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         Every method of a service is implemented by a C function.  In a few cases those
   9         functions are generic to all services.  In other cases they are loaded and executed from
  10         a shared object library that is specific to the application offering the service,  A
  11         registry maps method names to function names so that we can call the right function.
  12
  13         Each such function has a similar signature:
  14
  15                 int method_name( osrfMethodContext* ctx );
  16
  17         The return value is negative in case of an error.  A return code of zero implies that
  18         the method has already sent the client a STATUS message to say that it is finished.
  19         A return code greater than zero implies that the method has not sent such a STATUS
  20         message, so we need to do so after the method returns.
  21
  22         Any arguments passed to the method are bundled together in a jsonObject inside the
  23         osrfMethodContext.
  24
  25         An application's shared object may also implement any or all of three standard functions:
  26
  27         - int osrfAppInitialize( void ) Called when an application is registered
  28         - int osrfAppChildInit( void ) Called when a server drone is spawned
  29         - void osrfAppChildExit( void ) Called when a server drone terminates
  30
  31         osrfAppInitialize() and osrfAppChild return zero if successful, and non-zero if not.
  32 */
  33
  34 #include <opensrf/utils.h>
  35 #include <opensrf/log.h>
  36 #include <opensrf/osrf_app_session.h>
  37 #include <opensrf/osrf_hash.h>
  38 #include <opensrf/string_array.h>
  39
  40 #include <opensrf/osrf_json.h>
  41 #include <stdio.h>
  42 #include <dlfcn.h>
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 /**
  49         All OpenSRF methods take the signature
  50         int methodName( osrfMethodContext* );
  51         If a negative number is returned, it means an unknown error occured and an exception
  52         will be returned to the client automatically.
  53         If a positive number is returned, it means that libopensrf should send a 'Request Complete'
  54         message following any messages sent by the method.
  55         If 0 is returned, it tells libopensrf that the method completed successfully and
  56         there is no need to send any further data to the client.
  57 */
  58
  59 /** This macro verifies that methods receive the correct parameters */
  60 /** TODO: deprecate me, since I no longer server a purpose */
  61 #define OSRF_METHOD_VERIFY_CONTEXT(d) osrfMethodVerifyContext(d)
  62
  63 /**
  64         @name Method options
  65         @brief Macros that get OR'd together to form method options.
  66 */
  67 /*@{*/
  68 /**
  69         @brief Notes that the method may return more than one result.
  70
  71         For a @em streaming method, we register both an atomic method and a non-atomic method.
  72 */
  73 #define OSRF_METHOD_STREAMING       2
  74 /**
  75         @brief  Notes that a previous result to the same call may be available in memcache.
  76
  77         Before calling the registered function, a cachable method checks memcache for a previously
  78         determined result for the same call.  If no such result is available, it calls the
  79         registered function and caches the new result before returning.
  80
  81         This caching is not currently implemented for C methods.
  82 */
  83 #define OSRF_METHOD_CACHABLE        8
  84 /*@}*/
  85
  86 typedef struct {
  87         char* name;                 /**< Method name. */
  88         char* symbol;               /**< Symbol name (function name) within the shared object. */
  89         char* notes;                /**< Public method documentation. */
  90         int argc;                   /**< The minimum number of arguments for the method. */
  91         //char* paramNotes;         /**< Description of the params expected for this method. */
  92         int options;                /**< Bit switches setting various options for this method. */
  93         void* userData;             /**< Opaque pointer to application-specific data. */
  94         size_t max_bundle_size;     /**< How big a buffer to use for non-atomic methods */
  95         size_t max_chunk_size;      /**< Maximum content size per message; 0 means no limit */
  96
  97         /*
  98         int sysmethod;
  99         int streaming;
 100         int atomic;
 101         int cachable;
 102         */
 103 } osrfMethod;
 104
 105 typedef struct {
 106         osrfAppSession* session;    /**< Pointer to the current application session. */
 107         osrfMethod* method;         /**< Pointer to the requested method. */
 108         jsonObject* params;         /**< Parameters to the method. */
 109         int request;                /**< Request id. */
 110         jsonObject* responses;      /**< Array of cached responses. */
 111 } osrfMethodContext;
 112
 113 int osrfAppRegisterApplication( const char* appName, const char* soFile );
 114
 115 int osrfAppRegisterMethod( const char* appName, const char* methodName,
 116                 const char* symbolName, const char* notes, int argc, int options );
 117
 118 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
 119                 const char* symbolName, const char* notes, int argc, int options, void* );
 120
 121 int osrfMethodSetBundleSize( const char* appName, const char* methodName, size_t max_bundle_size );
 122
 123 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
 124
 125 int osrfAppRunMethod( const char* appName, const char* methodName,
 126                 osrfAppSession* ses, int reqId, jsonObject* params );
 127
 128 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
 129
 130 int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
 131
 132 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data );
 133
 134 int osrfAppRunChildInit(const char* appname);
 135
 136 void osrfAppRunExitCode( void );
 137
 138 int osrfMethodVerifyContext( osrfMethodContext* ctx );
 139
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144 #endif