3 #include "opensrf/utils.h"
4 #include "opensrf/log.h"
5 #include "objson/object.h"
6 #include "osrf_app_session.h"
11 All OpenSRF methods take the signature
12 int methodName( osrfMethodContext* );
13 If a negative number is returned, it means an unknown error occured and an exception
14 will be returned to the client automatically.
15 If a positive number is returned, it means that libopensrf should send a 'Request Complete'
16 message following any messages sent by the method.
17 If 0 is returned, it tells libopensrf that the method completed successfully and
18 there is no need to send any further data to the client.
24 This macro verifies methods receive the correct parameters */
25 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
27 if(!d->session) { osrfLogError( "Session is NULL in app reqeust" ); return -1; }\
28 if(!d->method) { osrfLogError( "Method is NULL in app reqeust" ); return -1; }\
29 if(!d->params) { osrfLogError( "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
30 if( d->params->type != JSON_ARRAY ) { \
31 osrfLogError( "'params' is not a JSON array for method %s", d->method->name);\
33 if( !d->method->name ) { osrfLogError( "Method name is NULL"); return -1; }
35 #ifdef OSRF_LOG_PARAMS
36 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
37 _OSRF_METHOD_VERIFY_CONTEXT(d); \
38 char* __j = jsonObjectToJSON(d->params);\
40 osrfLogInfo( "%s %s - %s", d->session->remote_service, d->method->name, __j);\
44 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
49 /* used internally to make sure the method description provided is OK */
50 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
53 if(!d->name) { osrfLogError( "No method name provided in description" ), return -1; } \
54 if(!d->symbol) { osrfLogError( "No method symbol provided in description" ), return -1; } \
55 if(!d->notes) d->notes = ""; \
56 if(!d->paramNotes) d->paramNotes = "";\
57 if(!d->returnNotes) d->returnNotes = "";
62 /* Some well known parameters */
63 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
64 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC "opensrf.system.method.atomic"
65 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
66 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC "opensrf.system.method.all.atomic"
67 #define OSRF_SYSMETHOD_ECHO "opensrf.system.echo"
68 #define OSRF_SYSMETHOD_ECHO_ATOMIC "opensrf.system.echo.atomic"
70 #define OSRF_METHOD_SYSTEM 1
71 #define OSRF_METHOD_STREAMING 2
72 #define OSRF_METHOD_ATOMIC 4
73 #define OSRF_METHOD_CACHABLE 8
77 struct _osrfApplicationStruct {
78 void* handle; /* the lib handle */
81 typedef struct _osrfApplicationStruct osrfApplication;
84 struct _osrfMethodStruct {
85 char* name; /* the method name */
86 char* symbol; /* the symbol name (function) */
87 char* notes; /* public method documentation */
88 int argc; /* how many args this method expects */
89 //char* paramNotes; /* Description of the params expected for this method */
90 int options; /* describes the various options for this method */
99 typedef struct _osrfMethodStruct osrfMethod;
101 struct _osrfMethodContextStruct {
102 osrfAppSession* session; /* the current session */
103 osrfMethod* method; /* the requested method */
104 jsonObject* params; /* the params to the method */
105 int request; /* request id */
106 jsonObject* responses; /* array of cached responses. */
108 typedef struct _osrfMethodContextStruct osrfMethodContext;
113 Register an application
114 @param appName The name of the application
115 @param soFile The library (.so) file that implements this application
116 @return 0 on success, -1 on error
118 int osrfAppRegisterApplication( char* appName, char* soFile );
122 Any method with the OSRF_METHOD_STREAMING option set will have a ".atomic"
123 version of the method registered automatically
124 @param appName The name of the application that implements the method
125 @param methodName The fully qualified name of the method
126 @param symbolName The symbol name (function) that implements the method
127 @param notes Public documentation for this method.
128 @params argc The number of arguments this method expects
129 @param streaming True if this is a streaming method that requires an atomic version
130 @return 0 on success, -1 on error
132 int osrfAppRegisterMethod( char* appName, char* methodName,
133 char* symbolName, char* notes, int argc, int options );
136 osrfMethod* _osrfAppBuildMethod( char* methodName,
137 char* symbolName, char* notes, int argc, int options );
140 Finds the given app in the list of apps
141 @param name The name of the application
142 @return The application pointer or NULL if there is no such application
144 osrfApplication* _osrfAppFindApplication( char* name );
147 Finds the given method for the given app
148 @param appName The application
149 @param methodName The method to find
150 @return A method pointer or NULL if no such method
151 exists for the given application
153 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
156 Finds the given method for the given app
157 @param app The application object
158 @param methodName The method to find
159 @return A method pointer or NULL if no such method
160 exists for the given application
162 osrfMethod* __osrfAppFindMethod( osrfApplication* app, char* methodName );
166 Runs the specified method for the specified application.
167 @param appName The name of the application who's method to run
168 @param methodName The name of the method to run
169 @param ses The app session attached to this request
170 @params reqId The request id for this request
171 @param params The method parameters
173 int osrfAppRunMethod( char* appName, char* methodName,
174 osrfAppSession* ses, int reqId, jsonObject* params );
178 Trys to run the requested method as a system method.
179 A system method is a well known method that all
181 @param context The current method context
182 @return 0 if the method is run successfully, return < 0 means
183 the method was not run, return > 0 means the method was run
184 and the application code now needs to send a 'request complete'
187 int __osrfAppRunSystemMethod(osrfMethodContext* context);
190 Registers all of the system methods for this app so that they may be
191 treated the same as other methods */
192 int __osrfAppRegisterSysMethods( char* app );
197 Responds to the client with a method exception
198 @param ses The current session
199 @param request The request id
200 @param msg The debug message to send to the client
201 @return 0 on successfully sending of the message, -1 otherwise
203 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );
205 int __osrfAppPostProcess( osrfMethodContext* context, int retcode );
208 int osrfAppRespond( osrfMethodContext* context, jsonObject* data );
209 int _osrfAppRespond( osrfMethodContext* context, jsonObject* data, int complete );
210 int osrfAppRespondComplete( osrfMethodContext* context, jsonObject* data );
212 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
213 //int osrfAppProcessMethodOptions( char* method );
215 int osrfAppIntrospect( osrfMethodContext* ctx );
216 int osrfAppIntrospectAll( osrfMethodContext* ctx );