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