]> git.evergreen-ils.org Git - OpenSRF.git/blob - src/libstack/osrf_application.h
added a settings server client and test. made the global config object wrapped in...
[OpenSRF.git] / src / libstack / osrf_application.h
1 #include <stdio.h>
2 #include <dlfcn.h>
3 #include "opensrf/utils.h"
4 #include "opensrf/log.h"
5 #include "objson/object.h"
6 #include "osrf_app_session.h"
7 #include "osrf_hash.h"
8
9
10 /**
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.
19   */
20
21
22
23 /** 
24   This macro verifies methods receive the correct parameters */
25 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
26         if(!d) return -1; \
27         if(!d->session) { osrfLogError( OSRF_LOG_MARK,  "Session is NULL in app reqeust" ); return -1; }\
28         if(!d->method) { osrfLogError( OSRF_LOG_MARK,  "Method is NULL in app reqeust" ); return -1; }\
29         if(d->method->argc) {\
30                 if(!d->params) { osrfLogError( OSRF_LOG_MARK,  "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
31                 if( d->params->type != JSON_ARRAY ) { \
32                         osrfLogError( OSRF_LOG_MARK,  "'params' is not a JSON array for method %s", d->method->name);\
33                         return -1; }\
34         }\
35         if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK,  "Method name is NULL"); return -1; } 
36
37 #ifdef OSRF_LOG_PARAMS 
38 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
39         _OSRF_METHOD_VERIFY_CONTEXT(d); \
40         char* __j = jsonObjectToJSON(d->params);\
41         if(__j) { \
42                 osrfLogInfo( OSRF_LOG_MARK,  "CALL:     %s %s - %s", d->session->remote_service, d->method->name, __j);\
43                 free(__j); \
44         } 
45 #else
46 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d); 
47 #endif
48
49
50
51 /* used internally to make sure the method description provided is OK */
52 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
53         if(!app) return -1; \
54         if(!d) return -1;\
55         if(!d->name) { osrfLogError( OSRF_LOG_MARK,  "No method name provided in description" ), return -1; } \
56         if(!d->symbol) { osrfLogError( OSRF_LOG_MARK,  "No method symbol provided in description" ), return -1; } \
57         if(!d->notes) d->notes = ""; \
58         if(!d->paramNotes) d->paramNotes = "";\
59         if(!d->returnNotes) d->returnNotes = "";
60
61
62
63
64 /* Some well known parameters */
65 #define OSRF_SYSMETHOD_INTROSPECT                               "opensrf.system.method"
66 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC                "opensrf.system.method.atomic"
67 #define OSRF_SYSMETHOD_INTROSPECT_ALL                   "opensrf.system.method.all"
68 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC    "opensrf.system.method.all.atomic"
69 #define OSRF_SYSMETHOD_ECHO                                             "opensrf.system.echo"
70 #define OSRF_SYSMETHOD_ECHO_ATOMIC                              "opensrf.system.echo.atomic"
71
72 #define OSRF_METHOD_SYSTEM                      1
73 #define OSRF_METHOD_STREAMING           2
74 #define OSRF_METHOD_ATOMIC                      4
75 #define OSRF_METHOD_CACHABLE            8
76
77         
78
79 struct _osrfApplicationStruct {
80         void* handle;                                                                   /* the lib handle */
81         osrfHash* methods;
82    void (*onExit) (void);
83 };
84 typedef struct _osrfApplicationStruct osrfApplication;
85
86
87 struct _osrfMethodStruct {
88         char* name;                                     /* the method name */
89         char* symbol;                           /* the symbol name (function) */
90         char* notes;                            /* public method documentation */
91         int argc;                                       /* how many args this method expects */
92         //char* paramNotes;                     /* Description of the params expected for this method */
93         int options;                            /* describes the various options for this method */
94         void* userData;                         /* You can put your weeeeeeed in it ... */
95
96         /*
97         int sysmethod;                          
98         int streaming;                          
99         int atomic;                                     
100         int cachable;                           
101         */
102 }; 
103 typedef struct _osrfMethodStruct osrfMethod;
104
105 struct _osrfMethodContextStruct {
106         osrfAppSession* session;        /* the current session */
107         osrfMethod* method;                     /* the requested method */      
108         jsonObject* params;                     /* the params to the method */
109         int request;                                    /* request id */
110         jsonObject* responses;          /* array of cached responses. */
111 };
112 typedef struct _osrfMethodContextStruct osrfMethodContext;
113
114
115
116 /** 
117   Register an application
118   @param appName The name of the application
119   @param soFile The library (.so) file that implements this application
120   @return 0 on success, -1 on error
121   */
122 int osrfAppRegisterApplication( char* appName, char* soFile );
123
124 /**
125   Register a method
126   Any method with  the OSRF_METHOD_STREAMING option set will have a ".atomic"
127   version of the method registered automatically
128   @param appName The name of the application that implements the method
129   @param methodName The fully qualified name of the method
130   @param symbolName The symbol name (function) that implements the method
131   @param notes Public documentation for this method.
132   @params argc The number of arguments this method expects 
133   @param streaming True if this is a streaming method that requires an atomic version
134   @return 0 on success, -1 on error
135   */
136 int osrfAppRegisterMethod( char* appName, char* methodName, 
137                 char* symbolName, char* notes, int argc, int options );
138
139
140 int osrfAppRegisterExtendedMethod( char* appName, char* methodName, 
141                 char* symbolName, char* notes, int argc, int options, void* );
142
143 osrfMethod* _osrfAppBuildMethod( char* methodName, 
144                 char* symbolName, char* notes, int argc, int options, void* );
145
146 /**
147   Finds the given app in the list of apps
148   @param name The name of the application
149   @return The application pointer or NULL if there is no such application
150   */
151 osrfApplication* _osrfAppFindApplication( char* name );
152
153 /**
154   Finds the given method for the given app
155   @param appName The application
156   @param methodName The method to find
157   @return A method pointer or NULL if no such method 
158   exists for the given application
159   */
160 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
161
162 /**
163   Finds the given method for the given app
164   @param app The application object
165   @param methodName The method to find
166   @return A method pointer or NULL if no such method 
167   exists for the given application
168   */
169 osrfMethod* __osrfAppFindMethod( osrfApplication* app, char* methodName );
170
171
172 /**
173   Runs the specified method for the specified application.
174   @param appName The name of the application who's method to run
175   @param methodName The name of the method to run
176   @param ses The app session attached to this request
177   @params reqId The request id for this request
178   @param params The method parameters
179   */
180 int osrfAppRunMethod( char* appName, char* methodName, 
181                 osrfAppSession* ses, int reqId, jsonObject* params );
182
183
184 /**
185   Trys to run the requested method as a system method.
186   A system method is a well known method that all
187   servers implement.  
188   @param context The current method context
189   @return 0 if the method is run successfully, return < 0 means
190   the method was not run, return > 0 means the method was run
191   and the application code now needs to send a 'request complete' 
192   message
193   */
194 int __osrfAppRunSystemMethod(osrfMethodContext* context);
195
196 /**
197   Registers all of the system methods for this app so that they may be
198   treated the same as other methods */
199 int __osrfAppRegisterSysMethods( char* app );
200
201
202
203 /**
204   Responds to the client with a method exception
205   @param ses The current session
206   @param request The request id
207   @param msg The debug message to send to the client
208   @return 0 on successfully sending of the message, -1 otherwise
209   */
210 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );
211
212 int __osrfAppPostProcess( osrfMethodContext* context, int retcode );
213
214
215 int osrfAppRespond( osrfMethodContext* context, jsonObject* data );
216 int _osrfAppRespond( osrfMethodContext* context, jsonObject* data, int complete );
217 int osrfAppRespondComplete( osrfMethodContext* context, jsonObject* data );
218
219 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
220 //int osrfAppProcessMethodOptions( char* method );
221
222 int osrfAppIntrospect( osrfMethodContext* ctx );
223 int osrfAppIntrospectAll( osrfMethodContext* ctx );
224 int osrfAppEcho( osrfMethodContext* ctx );
225
226
227 /**
228  * Tells the backend process to run its child init function */
229 int osrfAppRunChildInit(char* appname);
230 void osrfAppSetOnExit(osrfApplication* app, char* appName);
231 void osrfAppRunExitCode();
232
233