src/libstack/osrf_application.h

   1 #include <stdio.h>
   2 #include <dlfcn.h>
   3 #include "opensrf/utils.h"
   4 #include "opensrf/logging.h"
   5 #include "objson/object.h"
   6 #include "osrf_app_session.h"
   7
   8
   9 /**
  10   All OpenSRF methods take the signature
  11   int methodName( osrfMethodContext* );
  12   If a negative number is returned, it means an unknown error occured and an exception
  13   will be returned to the client automatically.
  14   If a positive number is returned, it means that libopensrf should send a 'Request Complete'
  15   message following any messages sent by the method.
  16   If 0 is returned, it tells libopensrf that the method completed successfully and
  17   there is no need to send any further data to the client.
  18   */
  19
  20
  21
  22 /**
  23   This macro verifies methods receive the correct parameters */
  24 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
  25         if(!d) return -1; \
  26         if(!d->session) { osrfLog( OSRF_ERROR, "Session is NULL in app reqeust" ); return -1; }\
  27         if(!d->method) { osrfLog( OSRF_ERROR, "Method is NULL in app reqeust" ); return -1; }\
  28         if(!d->params) { osrfLog( OSRF_ERROR, "Params is NULL in app reqeust %s", d->method->name ); return -1; }\
  29         if( d->params->type != JSON_ARRAY ) { \
  30                 osrfLog( OSRF_ERROR, "'params' is not a JSON array for method %s", d->method->name);\
  31                 return -1; }\
  32         if( !d->method->name ) { osrfLog(OSRF_ERROR, "Method name is NULL"); return -1; }
  33
  34 #ifdef OSRF_LOG_PARAMS
  35 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
  36         _OSRF_METHOD_VERIFY_CONTEXT(d); \
  37         char* __j = jsonObjectToJSON(d->params);\
  38         if(__j) { \
  39                 osrfLog( OSRF_INFO, "[%s:%s] params: %s", d->session->remote_service, d->method->name, __j);\
  40                 free(__j); \
  41         }
  42 #else
  43 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
  44 #endif
  45
  46
  47
  48
  49 /* used internally to make sure the method description provided is OK */
  50 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
  51         if(!app) return -1; \
  52         if(!d) return -1;\
  53         if(!d->name) { osrfLog( OSRF_ERROR, "No method name provided in description" ), return -1; } \
  54         if(!d->symbol) { osrfLog( OSRF_ERROR, "No method symbol provided in description" ), return -1; } \
  55         if(!d->notes) d->notes = ""; \
  56         if(!d->paramNotes) d->paramNotes = "";\
  57         if(!d->returnNotes) d->returnNotes = "";
  58
  59
  60
  61 /* Some well known parameters */
  62 #define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
  63 #define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
  64
  65
  66
  67 struct _osrfApplicationStruct {
  68         char* name;                                                                             /* the name of our application */
  69         void* handle;                                                                   /* the lib handle */
  70         struct _osrfMethodStruct* methods;              /* list of methods */
  71         struct _osrfApplicationStruct* next;    /* next application */
  72 };
  73 typedef struct _osrfApplicationStruct osrfApplication;
  74
  75
  76 struct _osrfMethodStruct {
  77         char* name;                                     /* the method name */
  78         char* symbol;                           /* the symbol name (function) */
  79         char* notes;                            /* public method documentation */
  80         int argc;                                       /* how many args this method expects */
  81         char* paramNotes;                       /* Description of the params expected for this method */
  82         struct _osrfMethodStruct* next; /* nest method in the list */
  83         int sysmethod;                          /* true if this is a system method */
  84 };
  85 typedef struct _osrfMethodStruct osrfMethod;
  86
  87 struct _osrfMethodContextStruct {
  88         osrfAppSession* session;        /* the current session */
  89         osrfMethod* method;                     /* the requested method */
  90         jsonObject* params;                     /* the params to the method */
  91         int request;                                    /* request id */
  92 };
  93 typedef struct _osrfMethodContextStruct osrfMethodContext;
  94
  95
  96
  97 /**
  98   Register an application
  99   @param appName The name of the application
 100   @param soFile The library (.so) file that implements this application
 101   @return 0 on success, -1 on error
 102   */
 103 int osrfAppRegisterApplication( char* appName, char* soFile );
 104
 105 /**
 106   Register a method
 107   @param appName The name of the application that implements the method
 108   @param methodName The fully qualified name of the method
 109   @param symbolName The symbol name (function) that implements the method
 110   @param notes Public documentation for this method.
 111   @params params String description description of the params expected
 112   @params argc The number of arguments this method expects
 113   @return 0 on success, -1 on error
 114   */
 115 int osrfAppRegisterMethod( char* appName,
 116                 char* methodName, char* symbolName, char* notes, char* params, int argc );
 117
 118 int _osrfAppRegisterSystemMethod( char* appName, char* methodName,
 119                 char* notes, char* params, int argc );
 120
 121 osrfMethod* _osrfAppBuildMethod( char* methodName,
 122                 char* symbolName, char* notes, char* params, int argc, int sysmethod );
 123
 124 /**
 125   Registher a method
 126   @param appName The name of the application that implements the method
 127   @params desc The method description
 128   @return 0 on success, -1 on error
 129   */
 130 /*
 131 int osrfAppRegisterMethod( char* appName, osrfMethodDescription* desc );
 132 */
 133
 134 /**
 135   Finds the given app in the list of apps
 136   @param name The name of the application
 137   @return The application pointer or NULL if there is no such application
 138   */
 139 osrfApplication* _osrfAppFindApplication( char* name );
 140
 141 /**
 142   Finds the given method for the given app
 143   @param appName The application
 144   @param methodName The method to find
 145   @return A method pointer or NULL if no such method
 146   exists for the given application
 147   */
 148 osrfMethod* _osrfAppFindMethod( char* appName, char* methodName );
 149
 150 /**
 151   Finds the given method for the given app
 152   @param app The application object
 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( osrfApplication* app, char* methodName );
 158
 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( char* appName, char* methodName,
 169                 osrfAppSession* ses, int reqId, jsonObject* params );
 170
 171
 172 /**
 173   Trys to run the requested method as a system method.
 174   A system method is a well known method that all
 175   servers implement.
 176   @param context The current method context
 177   @return 0 if the method is run successfully, return < 0 means
 178   the method was not run, return > 0 means the method was run
 179   and the application code now needs to send a 'request complete'
 180   message
 181   */
 182 int __osrfAppRunSystemMethod(osrfMethodContext* context);
 183
 184 /**
 185   Registers all of the system methods for this app so that they may be
 186   treated the same as other methods */
 187 int __osrfAppRegisterSysMethods( char* app );
 188
 189
 190
 191 /**
 192   Responds to the client with a method exception
 193   @param ses The current session
 194   @param request The request id
 195   @param msg The debug message to send to the client
 196   @return 0 on successfully sending of the message, -1 otherwise
 197   */
 198 int osrfAppRequestRespondException( osrfAppSession* ses, int request, char* msg, ... );
 199
 200