451450b146d3e2c27170a75d10a2a90659c520d9
[working/Evergreen.git] / OpenSRF / src / libstack / osrf_application.h
1 #include <stdio.h>
2 #include <dlfcn.h>
3 #include "opensrf/utils.h"
4 #include "opensrf/logging.h"
5 #include "objson/object.h"
6 #include "osrf_app_session.h"
7
8
9 /**
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.
18   */
19
20
21
22 /** 
23   This macro verifies methods receive the correct parameters */
24 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
25         if(!d) return -1; \
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);\
31                 return -1; }\
32         if( !d->method->name ) { osrfLog(OSRF_ERROR, "Method name is NULL"); return -1; } 
33
34 #ifdef OSRF_LOG_PARAMS 
35 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
36         _OSRF_METHOD_VERIFY_CONTEXT(d); \
37         char* __j = jsonObjectToJSON(d->params);\
38         if(__j) { \
39                 osrfLog( OSRF_INFO, "[%s:%s] params: %s", d->session->remote_service, d->method->name, __j);\
40                 free(__j); \
41         } 
42 #else
43 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d); 
44 #endif
45
46
47
48
49 /* used internally to make sure the method description provided is OK */
50 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
51         if(!app) return -1; \
52         if(!d) return -1;\
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 = "";
58
59
60
61 /* Some well known parameters */
62 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
63 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
64
65         
66
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 */
72 };
73 typedef struct _osrfApplicationStruct osrfApplication;
74
75
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 */
84 }; 
85 typedef struct _osrfMethodStruct osrfMethod;
86
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 */
92 };
93 typedef struct _osrfMethodContextStruct osrfMethodContext;
94
95
96
97 /** 
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
102   */
103 int osrfAppRegisterApplication( char* appName, char* soFile );
104
105 /**
106   Register a method
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
114   */
115 int osrfAppRegisterMethod( char* appName, 
116                 char* methodName, char* symbolName, char* notes, char* params, int argc );
117
118 int _osrfAppRegisterSystemMethod( char* appName, char* methodName, 
119                 char* notes, char* params, int argc );
120
121 osrfMethod* _osrfAppBuildMethod( char* methodName, 
122                 char* symbolName, char* notes, char* params, int argc, int sysmethod );
123
124 /**
125   Registher a method
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
129   */
130 /*
131 int osrfAppRegisterMethod( char* appName, osrfMethodDescription* desc );
132 */
133
134 /**
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
138   */
139 osrfApplication* _osrfAppFindApplication( char* name );
140
141 /**
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
147   */
148 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
149
150 /**
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
156   */
157 osrfMethod* __osrfAppFindMethod( osrfApplication* app, char* methodName );
158
159
160 /**
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
167   */
168 int osrfAppRunMethod( char* appName, char* methodName, 
169                 osrfAppSession* ses, int reqId, jsonObject* params );
170
171
172 /**
173   Trys to run the requested method as a system method.
174   A system method is a well known method that all
175   servers implement.  
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' 
180   message
181   */
182 int __osrfAppRunSystemMethod(osrfMethodContext* context);
183
184 /**
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 );
188
189
190
191 /**
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
197   */
198 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );
199
200