1 #ifndef OSRF_APPLICATION_H
2 #define OSRF_APPLICATION_H
5 @file osrf_application.h
6 @brief Routines to load and manage shared object libraries.
8 Every method of a service is implemented by a C function. In a few cases those
9 functions are generic to all services. In other cases they are loaded and executed from
10 a shared object library that is specific to the application offering the service, A
11 registry maps method names to function names so that we can call the right function.
13 Each such function has a similar signature:
15 int method_name( osrfMethodContext* ctx );
17 The return value is negative in case of an error. A return code of zero implies that
18 the method has already sent the client a STATUS message to say that it is finished.
19 A return code greater than zero implies that the method has not sent such a STATUS
20 message, so we need to do so after the method returns.
22 Any arguments passed to the method are bundled together in a jsonObject inside the
25 An application's shared object may also implement any or all of three standard functions:
27 - int osrfAppInitialize( void ) Called when an application is registered
28 - int osrfAppChildInit( void ) Called when a server drone is spawned
29 - void osrfAppChildExit( void ) Called when a server drone terminates
31 osrfAppInitialize() and osrfAppChild return zero if successful, and non-zero if not.
34 #include <opensrf/utils.h>
35 #include <opensrf/log.h>
36 #include <opensrf/osrf_app_session.h>
37 #include <opensrf/osrf_hash.h>
39 #include <opensrf/osrf_json.h>
48 All OpenSRF methods take the signature
49 int methodName( osrfMethodContext* );
50 If a negative number is returned, it means an unknown error occured and an exception
51 will be returned to the client automatically.
52 If a positive number is returned, it means that libopensrf should send a 'Request Complete'
53 message following any messages sent by the method.
54 If 0 is returned, it tells libopensrf that the method completed successfully and
55 there is no need to send any further data to the client.
58 /** This macro verifies that methods receive the correct parameters */
59 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
62 osrfLogError( OSRF_LOG_MARK, "Session is NULL in app request" ); \
66 osrfLogError( OSRF_LOG_MARK, "Method is NULL in app request" ); \
69 if(d->method->argc) { \
71 osrfLogError( OSRF_LOG_MARK, "Params is NULL in app request %s", d->method->name ); \
74 if( d->params->type != JSON_ARRAY ) { \
75 osrfLogError( OSRF_LOG_MARK, "'params' is not a JSON array for method %s", \
79 if( !d->method->name ) { \
80 osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); return -1; \
83 #ifdef OSRF_LOG_PARAMS
84 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
85 _OSRF_METHOD_VERIFY_CONTEXT(d); \
86 char* __j = jsonObjectToJSON(d->params); \
88 osrfLogInfo( OSRF_LOG_MARK, "CALL:\t%s %s - %s", d->session->remote_service, \
89 d->method->name, __j);\
93 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
98 @brief Macros that get OR'd together to form method options.
102 @brief Notes that the method may return more than one result.
104 For a @em streaming method, we register both an atomic method and a non-atomic method.
106 #define OSRF_METHOD_STREAMING 2
108 @brief Notes that a previous result to the same call may be available in memcache.
110 Before calling the registered function, a cachable method checks memcache for a previously
111 determined result for the same call. If no such result is available, it calls the
112 registered function and caches the new result before returning.
114 This caching is not currently implemented for C methods.
116 #define OSRF_METHOD_CACHABLE 8
120 char* name; /**< Method name. */
121 char* symbol; /**< Symbol name (function name) within the shared object. */
122 char* notes; /**< Public method documentation. */
123 int argc; /**< The minimum number of arguments for the method. */
124 //char* paramNotes; /**< Description of the params expected for this method. */
125 int options; /**< Bit switches setting various options for this method. */
126 void* userData; /**< Opaque pointer to application-specific data. */
127 size_t bufsize; /**< How big a buffer to use for non-atomic methods */
138 osrfAppSession* session; /**< Pointer to the current application session. */
139 osrfMethod* method; /**< Pointer to the requested method. */
140 jsonObject* params; /**< Parameters to the method. */
141 int request; /**< Request id. */
142 jsonObject* responses; /**< Array of cached responses. */
145 int osrfAppRegisterApplication( const char* appName, const char* soFile );
147 int osrfAppRegisterMethod( const char* appName, const char* methodName,
148 const char* symbolName, const char* notes, int argc, int options );
150 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
151 const char* symbolName, const char* notes, int argc, int options, void* );
153 int osrfMethodSetBufferSize( const char* appName, const char* methodName, size_t bufsize );
155 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
157 int osrfAppRunMethod( const char* appName, const char* methodName,
158 osrfAppSession* ses, int reqId, jsonObject* params );
160 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
162 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
164 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
166 int osrfAppRunChildInit(const char* appname);
168 void osrfAppRunExitCode( void );
170 int osrfMethodVerifyContext( osrfMethodContext* ctx );