include/opensrf/osrf_application.h

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