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