added "CALL" to the param debugging line for ease of grepping
[Evergreen.git] / OpenSRF / 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->params) { osrfLogError( OSRF_LOG_MARK,  "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
30         if( d->params->type != JSON_ARRAY ) { \
31                 osrfLogError( OSRF_LOG_MARK,  "'params' is not a JSON array for method %s", d->method->name);\
32                 return -1; }\
33         if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK,  "Method name is NULL"); return -1; } 
34
35 #ifdef OSRF_LOG_PARAMS 
36 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
37         _OSRF_METHOD_VERIFY_CONTEXT(d); \
38         char* __j = jsonObjectToJSON(d->params);\
39         if(__j) { \
40                 osrfLogInfo( OSRF_LOG_MARK,  "CALL:     %s %s - %s", d->session->remote_service, d->method->name, __j);\
41                 free(__j); \
42         } 
43 #else
44 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d); 
45 #endif
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) { osrfLogError( OSRF_LOG_MARK,  "No method name provided in description" ), return -1; } \
54         if(!d->symbol) { osrfLogError( OSRF_LOG_MARK,  "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
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"
69
70 #define OSRF_METHOD_SYSTEM                      1
71 #define OSRF_METHOD_STREAMING           2
72 #define OSRF_METHOD_ATOMIC                      4
73 #define OSRF_METHOD_CACHABLE            8
74
75         
76
77 struct _osrfApplicationStruct {
78         void* handle;                                                                   /* the lib handle */
79         osrfHash* methods;
80 };
81 typedef struct _osrfApplicationStruct osrfApplication;
82
83
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 */
91
92         /*
93         int sysmethod;                          
94         int streaming;                          
95         int atomic;                                     
96         int cachable;                           
97         */
98 }; 
99 typedef struct _osrfMethodStruct osrfMethod;
100
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. */
107 };
108 typedef struct _osrfMethodContextStruct osrfMethodContext;
109
110
111
112 /** 
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
117   */
118 int osrfAppRegisterApplication( char* appName, char* soFile );
119
120 /**
121   Register a method
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
131   */
132 int osrfAppRegisterMethod( char* appName, char* methodName, 
133                 char* symbolName, char* notes, int argc, int options );
134
135
136 osrfMethod* _osrfAppBuildMethod( char* methodName, 
137                 char* symbolName, char* notes, int argc, int options );
138
139 /**
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
143   */
144 osrfApplication* _osrfAppFindApplication( char* name );
145
146 /**
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
152   */
153 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
154
155 /**
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
161   */
162 osrfMethod* __osrfAppFindMethod( osrfApplication* app, char* methodName );
163
164
165 /**
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
172   */
173 int osrfAppRunMethod( char* appName, char* methodName, 
174                 osrfAppSession* ses, int reqId, jsonObject* params );
175
176
177 /**
178   Trys to run the requested method as a system method.
179   A system method is a well known method that all
180   servers implement.  
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' 
185   message
186   */
187 int __osrfAppRunSystemMethod(osrfMethodContext* context);
188
189 /**
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 );
193
194
195
196 /**
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
202   */
203 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );
204
205 int __osrfAppPostProcess( osrfMethodContext* context, int retcode );
206
207
208 int osrfAppRespond( osrfMethodContext* context, jsonObject* data );
209 int _osrfAppRespond( osrfMethodContext* context, jsonObject* data, int complete );
210 int osrfAppRespondComplete( osrfMethodContext* context, jsonObject* data );
211
212 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
213 //int osrfAppProcessMethodOptions( char* method );
214
215 int osrfAppIntrospect( osrfMethodContext* ctx );
216 int osrfAppIntrospectAll( osrfMethodContext* ctx );
217
218