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