6cc5ab833a44121bab71a49e682e6228e6131a80
[OpenSRF.git] / include / opensrf / osrf_application.h
1 #include <opensrf/utils.h>
2 #include <opensrf/log.h>
3 #include <opensrf/osrf_app_session.h>
4 #include <opensrf/osrf_hash.h>
5
6 #include <opensrf/osrf_json.h>
7 #include <stdio.h>
8 #include <dlfcn.h>
9
10
11 /**
12   All OpenSRF methods take the signature
13   int methodName( osrfMethodContext* );
14   If a negative number is returned, it means an unknown error occured and an exception
15   will be returned to the client automatically.
16   If a positive number is returned, it means that libopensrf should send a 'Request Complete'
17   message following any messages sent by the method.
18   If 0 is returned, it tells libopensrf that the method completed successfully and 
19   there is no need to send any further data to the client.
20   */
21
22
23
24 /** 
25   This macro verifies methods receive the correct parameters */
26 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
27         if(!d) return -1; \
28         if(!d->session) { osrfLogError( OSRF_LOG_MARK,  "Session is NULL in app reqeust" ); return -1; }\
29         if(!d->method) { osrfLogError( OSRF_LOG_MARK,  "Method is NULL in app reqeust" ); return -1; }\
30         if(d->method->argc) {\
31                 if(!d->params) { osrfLogError( OSRF_LOG_MARK,  "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
32                 if( d->params->type != JSON_ARRAY ) { \
33                         osrfLogError( OSRF_LOG_MARK,  "'params' is not a JSON array for method %s", d->method->name);\
34                         return -1; }\
35         }\
36         if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK,  "Method name is NULL"); return -1; } 
37
38 #ifdef OSRF_LOG_PARAMS 
39 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
40         _OSRF_METHOD_VERIFY_CONTEXT(d); \
41         char* __j = jsonObjectToJSON(d->params);\
42         if(__j) { \
43                 osrfLogInfo( OSRF_LOG_MARK,  "CALL:     %s %s - %s", d->session->remote_service, d->method->name, __j);\
44                 free(__j); \
45         } 
46 #else
47 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d); 
48 #endif
49
50
51
52 /* used internally to make sure the method description provided is OK */
53 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
54         if(!app) return -1; \
55         if(!d) return -1;\
56         if(!d->name) { osrfLogError( OSRF_LOG_MARK,  "No method name provided in description" ), return -1; } \
57         if(!d->symbol) { osrfLogError( OSRF_LOG_MARK,  "No method symbol provided in description" ), return -1; } \
58         if(!d->notes) d->notes = ""; \
59         if(!d->paramNotes) d->paramNotes = "";\
60         if(!d->returnNotes) d->returnNotes = "";
61
62
63
64
65 /* Some well known parameters */
66 #define OSRF_SYSMETHOD_INTROSPECT                               "opensrf.system.method"
67 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC                "opensrf.system.method.atomic"
68 #define OSRF_SYSMETHOD_INTROSPECT_ALL                   "opensrf.system.method.all"
69 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC    "opensrf.system.method.all.atomic"
70 #define OSRF_SYSMETHOD_ECHO                                             "opensrf.system.echo"
71 #define OSRF_SYSMETHOD_ECHO_ATOMIC                              "opensrf.system.echo.atomic"
72
73 #define OSRF_METHOD_SYSTEM                      1
74 #define OSRF_METHOD_STREAMING           2
75 #define OSRF_METHOD_ATOMIC                      4
76 #define OSRF_METHOD_CACHABLE            8
77
78         
79
80 struct _osrfApplicationStruct {
81         void* handle;                                                                   /* the lib handle */
82         osrfHash* methods;
83    void (*onExit) (void);
84 };
85 typedef struct _osrfApplicationStruct osrfApplication;
86
87
88 struct _osrfMethodStruct {
89         char* name;                                     /* the method name */
90         char* symbol;                           /* the symbol name (function) */
91         char* notes;                            /* public method documentation */
92         int argc;                                       /* how many args this method expects */
93         //char* paramNotes;                     /* Description of the params expected for this method */
94         int options;                            /* describes the various options for this method */
95         void* userData;                         /* You can put your weeeeeeed in it ... */
96
97         /*
98         int sysmethod;                          
99         int streaming;                          
100         int atomic;                                     
101         int cachable;                           
102         */
103 }; 
104 typedef struct _osrfMethodStruct osrfMethod;
105
106 struct _osrfMethodContextStruct {
107         osrfAppSession* session;        /* the current session */
108         osrfMethod* method;                     /* the requested method */      
109         jsonObject* params;                     /* the params to the method */
110         int request;                                    /* request id */
111         jsonObject* responses;          /* array of cached responses. */
112 };
113 typedef struct _osrfMethodContextStruct osrfMethodContext;
114
115
116
117 /** 
118   Register an application
119   @param appName The name of the application
120   @param soFile The library (.so) file that implements this application
121   @return 0 on success, -1 on error
122   */
123 int osrfAppRegisterApplication( const char* appName, const char* soFile );
124
125 /**
126   Register a method
127   Any method with  the OSRF_METHOD_STREAMING option set will have a ".atomic"
128   version of the method registered automatically
129   @param appName The name of the application that implements the method
130   @param methodName The fully qualified name of the method
131   @param symbolName The symbol name (function) that implements the method
132   @param notes Public documentation for this method.
133   @params argc The number of arguments this method expects 
134   @param streaming True if this is a streaming method that requires an atomic version
135   @return 0 on success, -1 on error
136   */
137 int osrfAppRegisterMethod( const char* appName, const char* methodName, 
138                 const char* symbolName, const char* notes, int argc, int options );
139
140
141 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName, 
142                 const char* symbolName, const char* notes, int argc, int options, void* );
143
144 /**
145   Finds the given method for the given app
146   @param appName The application
147   @param methodName The method to find
148   @return A method pointer or NULL if no such method 
149   exists for the given application
150   */
151 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
152
153 /**
154   Runs the specified method for the specified application.
155   @param appName The name of the application who's method to run
156   @param methodName The name of the method to run
157   @param ses The app session attached to this request
158   @params reqId The request id for this request
159   @param params The method parameters
160   */
161 int osrfAppRunMethod( const char* appName, const char* methodName, 
162                 osrfAppSession* ses, int reqId, jsonObject* params );
163
164 /**
165   Responds to the client with a method exception
166   @param ses The current session
167   @param request The request id
168   @param msg The debug message to send to the client
169   @return 0 on successfully sending of the message, -1 otherwise
170   */
171 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
172
173 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
174 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
175
176 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
177 //int osrfAppProcessMethodOptions( char* method );
178
179 /**
180  * Tells the backend process to run its child init function */
181 int osrfAppRunChildInit(const char* appname);
182 void osrfAppRunExitCode();
183
184