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