1 #ifndef OSRF_APPLICATION_H
2 #define OSRF_APPLICATION_H
4 #include <opensrf/utils.h>
5 #include <opensrf/log.h>
6 #include <opensrf/osrf_app_session.h>
7 #include <opensrf/osrf_hash.h>
9 #include <opensrf/osrf_json.h>
18 All OpenSRF methods take the signature
19 int methodName( osrfMethodContext* );
20 If a negative number is returned, it means an unknown error occured and an exception
21 will be returned to the client automatically.
22 If a positive number is returned, it means that libopensrf should send a 'Request Complete'
23 message following any messages sent by the method.
24 If 0 is returned, it tells libopensrf that the method completed successfully and
25 there is no need to send any further data to the client.
31 This macro verifies methods receive the correct parameters */
32 #define OSRF_METHOD_VERIFY_CONTEXT_(x) \
34 osrfMethodContext* d = x; \
37 osrfLogError( OSRF_LOG_MARK, "Session is NULL in app reqeust" ); \
41 osrfLogError( OSRF_LOG_MARK, "Method is NULL in app reqeust" ); \
44 if(d->method->argc) { \
46 osrfLogError( OSRF_LOG_MARK, \
47 "Params is NULL in app reqeust %s", d->method->name ); \
50 if( d->params->type != JSON_ARRAY ) { \
51 osrfLogError( OSRF_LOG_MARK, \
52 "'params' is not a JSON array for method %s", d->method->name);\
55 if( !d->method->name ) { \
56 osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); \
61 #ifdef OSRF_LOG_PARAMS
62 #define OSRF_METHOD_VERIFY_CONTEXT(x) \
64 osrfMethodContext* d = x; \
65 OSRF_METHOD_VERIFY_CONTEXT_(d); \
66 char* _j = jsonObjectToJSON(d->params); \
68 osrfLogInfo( OSRF_LOG_MARK, \
69 "CALL: %s %s - %s", d->session->remote_service, d->method->name, _j); \
75 #define OSRF_METHOD_VERIFY_CONTEXT(d) OSRF_METHOD_VERIFY_CONTEXT_(d);
80 /* used internally to make sure the method description provided is OK */
81 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
84 if(!d->name) { osrfLogError( OSRF_LOG_MARK, "No method name provided in description" ), return -1; } \
85 if(!d->symbol) { osrfLogError( OSRF_LOG_MARK, "No method symbol provided in description" ), return -1; } \
86 if(!d->notes) d->notes = ""; \
87 if(!d->paramNotes) d->paramNotes = "";\
88 if(!d->returnNotes) d->returnNotes = "";
93 /* Some well known parameters */
94 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
95 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC "opensrf.system.method.atomic"
96 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
97 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC "opensrf.system.method.all.atomic"
98 #define OSRF_SYSMETHOD_ECHO "opensrf.system.echo"
99 #define OSRF_SYSMETHOD_ECHO_ATOMIC "opensrf.system.echo.atomic"
101 #define OSRF_METHOD_SYSTEM 1
102 #define OSRF_METHOD_STREAMING 2
103 #define OSRF_METHOD_ATOMIC 4
104 #define OSRF_METHOD_CACHABLE 8
108 struct _osrfApplicationStruct {
109 void* handle; /* the lib handle */
111 void (*onExit) (void);
113 typedef struct _osrfApplicationStruct osrfApplication;
116 struct _osrfMethodStruct {
117 char* name; /* the method name */
118 char* symbol; /* the symbol name (function) */
119 char* notes; /* public method documentation */
120 int argc; /* how many args this method expects */
121 //char* paramNotes; /* Description of the params expected for this method */
122 int options; /* describes the various options for this method */
123 void* userData; /* You can put your weeeeeeed in it ... */
132 typedef struct _osrfMethodStruct osrfMethod;
134 struct _osrfMethodContextStruct {
135 osrfAppSession* session; /* the current session */
136 osrfMethod* method; /* the requested method */
137 jsonObject* params; /* the params to the method */
138 int request; /* request id */
139 jsonObject* responses; /* array of cached responses. */
141 typedef struct _osrfMethodContextStruct osrfMethodContext;
146 Register an application
147 @param appName The name of the application
148 @param soFile The library (.so) file that implements this application
149 @return 0 on success, -1 on error
151 int osrfAppRegisterApplication( const char* appName, const char* soFile );
155 Any method with the OSRF_METHOD_STREAMING option set will have a ".atomic"
156 version of the method registered automatically
157 @param appName The name of the application that implements the method
158 @param methodName The fully qualified name of the method
159 @param symbolName The symbol name (function) that implements the method
160 @param notes Public documentation for this method.
161 @params argc The number of arguments this method expects
162 @param streaming True if this is a streaming method that requires an atomic version
163 @return 0 on success, -1 on error
165 int osrfAppRegisterMethod( const char* appName, const char* methodName,
166 const char* symbolName, const char* notes, int argc, int options );
169 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
170 const char* symbolName, const char* notes, int argc, int options, void* );
173 Finds the given method for the given app
174 @param appName The application
175 @param methodName The method to find
176 @return A method pointer or NULL if no such method
177 exists for the given application
179 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
182 Runs the specified method for the specified application.
183 @param appName The name of the application who's method to run
184 @param methodName The name of the method to run
185 @param ses The app session attached to this request
186 @params reqId The request id for this request
187 @param params The method parameters
189 int osrfAppRunMethod( const char* appName, const char* methodName,
190 osrfAppSession* ses, int reqId, jsonObject* params );
193 Responds to the client with a method exception
194 @param ses The current session
195 @param request The request id
196 @param msg The debug message to send to the client
197 @return 0 on successfully sending of the message, -1 otherwise
199 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
201 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
202 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
204 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
205 //int osrfAppProcessMethodOptions( char* method );
208 * Tells the backend process to run its child init function */
209 int osrfAppRunChildInit(const char* appname);
210 void osrfAppRunExitCode();