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(d) \
34 if(!d->session) { osrfLogError( OSRF_LOG_MARK, "Session is NULL in app reqeust" ); return -1; }\
35 if(!d->method) { osrfLogError( OSRF_LOG_MARK, "Method is NULL in app reqeust" ); return -1; }\
36 if(d->method->argc) {\
37 if(!d->params) { osrfLogError( OSRF_LOG_MARK, "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
38 if( d->params->type != JSON_ARRAY ) { \
39 osrfLogError( OSRF_LOG_MARK, "'params' is not a JSON array for method %s", d->method->name);\
42 if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); return -1; }
44 #ifdef OSRF_LOG_PARAMS
45 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
46 _OSRF_METHOD_VERIFY_CONTEXT(d); \
47 char* __j = jsonObjectToJSON(d->params);\
49 osrfLogInfo( OSRF_LOG_MARK, "CALL: %s %s - %s", d->session->remote_service, d->method->name, __j);\
53 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
58 /* used internally to make sure the method description provided is OK */
59 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
62 if(!d->name) { osrfLogError( OSRF_LOG_MARK, "No method name provided in description" ), return -1; } \
63 if(!d->symbol) { osrfLogError( OSRF_LOG_MARK, "No method symbol provided in description" ), return -1; } \
64 if(!d->notes) d->notes = ""; \
65 if(!d->paramNotes) d->paramNotes = "";\
66 if(!d->returnNotes) d->returnNotes = "";
71 /* Some well known parameters */
72 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
73 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC "opensrf.system.method.atomic"
74 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
75 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC "opensrf.system.method.all.atomic"
76 #define OSRF_SYSMETHOD_ECHO "opensrf.system.echo"
77 #define OSRF_SYSMETHOD_ECHO_ATOMIC "opensrf.system.echo.atomic"
79 #define OSRF_METHOD_SYSTEM 1
80 #define OSRF_METHOD_STREAMING 2
81 #define OSRF_METHOD_ATOMIC 4
82 #define OSRF_METHOD_CACHABLE 8
86 struct _osrfApplicationStruct {
87 void* handle; /* the lib handle */
89 void (*onExit) (void);
91 typedef struct _osrfApplicationStruct osrfApplication;
94 struct _osrfMethodStruct {
95 char* name; /* the method name */
96 char* symbol; /* the symbol name (function) */
97 char* notes; /* public method documentation */
98 int argc; /* how many args this method expects */
99 //char* paramNotes; /* Description of the params expected for this method */
100 int options; /* describes the various options for this method */
101 void* userData; /* You can put your weeeeeeed in it ... */
110 typedef struct _osrfMethodStruct osrfMethod;
112 struct _osrfMethodContextStruct {
113 osrfAppSession* session; /* the current session */
114 osrfMethod* method; /* the requested method */
115 jsonObject* params; /* the params to the method */
116 int request; /* request id */
117 jsonObject* responses; /* array of cached responses. */
119 typedef struct _osrfMethodContextStruct osrfMethodContext;
124 Register an application
125 @param appName The name of the application
126 @param soFile The library (.so) file that implements this application
127 @return 0 on success, -1 on error
129 int osrfAppRegisterApplication( const char* appName, const char* soFile );
133 Any method with the OSRF_METHOD_STREAMING option set will have a ".atomic"
134 version of the method registered automatically
135 @param appName The name of the application that implements the method
136 @param methodName The fully qualified name of the method
137 @param symbolName The symbol name (function) that implements the method
138 @param notes Public documentation for this method.
139 @params argc The number of arguments this method expects
140 @param streaming True if this is a streaming method that requires an atomic version
141 @return 0 on success, -1 on error
143 int osrfAppRegisterMethod( const char* appName, const char* methodName,
144 const char* symbolName, const char* notes, int argc, int options );
147 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
148 const char* symbolName, const char* notes, int argc, int options, void* );
151 Finds the given method for the given app
152 @param appName The application
153 @param methodName The method to find
154 @return A method pointer or NULL if no such method
155 exists for the given application
157 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
160 Runs the specified method for the specified application.
161 @param appName The name of the application who's method to run
162 @param methodName The name of the method to run
163 @param ses The app session attached to this request
164 @params reqId The request id for this request
165 @param params The method parameters
167 int osrfAppRunMethod( const char* appName, const char* methodName,
168 osrfAppSession* ses, int reqId, jsonObject* params );
171 Responds to the client with a method exception
172 @param ses The current session
173 @param request The request id
174 @param msg The debug message to send to the client
175 @return 0 on successfully sending of the message, -1 otherwise
177 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
179 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
180 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
182 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
183 //int osrfAppProcessMethodOptions( char* method );
186 * Tells the backend process to run its child init function */
187 int osrfAppRunChildInit(const char* appname);
188 void osrfAppRunExitCode();