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