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 load and manage shared object 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 /** This macro verifies that methods receive the correct parameters */
  34 #define _OSRF_METHOD_VERIFY_CONTEXT(d) \
  35         if(!d) return -1; \
  36         if(!d->session) { \
  37                  osrfLogError( OSRF_LOG_MARK, "Session is NULL in app request" ); \
  38                  return -1; \
  39         } \
  40         if(!d->method) { \
  41                 osrfLogError( OSRF_LOG_MARK, "Method is NULL in app request" ); \
  42                 return -1; \
  43         } \
  44         if(d->method->argc) { \
  45                 if(!d->params) { \
  46                         osrfLogError( OSRF_LOG_MARK, "Params is NULL in app request %s", d->method->name ); \
  47                         return -1; \
  48                 } \
  49                 if( d->params->type != JSON_ARRAY ) { \
  50                         osrfLogError( OSRF_LOG_MARK, "'params' is not a JSON array for method %s", \
  51                                 d->method->name); \
  52                         return -1; } \
  53         } \
  54         if( !d->method->name ) { \
  55                 osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); return -1; \
  56         }
  57
  58 #ifdef OSRF_LOG_PARAMS
  59 #define OSRF_METHOD_VERIFY_CONTEXT(d) \
  60         _OSRF_METHOD_VERIFY_CONTEXT(d); \
  61         char* __j = jsonObjectToJSON(d->params); \
  62         if(__j) { \
  63                 osrfLogInfo( OSRF_LOG_MARK, "CALL:\t%s %s - %s", d->session->remote_service, \
  64                                 d->method->name, __j);\
  65                 free(__j); \
  66         }
  67 #else
  68 #define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
  69 #endif
  70
  71 #define OSRF_METHOD_SYSTEM          1
  72 #define OSRF_METHOD_STREAMING       2
  73 #define OSRF_METHOD_ATOMIC          4
  74 #define OSRF_METHOD_CACHABLE        8
  75
  76 typedef struct {
  77         char* name;                 /**< the method name. */
  78         char* symbol;               /**< the symbol name (function name). */
  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         int options;                /**< bitswitches setting various options for this method. */
  83         void* userData;             /**< Opaque pointer to application-specific data. */
  84
  85         /*
  86         int sysmethod;
  87         int streaming;
  88         int atomic;
  89         int cachable;
  90         */
  91 } osrfMethod;
  92
  93 typedef struct {
  94         osrfAppSession* session;    /**< the current session. */
  95         osrfMethod* method;         /**< the requested method. */
  96         jsonObject* params;         /**< the params to the method. */
  97         int request;                /**< request id. */
  98         jsonObject* responses;      /**< array of cached responses. */
  99 } osrfMethodContext;
 100
 101 /**
 102         Register an application
 103         @param appName The name of the application
 104         @param soFile The library (.so) file that implements this application
 105         @return 0 on success, -1 on error
 106 */
 107 int osrfAppRegisterApplication( const char* appName, const char* soFile );
 108
 109 /**
 110         @brief Register a method for a given application.
 111
 112         @param appName Name of the application that implements the method.
 113         @param methodName The fully qualified name of the method.
 114         @param symbolName The symbol name (function name) that implements the method.
 115         @param notes Public documentation for this method.
 116         @params argc The number of arguments this method expects.
 117         @param options Bit switches setting various options.
 118         @return 0 on success, -1 on error
 119
 120         Any method with  the OSRF_METHOD_STREAMING option set will have a ".atomic"
 121         version of the method registered automatically.
 122 */
 123 int osrfAppRegisterMethod( const char* appName, const char* methodName,
 124                 const char* symbolName, const char* notes, int argc, int options );
 125
 126 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
 127                 const char* symbolName, const char* notes, int argc, int options, void* );
 128
 129 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
 130
 131 /**
 132         Runs the specified method for the specified application.
 133         @param appName The name of the application who's method to run
 134         @param methodName The name of the method to run
 135         @param ses The app session attached to this request
 136         @params reqId The request id for this request
 137         @param params The method parameters
 138 */
 139 int osrfAppRunMethod( const char* appName, const char* methodName,
 140                 osrfAppSession* ses, int reqId, jsonObject* params );
 141
 142 /**
 143         @brief Respond to the client with a method exception.
 144         @param ses The current session.
 145         @param request The request id.
 146         @param msg The debug message to send to the client.
 147         @return 0 on successfully sending of the message, -1 otherwise.
 148 */
 149 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
 150
 151 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
 152 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
 153
 154 /* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
 155 //int osrfAppProcessMethodOptions( char* method );
 156
 157 /** Tell the backend process to run its child init function */
 158 int osrfAppRunChildInit(const char* appname);
 159
 160 void osrfAppRunExitCode( void );
 161
 162 /**
 163         Determine whether the context looks healthy.
 164         Return 0 if it does, or -1 if it doesn't.
 165 */
 166 int osrfMethodVerifyContext( osrfMethodContext* ctx );
 167
 168 #ifdef __cplusplus
 169 }
 170 #endif
 171
 172 #endif