include/opensrf/osrf_app_session.h

   1 /**
   2         @file osrf_app_session.h
   3         @brief Header for osrfAppSession.
   4 */
   5
   6 #ifndef OSRF_APP_SESSION_H
   7 #define OSRF_APP_SESSION_H
   8
   9 #include "opensrf/transport_client.h"
  10 #include "opensrf/osrf_message.h"
  11 #include "opensrf/osrf_system.h"
  12 #include "opensrf/string_array.h"
  13 #include "opensrf/osrfConfig.h"
  14 #include "opensrf/osrf_hash.h"
  15 #include "opensrf/osrf_list.h"
  16 #include "opensrf/osrf_json.h"
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 #define DEF_RECV_TIMEOUT 6 /* receive timeout */
  23 #define DEF_QUEUE_SIZE
  24
  25 enum OSRF_SESSION_STATE {
  26         OSRF_SESSION_CONNECTING,
  27         OSRF_SESSION_CONNECTED,
  28         OSRF_SESSION_DISCONNECTED
  29 };
  30
  31 enum OSRF_SESSION_TYPE {
  32         OSRF_SESSION_SERVER,
  33         OSRF_SESSION_CLIENT
  34 };
  35
  36 /**
  37         @brief Representation of a session with another application.
  38
  39         An osrfAppSession is a list of lists.  It includes a list of osrfAppRequests
  40         representing outstanding requests.  Each osrfAppRequest includes a list of
  41         responses.
  42 */
  43 struct osrf_app_session_struct {
  44
  45         /** Our messag passing object */
  46         transport_client* transport_handle;
  47         /** Cache of active app_request objects */
  48         osrfList* request_queue;
  49
  50         /** The original remote id of the remote service we're talking to */
  51         char* orig_remote_id;
  52         /** The current remote id of the remote service we're talking to */
  53         char* remote_id;
  54
  55         /** Whom we're talking to if we're a client;
  56                 what app we're serving if we're a server */
  57         char* remote_service;
  58
  59         /** The current request thread_trace */
  60         int thread_trace;
  61         /** Our ID */
  62         char* session_id;
  63
  64         /* true if this session does not require connect messages */
  65         int stateless;
  66
  67         /** The connect state */
  68         enum OSRF_SESSION_STATE state;
  69
  70         /** SERVER or CLIENT */
  71         enum OSRF_SESSION_TYPE type;
  72
  73         /** the current locale for this session **/
  74         char* session_locale;
  75
  76         /* let the user use the session to store their own session data */
  77         void* userData;
  78
  79         void (*userDataFree) (void*);
  80
  81     int transport_error;
  82 };
  83 typedef struct osrf_app_session_struct osrfAppSession;
  84
  85
  86
  87 // --------------------------------------------------------------------------
  88 // PUBLIC API ***
  89 // --------------------------------------------------------------------------
  90
  91 /** Allocates a initializes a new app_session */
  92 osrfAppSession* osrfAppSessionClientInit( const char* remote_service );
  93
  94 /** Allocates and initializes a new server session.  The global session cache
  95         is checked to see if this session already exists, if so, it's returned
  96 */
  97 osrfAppSession* osrf_app_server_session_init(
  98                 const char* session_id, const char* our_app, const char* remote_id );
  99
 100 /** sets the default locale for a session **/
 101 char* osrf_app_session_set_locale( osrfAppSession*, const char* );
 102
 103 /** returns a session from the global session hash */
 104 osrfAppSession* osrf_app_session_find_session( const char* session_id );
 105
 106 /** Builds a new app_request object with the given payload and returns
 107         the id of the request.  This id is then used to perform work on the
 108         request.  DEPRECATED; use osrfAppSessionSendRequest() instead.
 109 */
 110 int osrfAppSessionMakeRequest(
 111                 osrfAppSession* session, const jsonObject* params,
 112                 const char* method_name, int protocol, osrfStringArray* param_strings);
 113
 114 /** Builds a new app_request object with the given payload and returns
 115         the id of the request.  This id is then used to perform work on the
 116         request.
 117  */
 118 int osrfAppSessionSendRequest(
 119                  osrfAppSession* session, const jsonObject* params,
 120                  const char* method_name, int protocol );
 121
 122 /** Sets the given request to complete state */
 123 void osrf_app_session_set_complete( osrfAppSession* session, int request_id );
 124
 125 /** Returns true if the given request is complete */
 126 int osrf_app_session_request_complete( const osrfAppSession* session, int request_id );
 127
 128 /** Does a recv call on the given request */
 129 osrfMessage* osrfAppSessionRequestRecv(
 130                 osrfAppSession* session, int request_id, int timeout );
 131
 132 /** Removes the request from the request set and frees the reqest */
 133 void osrf_app_session_request_finish( osrfAppSession* session, int request_id );
 134
 135 /** Resends the orginal request with the given request id */
 136 int osrf_app_session_request_resend( osrfAppSession*, int request_id );
 137
 138 /** Resets the remote connection target to that of the original*/
 139 void osrf_app_session_reset_remote( osrfAppSession* );
 140
 141 /** Sets the remote target to 'remote_id' */
 142 void osrf_app_session_set_remote( osrfAppSession* session, const char* remote_id );
 143
 144 /** pushes the given message into the result list of the app_request
 145         whose request_id matches the messages thread_trace
 146 */
 147 int osrf_app_session_push_queue( osrfAppSession*, osrfMessage* msg );
 148
 149 /** Attempts to connect to the remote service. Returns 1 on successful
 150         connection, 0 otherwise.
 151 */
 152 int osrfAppSessionConnect( osrfAppSession* );
 153
 154 /** Sends a disconnect message to the remote service.  No response is expected */
 155 int osrf_app_session_disconnect( osrfAppSession* );
 156
 157 /** Waits up to 'timeout' seconds for some data to arrive.
 158         Any data that arrives will be processed according to its
 159         payload and message type.  This method will return after
 160         any data has arrived.
 161 */
 162 int osrf_app_session_queue_wait( osrfAppSession*, int timeout, int* recvd );
 163
 164 /** Disconnects (if client), frees any attached app_reuqests, removes the session from the
 165         global session cache and frees the session.  Needless to say, only call this when the
 166         session is completely done.
 167 */
 168 void osrfAppSessionFree( osrfAppSession* );
 169
 170 /** Tells the request to reset its wait timeout */
 171 void osrf_app_session_request_reset_timeout( osrfAppSession* session, int req_id );
 172
 173 int osrfAppRequestRespond( osrfAppSession* ses, int requestId, const jsonObject* data );
 174 int osrfAppRequestRespondComplete(
 175                 osrfAppSession* ses, int requestId, const jsonObject* data );
 176
 177 int osrfAppSessionStatus( osrfAppSession* ses, int type,
 178                 const char* name, int reqId, const char* message );
 179
 180 void osrfAppSessionCleanup( void );
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif
 185
 186 #endif