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