3 #include "opensrf/utils.h"
4 #include "opensrf/logging.h"
5 #include "objson/object.h"
6 #include "osrf_app_session.h"
10 All OpenSRF methods take the signature
11 int methodName( osrfMethodContext* );
12 If a negative number is returned, it means an unknown error occured and an exception
13 will be returned to the client automatically.
14 If a positive number is returned, it means that libopensrf should send a 'Request Complete'
15 message following any messages sent by the method.
16 If 0 is returned, it tells libopensrf that the method completed successfully and
17 there is no need to send any further data to the client.
23 This macro verifies methods receive the correct parameters */
24 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
26 if(!d->session) { osrfLog( OSRF_ERROR, "Session is NULL in app reqeust" ); return -1; }\
27 if(!d->method) { osrfLog( OSRF_ERROR, "Method is NULL in app reqeust" ); return -1; }\
28 if(!d->params) { osrfLog( OSRF_ERROR, "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
29 if( d->params->type != JSON_ARRAY ) { \
30 osrfLog( OSRF_ERROR, "'params' is not a JSON array for method %s", d->method->name);\
32 if( !d->method->name ) { osrfLog(OSRF_ERROR, "Method name is NULL"); return -1; }
34 #ifdef OSRF_LOG_PARAMS
35 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
36 _OSRF_METHOD_VERIFY_CONTEXT(d); \
37 char* __j = jsonObjectToJSON(d->params);\
39 osrfLog( OSRF_INFO, "[%s:%s] params: %s", d->session->remote_service, d->method->name, __j);\
43 #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) { osrfLog( OSRF_ERROR, "No method name provided in description" ), return -1; } \
54 if(!d->symbol) { osrfLog( OSRF_ERROR, "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 = "";
61 /* Some well known parameters */
62 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
63 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
67 struct _osrfApplicationStruct {
68 char* name; /* the name of our application */
69 void* handle; /* the lib handle */
70 struct _osrfMethodStruct* methods; /* list of methods */
71 struct _osrfApplicationStruct* next; /* next application */
73 typedef struct _osrfApplicationStruct osrfApplication;
76 struct _osrfMethodStruct {
77 char* name; /* the method name */
78 char* symbol; /* the symbol name (function) */
79 char* notes; /* public method documentation */
80 int argc; /* how many args this method expects */
81 char* paramNotes; /* Description of the params expected for this method */
82 struct _osrfMethodStruct* next; /* nest method in the list */
83 int sysmethod; /* true if this is a system method */
85 typedef struct _osrfMethodStruct osrfMethod;
87 struct _osrfMethodContextStruct {
88 osrfAppSession* session; /* the current session */
89 osrfMethod* method; /* the requested method */
90 jsonObject* params; /* the params to the method */
91 int request; /* request id */
93 typedef struct _osrfMethodContextStruct osrfMethodContext;
98 Register an application
99 @param appName The name of the application
100 @param soFile The library (.so) file that implements this application
101 @return 0 on success, -1 on error
103 int osrfAppRegisterApplication( char* appName, char* soFile );
107 @param appName The name of the application that implements the method
108 @param methodName The fully qualified name of the method
109 @param symbolName The symbol name (function) that implements the method
110 @param notes Public documentation for this method.
111 @params params String description description of the params expected
112 @params argc The number of arguments this method expects
113 @return 0 on success, -1 on error
115 int osrfAppRegisterMethod( char* appName,
116 char* methodName, char* symbolName, char* notes, char* params, int argc );
118 int _osrfAppRegisterSystemMethod( char* appName, char* methodName,
119 char* notes, char* params, int argc );
121 osrfMethod* _osrfAppBuildMethod( char* methodName,
122 char* symbolName, char* notes, char* params, int argc, int sysmethod );
126 @param appName The name of the application that implements the method
127 @params desc The method description
128 @return 0 on success, -1 on error
131 int osrfAppRegisterMethod( char* appName, osrfMethodDescription* desc );
135 Finds the given app in the list of apps
136 @param name The name of the application
137 @return The application pointer or NULL if there is no such application
139 osrfApplication* _osrfAppFindApplication( char* name );
142 Finds the given method for the given app
143 @param appName The application
144 @param methodName The method to find
145 @return A method pointer or NULL if no such method
146 exists for the given application
148 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
151 Finds the given method for the given app
152 @param app The application object
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( osrfApplication* app, char* methodName );
161 Runs the specified method for the specified application.
162 @param appName The name of the application who's method to run
163 @param methodName The name of the method to run
164 @param ses The app session attached to this request
165 @params reqId The request id for this request
166 @param params The method parameters
168 int osrfAppRunMethod( char* appName, char* methodName,
169 osrfAppSession* ses, int reqId, jsonObject* params );
173 Trys to run the requested method as a system method.
174 A system method is a well known method that all
176 @param context The current method context
177 @return 0 if the method is run successfully, return < 0 means
178 the method was not run, return > 0 means the method was run
179 and the application code now needs to send a 'request complete'
182 int __osrfAppRunSystemMethod(osrfMethodContext* context);
185 Registers all of the system methods for this app so that they may be
186 treated the same as other methods */
187 int __osrfAppRegisterSysMethods( char* app );
192 Responds to the client with a method exception
193 @param ses The current session
194 @param request The request id
195 @param msg The debug message to send to the client
196 @return 0 on successfully sending of the message, -1 otherwise
198 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );