d635323b205c8cfd7a2db9ecbb6715af8d40eff0
[OpenSRF.git] / 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 enum OSRF_SESSION_STATE {
23         OSRF_SESSION_CONNECTING,
24         OSRF_SESSION_CONNECTED,
25         OSRF_SESSION_DISCONNECTED
26 };
27
28 enum OSRF_SESSION_TYPE {
29         OSRF_SESSION_SERVER,
30         OSRF_SESSION_CLIENT
31 };
32
33 struct osrf_app_request_struct;
34 typedef struct osrf_app_request_struct osrfAppRequest;
35
36 #define OSRF_REQUEST_HASH_SIZE 64
37
38 /**
39         @brief Default size of output buffer.
40 */
41 #define OSRF_MSG_BUNDLE_SIZE 25600 /* 25K */
42 #define OSRF_MSG_CHUNK_SIZE  (OSRF_MSG_BUNDLE_SIZE * 2)
43
44 /**
45         @brief Representation of a session with another application.
46
47         An osrfAppSession is a list of lists.  It includes a list of osrfAppRequests
48         representing outstanding requests.  Each osrfAppRequest includes a list of
49         responses.
50 */
51 struct osrf_app_session_struct {
52
53         /** Our message passing object */
54         transport_client* transport_handle;
55
56         /** The original remote id of the remote service we're talking to */
57         char* orig_remote_id;
58         /** The current remote id of the remote service we're talking to */
59         char* remote_id;
60
61         /** Whom we're talking to if we're a client;
62                 what app we're serving if we're a server */
63         char* remote_service;
64
65         /** The current request thread_trace */
66         int thread_trace;
67         /** Our ID */
68         char* session_id;
69
70         /** Boolean; true if this session does not require connect messages.
71             Assigned a value depending on the compile-time macro ASSUME_STATELESS. */
72         int stateless;
73
74         /** The connect state */
75         enum OSRF_SESSION_STATE state;
76
77         /** SERVER or CLIENT */
78         enum OSRF_SESSION_TYPE type;
79
80         /** the current locale for this session. **/
81         char* session_locale;
82
83         /** the current TZ for this session. **/
84         char* session_tz;
85
86         /** let the user use the session to store their own session data. */
87         void* userData;
88
89         /** Callback function for freeing user's session data. */
90         void (*userDataFree) (void*);
91
92         int transport_error;
93
94         /** Hash table of pending requests. */
95         osrfAppRequest* request_hash[ OSRF_REQUEST_HASH_SIZE ];
96
97         /** Boolean: true if the app wants to terminate the process.  Typically this means that */
98         /** a drone has lost its database connection and can therefore no longer function.      */
99         int panic;
100
101         /** Buffer used by server drone to collect outbound response messages */
102         growing_buffer* outbuf;
103 };
104 typedef struct osrf_app_session_struct osrfAppSession;
105
106 // --------------------------------------------------------------------------
107 // PUBLIC API ***
108 // --------------------------------------------------------------------------
109
110 osrfAppSession* osrfAppSessionClientInit( const char* remote_service );
111
112 osrfAppSession* osrf_app_server_session_init(
113                 const char* session_id, const char* our_app, const char* remote_id );
114
115 char* osrf_app_session_set_locale( osrfAppSession*, const char* );
116
117 char* osrf_app_session_set_tz( osrfAppSession*, const char* );
118
119 /* ingress used by all sessions until replaced */
120 char* osrfAppSessionSetIngress( const char* );
121
122 const char* osrfAppSessionGetIngress();
123
124 osrfAppSession* osrf_app_session_find_session( const char* session_id );
125
126 /* DEPRECATED; use osrfAppSessionSendRequest() instead. */
127 int osrfAppSessionMakeRequest(
128                 osrfAppSession* session, const jsonObject* params,
129                 const char* method_name, int protocol, osrfStringArray* param_strings);
130
131 int osrfAppSessionSendRequest(
132                  osrfAppSession* session, const jsonObject* params,
133                  const char* method_name, int protocol );
134
135 void osrf_app_session_set_complete( osrfAppSession* session, int request_id );
136
137 int osrf_app_session_request_complete( const osrfAppSession* session, int request_id );
138
139 osrfMessage* osrfAppSessionRequestRecv(
140                 osrfAppSession* session, int request_id, int timeout );
141
142 void osrf_app_session_request_finish( osrfAppSession* session, int request_id );
143
144 int osrf_app_session_request_resend( osrfAppSession*, int request_id );
145
146 int osrfSendTransportPayload( osrfAppSession* session, const char* payload );
147
148 void osrf_app_session_reset_remote( osrfAppSession* );
149
150 void osrf_app_session_set_remote( osrfAppSession* session, const char* remote_id );
151
152 void osrf_app_session_push_queue( osrfAppSession*, osrfMessage* msg );
153
154 int osrfAppSessionConnect( osrfAppSession* );
155
156 int osrf_app_session_disconnect( osrfAppSession* );
157
158 int osrf_app_session_queue_wait( osrfAppSession*, int timeout, int* recvd );
159
160 void osrfAppSessionFree( osrfAppSession* );
161
162 void osrf_app_session_request_reset_timeout( osrfAppSession* session, int req_id );
163
164 int osrfAppRequestRespond( osrfAppSession* ses, int requestId, const jsonObject* data );
165
166 int osrfAppRequestRespondComplete(
167                 osrfAppSession* ses, int requestId, const jsonObject* data );
168
169 int osrfAppSessionStatus( osrfAppSession* ses, int type,
170                 const char* name, int reqId, const char* message );
171
172 void osrfAppSessionCleanup( void );
173
174 void osrfAppSessionPanic( osrfAppSession* ses );
175
176 #ifdef __cplusplus
177 }
178 #endif
179
180 #endif