#ifndef OSRF_APPLICATION_H
#define OSRF_APPLICATION_H
+/**
+ @file osrf_application.h
+ @brief Routines to manage dynamically loaded libraries.
+*/
+
#include <opensrf/utils.h>
#include <opensrf/log.h>
#include <opensrf/osrf_app_session.h>
#endif
/**
- All OpenSRF methods take the signature
- int methodName( osrfMethodContext* );
- If a negative number is returned, it means an unknown error occured and an exception
- will be returned to the client automatically.
- If a positive number is returned, it means that libopensrf should send a 'Request Complete'
- message following any messages sent by the method.
- If 0 is returned, it tells libopensrf that the method completed successfully and
- there is no need to send any further data to the client.
- */
-
-
-
-/**
- This macro verifies methods receive the correct parameters */
+ All OpenSRF methods take the signature
+ int methodName( osrfMethodContext* );
+ If a negative number is returned, it means an unknown error occured and an exception
+ will be returned to the client automatically.
+ If a positive number is returned, it means that libopensrf should send a 'Request Complete'
+ message following any messages sent by the method.
+ If 0 is returned, it tells libopensrf that the method completed successfully and
+ there is no need to send any further data to the client.
+*/
+
+
+/** This macro verifies methods receive the correct parameters */
#define _OSRF_METHOD_VERIFY_CONTEXT(d) \
if(!d) return -1; \
if(!d->session) { osrfLogError( OSRF_LOG_MARK, "Session is NULL in app request" ); return -1; }\
osrfLogError( OSRF_LOG_MARK, "'params' is not a JSON array for method %s", d->method->name);\
return -1; }\
}\
- if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); return -1; }
+ if( !d->method->name ) { osrfLogError( OSRF_LOG_MARK, "Method name is NULL"); return -1; }
-#ifdef OSRF_LOG_PARAMS
+#ifdef OSRF_LOG_PARAMS
#define OSRF_METHOD_VERIFY_CONTEXT(d) \
_OSRF_METHOD_VERIFY_CONTEXT(d); \
char* __j = jsonObjectToJSON(d->params);\
if(__j) { \
- osrfLogInfo( OSRF_LOG_MARK, "CALL: %s %s - %s", d->session->remote_service, d->method->name, __j);\
+ osrfLogInfo( OSRF_LOG_MARK, "CALL:\t%s %s - %s", d->session->remote_service, d->method->name, __j);\
free(__j); \
- }
+ }
#else
-#define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
+#define OSRF_METHOD_VERIFY_CONTEXT(d) _OSRF_METHOD_VERIFY_CONTEXT(d);
#endif
/* Some well known parameters */
-#define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
-#define OSRF_SYSMETHOD_INTROSPECT_ATOMIC "opensrf.system.method.atomic"
-#define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
-#define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC "opensrf.system.method.all.atomic"
-#define OSRF_SYSMETHOD_ECHO "opensrf.system.echo"
-#define OSRF_SYSMETHOD_ECHO_ATOMIC "opensrf.system.echo.atomic"
+#define OSRF_SYSMETHOD_INTROSPECT "opensrf.system.method"
+#define OSRF_SYSMETHOD_INTROSPECT_ATOMIC "opensrf.system.method.atomic"
+#define OSRF_SYSMETHOD_INTROSPECT_ALL "opensrf.system.method.all"
+#define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC "opensrf.system.method.all.atomic"
+#define OSRF_SYSMETHOD_ECHO "opensrf.system.echo"
+#define OSRF_SYSMETHOD_ECHO_ATOMIC "opensrf.system.echo.atomic"
-#define OSRF_METHOD_SYSTEM 1
-#define OSRF_METHOD_STREAMING 2
-#define OSRF_METHOD_ATOMIC 4
-#define OSRF_METHOD_CACHABLE 8
+#define OSRF_METHOD_SYSTEM 1
+#define OSRF_METHOD_STREAMING 2
+#define OSRF_METHOD_ATOMIC 4
+#define OSRF_METHOD_CACHABLE 8
-
struct _osrfApplicationStruct {
- void* handle; /* the lib handle */
+ void* handle; /**< the lib handle. */
osrfHash* methods;
- void (*onExit) (void);
+ void (*onExit) (void);
};
typedef struct _osrfApplicationStruct osrfApplication;
struct _osrfMethodStruct {
- char* name; /* the method name */
- char* symbol; /* the symbol name (function) */
- char* notes; /* public method documentation */
- int argc; /* how many args this method expects */
- //char* paramNotes; /* Description of the params expected for this method */
- int options; /* describes the various options for this method */
- void* userData; /* You can put your weeeeeeed in it ... */
+ char* name; /**< the method name */
+ char* symbol; /**< the symbol name (function) */
+ char* notes; /**< public method documentation */
+ int argc; /**< how many args this method expects */
+ //char* paramNotes; /**< Description of the params expected for this method */
+ int options; /**< describes the various options for this method */
+ void* userData; /**< You can put your weeeeeeed in it ... */
/*
- int sysmethod;
- int streaming;
- int atomic;
- int cachable;
+ int sysmethod;
+ int streaming;
+ int atomic;
+ int cachable;
*/
-};
+};
typedef struct _osrfMethodStruct osrfMethod;
struct _osrfMethodContextStruct {
- osrfAppSession* session; /* the current session */
- osrfMethod* method; /* the requested method */
- jsonObject* params; /* the params to the method */
- int request; /* request id */
- jsonObject* responses; /* array of cached responses. */
+ osrfAppSession* session; /**< the current session. */
+ osrfMethod* method; /**< the requested method. */
+ jsonObject* params; /**< the params to the method. */
+ int request; /**< request id. */
+ jsonObject* responses; /**< array of cached responses. */
};
typedef struct _osrfMethodContextStruct osrfMethodContext;
-
-/**
- Register an application
- @param appName The name of the application
- @param soFile The library (.so) file that implements this application
- @return 0 on success, -1 on error
- */
+/**
+ Register an application
+ @param appName The name of the application
+ @param soFile The library (.so) file that implements this application
+ @return 0 on success, -1 on error
+*/
int osrfAppRegisterApplication( const char* appName, const char* soFile );
/**
- Register a method
- Any method with the OSRF_METHOD_STREAMING option set will have a ".atomic"
- version of the method registered automatically
- @param appName The name of the application that implements the method
- @param methodName The fully qualified name of the method
- @param symbolName The symbol name (function) that implements the method
- @param notes Public documentation for this method.
- @params argc The number of arguments this method expects
- @param streaming True if this is a streaming method that requires an atomic version
- @return 0 on success, -1 on error
- */
-int osrfAppRegisterMethod( const char* appName, const char* methodName,
+ Register a method
+ Any method with the OSRF_METHOD_STREAMING option set will have a ".atomic"
+ version of the method registered automatically
+ @param appName The name of the application that implements the method
+ @param methodName The fully qualified name of the method
+ @param symbolName The symbol name (function) that implements the method
+ @param notes Public documentation for this method.
+ @params argc The number of arguments this method expects
+ @param streaming True if this is a streaming method that requires an atomic version
+ @return 0 on success, -1 on error
+*/
+int osrfAppRegisterMethod( const char* appName, const char* methodName,
const char* symbolName, const char* notes, int argc, int options );
-int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
+int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
const char* symbolName, const char* notes, int argc, int options, void* );
/**
- Finds the given method for the given app
- @param appName The application
- @param methodName The method to find
- @return A method pointer or NULL if no such method
- exists for the given application
- */
+ Finds the given method for the given app
+ @param appName The application
+ @param methodName The method to find
+ @return A method pointer or NULL if no such method
+ exists for the given application
+*/
osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName );
/**
- Runs the specified method for the specified application.
- @param appName The name of the application who's method to run
- @param methodName The name of the method to run
- @param ses The app session attached to this request
- @params reqId The request id for this request
- @param params The method parameters
- */
-int osrfAppRunMethod( const char* appName, const char* methodName,
+ Runs the specified method for the specified application.
+ @param appName The name of the application who's method to run
+ @param methodName The name of the method to run
+ @param ses The app session attached to this request
+ @params reqId The request id for this request
+ @param params The method parameters
+*/
+int osrfAppRunMethod( const char* appName, const char* methodName,
osrfAppSession* ses, int reqId, jsonObject* params );
/**
- Responds to the client with a method exception
- @param ses The current session
- @param request The request id
- @param msg The debug message to send to the client
- @return 0 on successfully sending of the message, -1 otherwise
- */
+ Responds to the client with a method exception
+ @param ses The current session
+ @param request The request id
+ @param msg The debug message to send to the client
+ @return 0 on successfully sending of the message, -1 otherwise
+*/
int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... );
int osrfAppRespond( osrfMethodContext* context, const jsonObject* data );
/* OSRF_METHOD_ATOMIC and/or OSRF_METHOD_CACHABLE and/or 0 for no special options */
//int osrfAppProcessMethodOptions( char* method );
-/**
- * Tells the backend process to run its child init function */
+/** Tells the backend process to run its child init function */
int osrfAppRunChildInit(const char* appname);
void osrfAppRunExitCode();
/**
- Determine whether the context looks healthy.
- Return 0 if it does, or -1 if it doesn't.
- */
+ Determine whether the context looks healthy.
+ Return 0 if it does, or -1 if it doesn't.
+*/
int osrfMethodVerifyContext( osrfMethodContext* ctx );
#ifdef __cplusplus
#include <opensrf/osrf_application.h>
+/**
+ @file osrf_application.c
+ @brief Routines to manage dynamically loaded libraries.
+*/
+
static osrfMethod* _osrfAppBuildMethod( const char* methodName, const char* symbolName,
const char* notes, int argc, int options, void* );
static void osrfAppSetOnExit(osrfApplication* app, const char* appName);
if(!appName || ! soFile) return -1;
char* error;
- if(!_osrfAppHash) _osrfAppHash = osrfNewHash();
+ if(!_osrfAppHash)
+ _osrfAppHash = osrfNewHash();
osrfLogInfo( OSRF_LOG_MARK, "Registering application %s with file %s", appName, soFile );
*(void **) (&init) = dlsym(app->handle, "osrfAppInitialize");
if( (error = dlerror()) != NULL ) {
- osrfLogWarning( OSRF_LOG_MARK,
- "! Unable to locate method symbol [osrfAppInitialize] for app %s: %s", appName, error );
+ osrfLogWarning( OSRF_LOG_MARK,
+ "! Unable to locate method symbol [osrfAppInitialize] for app %s: %s",
+ appName, error );
} else {
}
-void osrfAppRunExitCode() {
+void osrfAppRunExitCode() {
osrfHashIterator* itr = osrfNewHashIterator(_osrfAppHash);
osrfApplication* app;
while( (app = osrfHashIteratorNext(itr)) ) {
}
-int osrfAppRegisterMethod( const char* appName, const char* methodName,
+int osrfAppRegisterMethod( const char* appName, const char* methodName,
const char* symbolName, const char* notes, int argc, int options ) {
return osrfAppRegisterExtendedMethod(
}
-int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
+int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
const char* symbolName, const char* notes, int argc, int options, void * user_data ) {
if( !appName || ! methodName ) return -1;
osrfLogDebug( OSRF_LOG_MARK, "Registering method %s for app %s", methodName, appName );
osrfMethod* method = _osrfAppBuildMethod(
- methodName, symbolName, notes, argc, options, user_data );
+ methodName, symbolName, notes, argc, options, user_data );
method->options = options;
/* plug the method into the list of methods */
if( options & OSRF_METHOD_STREAMING ) { /* build the atomic counterpart */
int newops = options | OSRF_METHOD_ATOMIC;
osrfMethod* atomicMethod = _osrfAppBuildMethod(
- methodName, symbolName, notes, argc, newops, NULL );
+ methodName, symbolName, notes, argc, newops, NULL );
osrfHashSet( app->methods, atomicMethod, atomicMethod->name );
atomicMethod->userData = method->userData;
}
static osrfMethod* _osrfAppBuildMethod( const char* methodName, const char* symbolName,
const char* notes, int argc, int options, void* user_data ) {
- osrfMethod* method = safe_malloc(sizeof(osrfMethod));
+ osrfMethod* method = safe_malloc(sizeof(osrfMethod));
+
+ if(methodName)
+ method->name = strdup(methodName);
+ else
+ method->name = NULL;
- if(methodName) method->name = strdup(methodName);
- else method->name = NULL;
- if(symbolName) method->symbol = strdup(symbolName);
- else method->symbol = NULL;
- if(notes) method->notes = strdup(notes);
- else method->notes = NULL;
- if(user_data) method->userData = user_data;
+ if(symbolName)
+ method->symbol = strdup(symbolName);
+ else
+ method->symbol = NULL;
- method->argc = argc;
- method->options = options;
+ if(notes)
+ method->notes = strdup(notes);
+ else
+ method->notes = NULL;
+
+ if(user_data)
+ method->userData = user_data;
+
+ method->argc = argc;
+ method->options = options;
if(options & OSRF_METHOD_ATOMIC) { /* add ".atomic" to the end of the name */
char mb[strlen(method->name) + 8];
/**
- Registers all of the system methods for this app so that they may be
- treated the same as other methods */
+ Registers all of the system methods for this app so that they may be
+ treated the same as other methods
+*/
static int _osrfAppRegisterSysMethods( const char* app ) {
- osrfAppRegisterMethod(
- app, OSRF_SYSMETHOD_INTROSPECT, NULL,
+ osrfAppRegisterMethod(
+ app, OSRF_SYSMETHOD_INTROSPECT, NULL,
"Return a list of methods whose names have the same initial "
- "substring as that of the provided method name PARAMS( methodNameSubstring )",
+ "substring as that of the provided method name PARAMS( methodNameSubstring )",
1, OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
- osrfAppRegisterMethod(
- app, OSRF_SYSMETHOD_INTROSPECT_ALL, NULL,
- "Returns a complete list of methods. PARAMS()", 0,
+ osrfAppRegisterMethod(
+ app, OSRF_SYSMETHOD_INTROSPECT_ALL, NULL,
+ "Returns a complete list of methods. PARAMS()", 0,
OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
- osrfAppRegisterMethod(
- app, OSRF_SYSMETHOD_ECHO, NULL,
- "Echos all data sent to the server back to the client. PARAMS([a, b, ...])", 0,
+ osrfAppRegisterMethod(
+ app, OSRF_SYSMETHOD_ECHO, NULL,
+ "Echos all data sent to the server back to the client. PARAMS([a, b, ...])", 0,
OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
return 0;
}
/**
- Finds the given app in the list of apps
- @param name The name of the application
- @return The application pointer or NULL if there is no such application
- */
+ Finds the given app in the list of apps
+ @param name The name of the application
+ @return The application pointer or NULL if there is no such application
+*/
static osrfApplication* _osrfAppFindApplication( const char* name ) {
if(!name) return NULL;
return (osrfApplication*) osrfHashGet(_osrfAppHash, name);
}
/**
- Finds the given method for the given app
- @param app The application object
- @param methodName The method to find
- @return A method pointer or NULL if no such method
- exists for the given application
- */
+ @brief Find the given method for the given app.
+ @param app The application object.
+ @param methodName The method to find.
+ @return A method pointer or NULL if no such method exists for the given application.
+*/
static osrfMethod* osrfAppFindMethod( osrfApplication* app, const char* methodName ) {
if(!app || ! methodName) return NULL;
return (osrfMethod*) osrfHashGet( app->methods, methodName );
}
-int osrfAppRunMethod( const char* appName, const char* methodName,
+int osrfAppRunMethod( const char* appName, const char* methodName,
osrfAppSession* ses, int reqId, jsonObject* params ) {
if( !(appName && methodName && ses) ) return -1;
context.responses = NULL;
/* this is the method we're gonna run */
- int (*meth) (osrfMethodContext*);
+ int (*meth) (osrfMethodContext*);
if( !(app = _osrfAppFindApplication(appName)) )
- return osrfAppRequestRespondException( ses,
+ return osrfAppRequestRespondException( ses,
reqId, "Application not found: %s", appName );
-
+
if( !(method = osrfAppFindMethod( app, methodName )) )
- return osrfAppRequestRespondException( ses, reqId,
+ return osrfAppRequestRespondException( ses, reqId,
"Method [%s] not found for service %s", methodName, appName );
context.method = method;
#ifdef OSRF_STRICT_PARAMS
if( method->argc > 0 ) {
if(!params || params->type != JSON_ARRAY || params->size < method->argc )
- return osrfAppRequestRespondException( ses, reqId,
+ return osrfAppRequestRespondException( ses, reqId,
"Not enough params for method %s / service %s", methodName, appName );
}
#endif
*(void **) (&meth) = dlsym(app->handle, method->symbol);
if( (error = dlerror()) != NULL ) {
- return osrfAppRequestRespondException( ses, reqId,
+ return osrfAppRequestRespondException( ses, reqId,
"Unable to execute method [%s] for service %s", methodName, appName );
}
retcode = (*meth) (&context);
}
- if(retcode < 0)
- return osrfAppRequestRespondException(
+ if(retcode < 0)
+ return osrfAppRequestRespondException(
ses, reqId, "An unknown server error occurred" );
return _osrfAppPostProcess( &context, retcode );
if(!(ctx && ctx->method)) return -1;
if( ctx->method->options & OSRF_METHOD_ATOMIC ) {
- osrfLogDebug( OSRF_LOG_MARK,
+ osrfLogDebug( OSRF_LOG_MARK,
"Adding responses to stash for atomic method %s", ctx->method->name );
if( ctx->responses == NULL )
ctx->responses = jsonNewObjectType( JSON_ARRAY );
if ( data != NULL )
- jsonObjectPush( ctx->responses, jsonObjectClone(data) );
+ jsonObjectPush( ctx->responses, jsonObjectClone(data) );
}
- if( !(ctx->method->options & OSRF_METHOD_ATOMIC) &&
+ if( !(ctx->method->options & OSRF_METHOD_ATOMIC ) &&
!(ctx->method->options & OSRF_METHOD_CACHABLE) ) {
- if(complete)
+ if(complete)
osrfAppRequestRespondComplete( ctx->session, ctx->request, data );
else
osrfAppRequestRespond( ctx->session, ctx->request, data );
}
-
-
static int _osrfAppPostProcess( osrfMethodContext* ctx, int retcode ) {
if(!(ctx && ctx->method)) return -1;
} else {
- if( retcode > 0 )
- osrfAppSessionStatus( ctx->session, OSRF_STATUS_COMPLETE,
+ if( retcode > 0 )
+ osrfAppSessionStatus( ctx->session, OSRF_STATUS_COMPLETE,
"osrfConnectStatus", ctx->request, "Request Complete" );
}
static void _osrfAppSetIntrospectMethod( osrfMethodContext* ctx, const osrfMethod* method, jsonObject* resp ) {
if(!(ctx && resp)) return;
- jsonObjectSetKey(resp, "api_name", jsonNewObject(method->name));
- jsonObjectSetKey(resp, "method", jsonNewObject(method->symbol));
- jsonObjectSetKey(resp, "service", jsonNewObject(ctx->session->remote_service));
- jsonObjectSetKey(resp, "notes", jsonNewObject(method->notes));
- jsonObjectSetKey(resp, "argc", jsonNewNumberObject(method->argc));
+ jsonObjectSetKey(resp, "api_name", jsonNewObject(method->name));
+ jsonObjectSetKey(resp, "method", jsonNewObject(method->symbol));
+ jsonObjectSetKey(resp, "service", jsonNewObject(ctx->session->remote_service));
+ jsonObjectSetKey(resp, "notes", jsonNewObject(method->notes));
+ jsonObjectSetKey(resp, "argc", jsonNewNumberObject(method->argc));
- jsonObjectSetKey(resp, "sysmethod",
+ jsonObjectSetKey(resp, "sysmethod",
jsonNewNumberObject( (method->options & OSRF_METHOD_SYSTEM) ? 1 : 0 ));
- jsonObjectSetKey(resp, "atomic",
+ jsonObjectSetKey(resp, "atomic",
jsonNewNumberObject( (method->options & OSRF_METHOD_ATOMIC) ? 1 : 0 ));
- jsonObjectSetKey(resp, "cachable",
+ jsonObjectSetKey(resp, "cachable",
jsonNewNumberObject( (method->options & OSRF_METHOD_CACHABLE) ? 1 : 0 ));
}
/**
- Trys to run the requested method as a system method.
- A system method is a well known method that all
- servers implement.
- @param context The current method context
- @return 0 if the method is run successfully, return < 0 means
- the method was not run, return > 0 means the method was run
- and the application code now needs to send a 'request complete'
- message
- */
+ Tries to run the requested method as a system method.
+ A system method is a well known method that all
+ servers implement.
+ @param context The current method context
+ @return 0 if the method is run successfully, return < 0 means
+ the method was not run, return > 0 means the method was run
+ and the application code now needs to send a 'request complete'
+ message
+*/
static int _osrfAppRunSystemMethod(osrfMethodContext* ctx) {
if( osrfMethodVerifyContext( ctx ) < 0 ) {
osrfLogError( OSRF_LOG_MARK, "_osrfAppRunSystemMethod: Received invalid method context" );
return -1;
}
- if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ALL ) ||
+ if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ALL ) ||
!strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC )) {
return osrfAppIntrospectAll(ctx);
}
- if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT ) ||
+ if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT ) ||
!strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ATOMIC )) {
return osrfAppIntrospect(ctx);
}
- if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_ECHO ) ||
+ if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_ECHO ) ||
!strcmp(ctx->method->name, OSRF_SYSMETHOD_ECHO_ATOMIC )) {
return osrfAppEcho(ctx);
}
- osrfAppRequestRespondException( ctx->session,
+ osrfAppRequestRespondException( ctx->session,
ctx->request, "System method implementation not found");
return 0;
osrfLogError( OSRF_LOG_MARK, "osrfAppEcho: Received invalid method context" );
return -1;
}
-
+
int i;
for( i = 0; i < ctx->params->size; i++ ) {
const jsonObject* str = jsonObjectGetIndex(ctx->params,i);
}
/**
- Determine whether the context looks healthy.
- Return 0 if it does, or -1 if it doesn't.
- */
+ Determine whether the context looks healthy.
+ Return 0 if it does, or -1 if it doesn't.
+*/
int osrfMethodVerifyContext( osrfMethodContext* ctx )
{
if( !ctx ) {
osrfLogError( OSRF_LOG_MARK, "Context is NULL in app request" );
return -1;
}
-
+
if( !ctx->session ) {
osrfLogError( OSRF_LOG_MARK, "Session is NULL in app request" );
return -1;
// Log the call, with the method and parameters
char* params_str = jsonObjectToJSON( ctx->params );
if( params_str ) {
- osrfLogInfo( OSRF_LOG_MARK, "CALL: %s %s - %s",
+ osrfLogInfo( OSRF_LOG_MARK, "CALL:\t%s %s - %s",
ctx->session->remote_service, ctx->method->name, params_str );
free( params_str );
}
return 0;
}
-
projects / opensrf-equinox.git / commitdiff