836f73bd53063db665f9efa5abd49facce33dde1
[OpenSRF.git] / src / libopensrf / osrf_application.c
1 #include <opensrf/osrf_application.h>
2
3 /**
4         @file osrf_application.c
5         @brief Load and manage shared object libraries.
6
7         Maintain a registry of applications, using an osrfHash keyed on application name,
8
9         For each application, load a shared object library so that we can call
10         application-specific functions dynamically.  In order to map method names to the
11         corresponding functions (i.e. symbol names in the library), maintain a registry of
12         methods, using an osrfHash keyed on method name.
13 */
14
15 // The following macro is commented out because it ia no longer used.
16
17 // Used internally to make sure the method description provided is OK
18 /*
19 #define OSRF_METHOD_VERIFY_DESCRIPTION(app, d) \
20         if(!app) return -1; \
21         if(!d) return -1;\
22         if(!d->name) { \
23                 osrfLogError( OSRF_LOG_MARK,  "No method name provided in description" ), \
24                 return -1; \
25 } \
26         if(!d->symbol) { \
27                 osrfLogError( OSRF_LOG_MARK, "No method symbol provided in description" ), \
28                 return -1; \
29 } \
30         if(!d->notes) \
31                 d->notes = ""; \
32         if(!d->paramNotes) \
33                 d->paramNotes = "";\
34         if(!d->returnNotes) \
35                 d->returnNotes = "";
36 */
37
38 /**
39         @name Well known method names
40         @brief These methods are automatically implemented for every application.
41 */
42 /*@{*/
43 #define OSRF_SYSMETHOD_INTROSPECT               "opensrf.system.method"
44 #define OSRF_SYSMETHOD_INTROSPECT_ATOMIC        "opensrf.system.method.atomic"
45 #define OSRF_SYSMETHOD_INTROSPECT_ALL           "opensrf.system.method.all"
46 #define OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC    "opensrf.system.method.all.atomic"
47 #define OSRF_SYSMETHOD_ECHO                     "opensrf.system.echo"
48 #define OSRF_SYSMETHOD_ECHO_ATOMIC              "opensrf.system.echo.atomic"
49 /*@}*/
50
51 /**
52         @brief Represent an Application.
53 */
54 typedef struct {
55         void* handle;               /**< Handle to the shared object library. */
56         osrfHash* methods;          /**< Registry of method names. */
57         void (*onExit) (void);      /**< Exit handler for the application. */
58 } osrfApplication;
59
60 static osrfMethod* _osrfAppBuildMethod( const char* methodName, const char* symbolName,
61                 const char* notes, int argc, int options, void* );
62 static void osrfAppSetOnExit(osrfApplication* app, const char* appName);
63 static void _osrfAppRegisterSysMethods( const char* app );
64 static inline osrfApplication* _osrfAppFindApplication( const char* name );
65 static inline osrfMethod* osrfAppFindMethod( osrfApplication* app, const char* methodName );
66 static int _osrfAppRespond( osrfMethodContext* context, const jsonObject* data, int complete );
67 static int _osrfAppPostProcess( osrfMethodContext* context, int retcode );
68 static int _osrfAppRunSystemMethod(osrfMethodContext* context);
69 static void _osrfAppSetIntrospectMethod( osrfMethodContext* ctx, const osrfMethod* method,
70                 jsonObject* resp );
71 static int osrfAppIntrospect( osrfMethodContext* ctx );
72 static int osrfAppIntrospectAll( osrfMethodContext* ctx );
73 static int osrfAppEcho( osrfMethodContext* ctx );
74
75 /**
76         @brief Registry of applications.
77
78         The key of the hash is the application name, and the associated data is an osrfApplication.
79 */
80 static osrfHash* _osrfAppHash = NULL;
81
82 /**
83         @brief Register an application.
84         @param appName Name of the application.
85         @param soFile Name of the shared object file to be loaded for this application.
86         @return Zero if successful, or -1 upon error.
87
88         Open the shared object file and call its osrfAppInitialize() function, if it has one.
89         Register the standard system methods for it.  Arrange for the application name to
90         appear in subsequent log messages.
91 */
92 int osrfAppRegisterApplication( const char* appName, const char* soFile ) {
93         if( !appName || ! soFile ) return -1;
94         char* error;
95
96         osrfLogSetAppname( appName );
97
98         if( !_osrfAppHash )
99                 _osrfAppHash = osrfNewHash();
100
101         osrfLogInfo( OSRF_LOG_MARK, "Registering application %s with file %s", appName, soFile );
102
103         void* handle = dlopen( soFile, RTLD_NOW );
104         if( ! handle ) {
105                 const char* msg = dlerror();
106                 osrfLogWarning( OSRF_LOG_MARK, "Failed to dlopen library file %s: %s", soFile, msg );
107                 return -1;
108         }
109
110         osrfApplication* app = safe_malloc(sizeof(osrfApplication));
111         app->handle = handle;
112         app->onExit = NULL;
113         app->methods = osrfNewHash();
114         osrfHashSet( _osrfAppHash, app, appName );
115
116         /* see if we can run the initialize method */
117         int (*init) (void);
118         *(void **) (&init) = dlsym(app->handle, "osrfAppInitialize");
119
120         if( (error = dlerror()) != NULL ) {
121                 osrfLogWarning( OSRF_LOG_MARK,
122                         "! Unable to locate method symbol [osrfAppInitialize] for app %s: %s",
123                         appName, error );
124
125         } else {
126
127                 /* run the method */
128                 int ret;
129                 if( (ret = (*init)()) ) {
130                         osrfLogWarning( OSRF_LOG_MARK, "Application %s returned non-zero value from "
131                                         "'osrfAppInitialize', not registering...", appName );
132                         //free(app->name); /* need a method to remove an application from the list */
133                         //free(app);
134                         return ret;
135                 }
136         }
137
138         _osrfAppRegisterSysMethods(appName);
139
140         osrfLogInfo( OSRF_LOG_MARK, "Application %s registered successfully", appName );
141
142         osrfAppSetOnExit(app, appName);
143
144         return 0;
145 }
146
147 /**
148         @brief Save a pointer to the application's exit function.
149         @param app Pointer to the osrfApplication.
150         @param appName Application name (used only for log messages).
151
152         Look in the shared object for a symbol named "osrfAppChildExit".  If you find one, save
153         it as a pointer to the application's exit function.  If present, this function will be
154         called when a server's child process (a so-called "drone") is shutting down.
155 */
156 static void osrfAppSetOnExit(osrfApplication* app, const char* appName) {
157         if(!(app && appName)) return;
158
159         /* see if we can run the initialize method */
160         char* error;
161         void (*onExit) (void);
162         *(void **) (&onExit) = dlsym(app->handle, "osrfAppChildExit");
163
164         if( (error = dlerror()) != NULL ) {
165                 osrfLogDebug(OSRF_LOG_MARK, "No exit handler defined for %s", appName);
166                 return;
167         }
168
169         osrfLogInfo(OSRF_LOG_MARK, "registering exit handler for %s", appName);
170         app->onExit = (*onExit);
171 }
172
173 /**
174         @brief Run the application-specific child initialization function for a given application.
175         @param appname Name of the application.
176         @return Zero if successful, or if the application has no child initialization function; -1
177         if the application is not registered, or if the function returns non-zero.
178
179         The child initialization function must be named "osrfAppChildInit" within the shared
180         object library.  It initializes a drone process of a server.
181 */
182 int osrfAppRunChildInit(const char* appname) {
183         osrfApplication* app = _osrfAppFindApplication(appname);
184         if(!app) return -1;
185
186         char* error;
187         int ret;
188         int (*childInit) (void);
189
190         *(void**) (&childInit) = dlsym(app->handle, "osrfAppChildInit");
191
192         if( (error = dlerror()) != NULL ) {
193                 osrfLogInfo( OSRF_LOG_MARK, "No child init defined for app %s : %s", appname, error);
194                 return 0;
195         }
196
197         if( (ret = (*childInit)()) ) {
198                 osrfLogError(OSRF_LOG_MARK, "App %s child init failed", appname);
199                 return -1;
200         }
201
202         osrfLogInfo(OSRF_LOG_MARK, "%s child init succeeded", appname);
203         return 0;
204 }
205
206 /**
207         @brief Call the exit handler for every application that has one.
208
209         Normally a server's child process (a so-called "drone") calls this function just before
210         shutting down.
211 */
212 void osrfAppRunExitCode( void ) {
213         osrfHashIterator* itr = osrfNewHashIterator(_osrfAppHash);
214         osrfApplication* app;
215         while( (app = osrfHashIteratorNext(itr)) ) {
216                 if( app->onExit ) {
217                         osrfLogInfo(OSRF_LOG_MARK, "Running onExit handler for app %s",
218                                 osrfHashIteratorKey(itr) );
219                         app->onExit();
220                 }
221         }
222         osrfHashIteratorFree(itr);
223 }
224
225 /**
226         @brief Register a method for a specified application.
227
228         @param appName Name of the application that implements the method.
229         @param methodName The fully qualified name of the method.
230         @param symbolName The symbol name (function name) that implements the method.
231         @param notes Public documentation for this method.
232         @param argc The minimum number of arguments for the function.
233         @param options Bit switches setting various options.
234         @return Zero on success, or -1 on error.
235
236         Registering a method enables us to call the right function when a client requests a
237         method call.
238
239         The @a options parameter is zero or more of the following macros, OR'd together:
240
241         - OSRF_METHOD_SYSTEM
242         - OSRF_METHOD_STREAMING
243         - OSRF_METHOD_ATOMIC
244         - OSRF_METHOD_CACHABLE
245
246         If the OSRF_METHOD_STREAMING bit is set, also register an ".atomic" version of
247         the method.
248 */
249 int osrfAppRegisterMethod( const char* appName, const char* methodName,
250                 const char* symbolName, const char* notes, int argc, int options ) {
251
252         return osrfAppRegisterExtendedMethod(
253                         appName,
254                         methodName,
255                         symbolName,
256                         notes,
257                         argc,
258                         options,
259                         NULL
260         );
261 }
262
263 /**
264         @brief Register a method for a specified application.
265
266         @param appName Name of the application that implements the method.
267         @param methodName The fully qualified name of the method.
268         @param symbolName The symbol name (function name) that implements the method.
269         @param notes Public documentation for this method.
270         @param argc How many arguments this method expects.
271         @param options Bit switches setting various options.
272         @param user_data Opaque pointer to be passed to the dynamically called function.
273         @return Zero on success, or -1 on error.
274
275         This function is identical to osrfAppRegisterMethod(), except that it also installs
276         a method-specific opaque pointer.  When we call the corresponding function at
277         run time, this pointer will be available to the function via the method context.
278 */
279 int osrfAppRegisterExtendedMethod( const char* appName, const char* methodName,
280                 const char* symbolName, const char* notes, int argc, int options, void * user_data ) {
281
282         if( !appName || ! methodName  ) return -1;
283
284         osrfApplication* app = _osrfAppFindApplication(appName);
285         if(!app) {
286                 osrfLogWarning( OSRF_LOG_MARK, "Unable to locate application %s", appName );
287                 return -1;
288         }
289
290         osrfLogDebug( OSRF_LOG_MARK, "Registering method %s for app %s", methodName, appName );
291
292         osrfMethod* method = _osrfAppBuildMethod(
293                 methodName, symbolName, notes, argc, options, user_data );
294         method->options = options;
295
296         /* plug the method into the list of methods */
297         osrfHashSet( app->methods, method, method->name );
298
299         if( options & OSRF_METHOD_STREAMING ) { /* build the atomic counterpart */
300                 int newops = options | OSRF_METHOD_ATOMIC;
301                 osrfMethod* atomicMethod = _osrfAppBuildMethod(
302                         methodName, symbolName, notes, argc, newops, user_data );
303                 osrfHashSet( app->methods, atomicMethod, atomicMethod->name );
304         }
305
306         return 0;
307 }
308
309 /**
310         @brief Allocate and populate an osrfMethod.
311         @param methodName Name of the method.
312         @param symbolName Name of the function that implements the method.
313         @param notes Remarks documenting the method.
314         @param argc Minimum number of arguments to the method.
315         @param options Bit switches setting various options.
316         @param user_data An opaque pointer to be passed in the method context.
317         @return Pointer to the newly allocated osrfMethod.
318 */
319 static osrfMethod* _osrfAppBuildMethod( const char* methodName, const char* symbolName,
320                 const char* notes, int argc, int options, void* user_data ) {
321
322         osrfMethod* method      = safe_malloc(sizeof(osrfMethod));
323
324         if( !methodName )
325                 methodName = "";  // should never happen
326
327         if( options & OSRF_METHOD_ATOMIC ) {
328                 // Append ".atomic" to the name, and make the method streaming
329                 char mb[ strlen( methodName ) + 8 ];
330                 sprintf( mb, "%s.atomic", methodName );
331                 method->name        = strdup( mb );
332                 options |= OSRF_METHOD_STREAMING;
333         } else {
334                 method->name        = strdup(methodName);
335         }
336
337         if(symbolName)
338                 method->symbol      = strdup(symbolName);
339         else
340                 method->symbol      = NULL;
341
342         if(notes)
343                 method->notes       = strdup(notes);
344         else
345                 method->notes       = NULL;
346
347         method->argc            = argc;
348         method->options         = options;
349
350         if(user_data)
351                 method->userData    = user_data;
352
353         return method;
354 }
355
356 /**
357         @brief Register all of the system methods for this application.
358         @param app Application name.
359
360         A client can call these methods the same way it calls application-specific methods,
361         but they are implemented by functions here in this module, not by functions in the
362         shared object.
363 */
364 static void _osrfAppRegisterSysMethods( const char* app ) {
365
366         osrfAppRegisterMethod(
367                         app, OSRF_SYSMETHOD_INTROSPECT, NULL,
368                         "Return a list of methods whose names have the same initial "
369                         "substring as that of the provided method name PARAMS( methodNameSubstring )",
370                         1, OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
371
372         osrfAppRegisterMethod(
373                         app, OSRF_SYSMETHOD_INTROSPECT_ALL, NULL,
374                         "Returns a complete list of methods. PARAMS()", 0,
375                         OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
376
377         osrfAppRegisterMethod(
378                         app, OSRF_SYSMETHOD_ECHO, NULL,
379                         "Echos all data sent to the server back to the client. PARAMS([a, b, ...])", 0,
380                         OSRF_METHOD_SYSTEM | OSRF_METHOD_STREAMING );
381 }
382
383 /**
384         @brief Look up an application by name in the application registry.
385         @param name The name of the application.
386         @return Pointer to the corresponding osrfApplication if found, or NULL if not.
387 */
388 static inline osrfApplication* _osrfAppFindApplication( const char* name ) {
389         return (osrfApplication*) osrfHashGet(_osrfAppHash, name);
390 }
391
392 /**
393         @brief Look up a method by name for a given application.
394         @param app Pointer to the osrfApplication that owns the method.
395         @param methodName Name of the method to find.
396         @return Pointer to the corresponding osrfMethod if found, or NULL if not.
397 */
398 static inline osrfMethod* osrfAppFindMethod( osrfApplication* app, const char* methodName ) {
399         if( !app ) return NULL;
400         return (osrfMethod*) osrfHashGet( app->methods, methodName );
401 }
402
403 /**
404         @brief Look up a method by name for an application with a given name.
405         @param appName Name of the osrfApplication.
406         @param methodName Name of the method to find.
407         @return Pointer to the corresponding osrfMethod if found, or NULL if not.
408 */
409 osrfMethod* _osrfAppFindMethod( const char* appName, const char* methodName ) {
410         if( !appName ) return NULL;
411         return osrfAppFindMethod( _osrfAppFindApplication(appName), methodName );
412 }
413
414 /**
415         @brief Call the function that implements a specified method.
416         @param appName Name of the application.
417         @param methodName Name of the method.
418         @param ses Pointer to the current application session.
419         @param reqId The request id of the request invoking the method.
420         @param params Pointer to a jsonObject encoding the parameters to the method.
421         @return Zero if successful, or -1 upon failure.
422
423         If we can't find a function corresponding to the method, or if we call it and it returns
424         a negative return code, send a STATUS message to the client to report an exception.
425
426         A return code of -1 means that the @a appName, @a methodName, or @a ses parameter was NULL.
427 */
428 int osrfAppRunMethod( const char* appName, const char* methodName,
429                 osrfAppSession* ses, int reqId, jsonObject* params ) {
430
431         if( !(appName && methodName && ses) ) return -1;
432
433         // Find the application, and then find the method for it
434         osrfApplication* app = _osrfAppFindApplication(appName);
435         if( !app )
436                 return osrfAppRequestRespondException( ses,
437                                 reqId, "Application not found: %s", appName );
438
439         osrfMethod* method = osrfAppFindMethod( app, methodName );
440         if( !method )
441                 return osrfAppRequestRespondException( ses, reqId,
442                                 "Method [%s] not found for service %s", methodName, appName );
443
444         #ifdef OSRF_STRICT_PARAMS
445         if( method->argc > 0 ) {
446                 // Make sure that the client has passed at least the minimum number of arguments.
447                 if(!params || params->type != JSON_ARRAY || params->size < method->argc )
448                         return osrfAppRequestRespondException( ses, reqId,
449                                 "Not enough params for method %s / service %s", methodName, appName );
450         }
451         #endif
452
453         // Build an osrfMethodContext, which we will pass by pointer to the function.
454         osrfMethodContext context;
455
456         context.session = ses;
457         context.method = method;
458         context.params = params;
459         context.request = reqId;
460         context.responses = NULL;
461
462         int retcode = 0;
463
464         if( method->options & OSRF_METHOD_SYSTEM ) {
465                 retcode = _osrfAppRunSystemMethod(&context);
466
467         } else {
468
469                 // Function pointer through which we will call the function dynamically
470                 int (*meth) (osrfMethodContext*);
471
472                 // Open the function that implements the method
473                 meth = dlsym(app->handle, method->symbol);
474
475                 const char* error = dlerror();
476                 if( error != NULL ) {
477                         return osrfAppRequestRespondException( ses, reqId,
478                                 "Unable to execute method [%s] for service %s", methodName, appName );
479                 }
480
481                 // Run it
482                 retcode = meth( &context );
483         }
484
485         if(retcode < 0)
486                 return osrfAppRequestRespondException(
487                                 ses, reqId, "An unknown server error occurred" );
488
489         return _osrfAppPostProcess( &context, retcode );
490 }
491
492 /**
493         @brief Either send or enqueue a response to a client.
494         @param ctx Pointer to the current method context.
495         @param data Pointer to the response, in the form of a jsonObject.
496         @return Zero if successful, or -1 upon error.  The only recognized errors are if either
497         the @a context pointer or its method pointer is NULL.
498
499         For an atomic method, add a copy of the response data to a cache within the method
500         context, to be sent later.  Otherwise, send a RESULT message to the client, with the
501         results in @a data.
502
503         Note that, for an atomic method, this function is equivalent to osrfAppRespondComplete():
504         we send the STATUS message after the method returns, and not before.
505 */
506 int osrfAppRespond( osrfMethodContext* ctx, const jsonObject* data ) {
507         return _osrfAppRespond( ctx, data, 0 );
508 }
509
510 /**
511         @brief Either send or enqueue a response to a client, with a completion notice.
512         @param context Pointer to the current method context.
513         @param data Pointer to the response, in the form of a jsonObject.
514         @return Zero if successful, or -1 upon error.  The only recognized errors are if either
515         the @a context pointer or its method pointer is NULL.
516
517         For an atomic method, add a copy of the response data to a cache within the method
518         context, to be sent later.  Otherwise, send a RESULT message to the client, with the
519         results in @a data.  Also send a STATUS message to indicate that the response is complete.
520
521         Note that, for an atomic method, this function is equivalent to osrfAppRespond(): we
522         send the STATUS message after the method returns, and not before.
523 */
524 int osrfAppRespondComplete( osrfMethodContext* context, const jsonObject* data ) {
525         return _osrfAppRespond( context, data, 1 );
526 }
527
528 /**
529         @brief Either send or enqueue a response to a client, optionally with a completion notice.
530         @param ctx Pointer to the method context.
531         @param data Pointer to the response, in the form of a jsonObject.
532         @param complete Boolean: if true, we will accompany the RESULT message with a STATUS
533         message indicating that the response is complete.
534         @return Zero if successful, or -1 upon error.  The only recognized errors are if either
535         the @a ctx pointer or its method pointer is NULL.
536
537         For an atomic method, add a copy of the response data to a cache within the method
538         context, to be sent later.  In this case the @a complete parameter has no effect,
539         because we'll send the STATUS message later when we send the cached results.
540
541         If the method is cachable but not atomic, do nothing, ignoring the results in @a data.
542         Apparently there are no cachable methods at this writing.  If we ever invent some, we
543         may need to revisit this function.
544
545         If the method is neither atomic nor cachable, then send a RESULT message to the client,
546         with the results in @a data.  If @a complete is true, also send a STATUS message to
547         indicate that the response is complete.
548 */
549 static int _osrfAppRespond( osrfMethodContext* ctx, const jsonObject* data, int complete ) {
550         if(!(ctx && ctx->method)) return -1;
551
552         if( ctx->method->options & OSRF_METHOD_ATOMIC ) {
553                 osrfLogDebug( OSRF_LOG_MARK,
554                         "Adding responses to stash for atomic method %s", ctx->method->name );
555
556                 // If we don't already have one, create a JSON_ARRAY to serve as a cache.
557                 if( ctx->responses == NULL )
558                         ctx->responses = jsonNewObjectType( JSON_ARRAY );
559
560                 // Add a copy of the data object to the cache.
561                 if ( data != NULL )
562                         jsonObjectPush( ctx->responses, jsonObjectClone(data) );
563         }
564
565         if( !(ctx->method->options & OSRF_METHOD_ATOMIC ) &&
566                         !(ctx->method->options & OSRF_METHOD_CACHABLE) ) {
567
568                 if(complete)
569                         osrfAppRequestRespondComplete( ctx->session, ctx->request, data );
570                 else
571                         osrfAppRequestRespond( ctx->session, ctx->request, data );
572         }
573
574         return 0;
575 }
576
577 /**
578         @brief Finish up the processing of a request.
579         @param ctx Pointer to the method context.
580         @param retcode The return code from the method's function.
581         @return 0 if successfull, or -1 upon error.
582
583         For an atomic method: send whatever responses we have been saving up, together with a
584         STATUS message to say that we're finished.
585
586         For a non-atomic method: if the return code from the method is greater than zero, just
587         send the STATUS message.  If the return code is zero, do nothing; the method presumably
588         sent the STATUS message on its own.
589 */
590 static int _osrfAppPostProcess( osrfMethodContext* ctx, int retcode ) {
591         if(!(ctx && ctx->method)) return -1;
592
593         osrfLogDebug( OSRF_LOG_MARK, "Postprocessing method %s with retcode %d",
594                         ctx->method->name, retcode );
595
596         if(ctx->responses) {
597                 // We have cached responses to return, collected in a JSON ARRAY (we haven't sent
598                 // any responses yet).  Now send them all at once, followed by a STATUS message
599                 // to say that we're finished.
600                 osrfAppRequestRespondComplete( ctx->session, ctx->request, ctx->responses );
601                 jsonObjectFree(ctx->responses);
602                 ctx->responses = NULL;
603
604         } else {
605                 // We have no cached responses to return.
606                 if( retcode > 0 )
607                         // Send a STATUS message to say that we're finished.
608                         osrfAppSessionStatus( ctx->session, OSRF_STATUS_COMPLETE,
609                                         "osrfConnectStatus", ctx->request, "Request Complete" );
610         }
611
612         return 0;
613 }
614
615 /**
616         @brief Send a STATUS message to the client, notifying it of an error.
617         @param ses Pointer to the current application session.
618         @param request Request ID of the request.
619         @param msg A printf-style format string defining an explanatory message to be sent to
620         the client.  Subsequent parameters, if any, will be formatted and inserted into the
621         resulting output string.
622         @return -1 if the @a ses parameter is NULL; otherwise zero.
623 */
624 int osrfAppRequestRespondException( osrfAppSession* ses, int request, const char* msg, ... ) {
625         if(!ses) return -1;
626         if(!msg) msg = "";
627         VA_LIST_TO_STRING(msg);
628         osrfLogWarning( OSRF_LOG_MARK,  "Returning method exception with message: %s", VA_BUF );
629         osrfAppSessionStatus( ses, OSRF_STATUS_NOTFOUND, "osrfMethodException", request,  VA_BUF );
630         return 0;
631 }
632
633 /**
634         @brief Introspect a specified method.
635         @param ctx Pointer to the method context.
636         @param method Pointer to the osrfMethod for the specified method.
637         @param resp Pointer to the jsonObject into which method information will be placed.
638
639         Treating the @a resp object as a JSON_HASH, insert entries for various bits of information
640         about the specified method.
641 */
642 static void _osrfAppSetIntrospectMethod( osrfMethodContext* ctx, const osrfMethod* method,
643                 jsonObject* resp ) {
644         if(!(ctx && resp)) return;
645
646         jsonObjectSetKey(resp, "api_name",  jsonNewObject(method->name));
647         jsonObjectSetKey(resp, "method",    jsonNewObject(method->symbol));
648         jsonObjectSetKey(resp, "service",   jsonNewObject(ctx->session->remote_service));
649         jsonObjectSetKey(resp, "notes",     jsonNewObject(method->notes));
650         jsonObjectSetKey(resp, "argc",      jsonNewNumberObject(method->argc));
651
652         jsonObjectSetKey(resp, "sysmethod",
653                         jsonNewNumberObject( (method->options & OSRF_METHOD_SYSTEM) ? 1 : 0 ));
654         jsonObjectSetKey(resp, "atomic",
655                         jsonNewNumberObject( (method->options & OSRF_METHOD_ATOMIC) ? 1 : 0 ));
656         jsonObjectSetKey(resp, "cachable",
657                         jsonNewNumberObject( (method->options & OSRF_METHOD_CACHABLE) ? 1 : 0 ));
658 }
659
660 /**
661         @brief Run the requested system method.
662         @param ctx The method context.
663         @return Zero if the method is run successfully; -1 if the method was not run; 1 if the
664         method was run and the application code now needs to send a 'request complete' message.
665
666         A system method is a well known method implemented here for all servers.  Instead of
667         looking in the shared object, branch on the method name and call the corresponding
668         function.
669 */
670 static int _osrfAppRunSystemMethod(osrfMethodContext* ctx) {
671         if( osrfMethodVerifyContext( ctx ) < 0 ) {
672                 osrfLogError( OSRF_LOG_MARK,  "_osrfAppRunSystemMethod: Received invalid method context" );
673                 return -1;
674         }
675
676         if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ALL ) ||
677                         !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ALL_ATOMIC )) {
678                 return osrfAppIntrospectAll(ctx);
679         }
680
681         if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT ) ||
682                         !strcmp(ctx->method->name, OSRF_SYSMETHOD_INTROSPECT_ATOMIC )) {
683                 return osrfAppIntrospect(ctx);
684         }
685
686         if( !strcmp(ctx->method->name, OSRF_SYSMETHOD_ECHO ) ||
687                         !strcmp(ctx->method->name, OSRF_SYSMETHOD_ECHO_ATOMIC )) {
688                 return osrfAppEcho(ctx);
689         }
690
691         osrfAppRequestRespondException( ctx->session,
692                         ctx->request, "System method implementation not found");
693
694         return 0;
695 }
696
697 /**
698         @brief Run the introspect method for a specified method or group of methods.
699         @param ctx Pointer to the method context.
700         @return 1 if successful, or if no search target is specified as a parameter; -1 if unable
701         to find a pointer to the application.
702
703         Traverse the list of methods, and report on each one whose name starts with the specified
704         search target.  In effect, the search target ends with an implicit wild card.
705 */
706 static int osrfAppIntrospect( osrfMethodContext* ctx ) {
707
708         // Get the name of the method to introspect
709         const char* methodSubstring = jsonObjectGetString( jsonObjectGetIndex(ctx->params, 0) );
710         if( !methodSubstring )
711                 return 1; /* respond with no methods */
712
713         // Get a pointer to the application
714         osrfApplication* app = _osrfAppFindApplication( ctx->session->remote_service );
715         if( !app )
716                 return -1;   // Oops, no application...
717
718         int len = 0;
719         osrfHashIterator* itr = osrfNewHashIterator(app->methods);
720         osrfMethod* method;
721
722         while( (method = osrfHashIteratorNext(itr)) ) {
723                 if( (len = strlen(methodSubstring)) <= strlen(method->name) ) {
724                         if( !strncmp( method->name, methodSubstring, len) ) {
725                                 jsonObject* resp = jsonNewObject(NULL);
726                                 _osrfAppSetIntrospectMethod( ctx, method, resp );
727                                 osrfAppRespond(ctx, resp);
728                                 jsonObjectFree(resp);
729                         }
730                 }
731         }
732
733         osrfHashIteratorFree(itr);
734         return 1;
735 }
736
737 /**
738         @brief Run the implement_all method.
739         @param ctx Pointer to the method context.
740         @return 1 if successful, or -1 if unable to find a pointer to the application.
741
742         Report on all of the methods of the application.
743 */
744 static int osrfAppIntrospectAll( osrfMethodContext* ctx ) {
745         osrfApplication* app = _osrfAppFindApplication( ctx->session->remote_service );
746
747         if(app) {
748                 osrfHashIterator* itr = osrfNewHashIterator(app->methods);
749                 osrfMethod* method;
750                 while( (method = osrfHashIteratorNext(itr)) ) {
751                         jsonObject* resp = jsonNewObject(NULL);
752                         _osrfAppSetIntrospectMethod( ctx, method, resp );
753                         osrfAppRespond(ctx, resp);
754                         jsonObjectFree(resp);
755                 }
756                 osrfHashIteratorFree(itr);
757                 return 1;
758         } else
759                 return -1;
760 }
761
762 /**
763         @brief Run the echo method.
764         @param ctx Pointer to the method context.
765         @return -1 if the method context is invalid or corrupted; otherwise 1.
766
767         Send the client a copy of each parameter.
768 */
769 static int osrfAppEcho( osrfMethodContext* ctx ) {
770         if( osrfMethodVerifyContext( ctx ) < 0 ) {
771                 osrfLogError( OSRF_LOG_MARK,  "osrfAppEcho: Received invalid method context" );
772                 return -1;
773         }
774
775         int i;
776         for( i = 0; i < ctx->params->size; i++ ) {
777                 const jsonObject* str = jsonObjectGetIndex(ctx->params,i);
778                 osrfAppRespond(ctx, str);
779         }
780         return 1;
781 }
782
783 /**
784         @brief Perform a series of sanity tests on an osrfMethodContext.
785         @param ctx Pointer to the osrfMethodContext to be checked.
786         @return Zero if the osrfMethodContext passes all tests, or -1 if it doesn't.
787 */
788 int osrfMethodVerifyContext( osrfMethodContext* ctx )
789 {
790         if( !ctx ) {
791                 osrfLogError( OSRF_LOG_MARK,  "Context is NULL in app request" );
792                 return -1;
793         }
794
795         if( !ctx->session ) {
796                 osrfLogError( OSRF_LOG_MARK, "Session is NULL in app request" );
797                 return -1;
798         }
799
800         if( !ctx->method )
801         {
802                 osrfLogError( OSRF_LOG_MARK, "Method is NULL in app request" );
803                 return -1;
804         }
805
806         if( ctx->method->argc ) {
807                 if( !ctx->params ) {
808                         osrfLogError( OSRF_LOG_MARK,
809                                 "Params is NULL in app request %s", ctx->method->name );
810                         return -1;
811                 }
812                 if( ctx->params->type != JSON_ARRAY ) {
813                         osrfLogError( OSRF_LOG_MARK,
814                                 "'params' is not a JSON array for method %s", ctx->method->name );
815                         return -1;
816                 }
817         }
818
819         if( !ctx->method->name ) {
820                 osrfLogError( OSRF_LOG_MARK, "Method name is NULL" );
821                  return -1;
822         }
823
824         // Log the call, with the method and parameters
825         char* params_str = jsonObjectToJSON( ctx->params );
826         if( params_str ) {
827                 osrfLogInfo( OSRF_LOG_MARK, "CALL:\t%s %s - %s",
828                          ctx->session->remote_service, ctx->method->name, params_str );
829                 free( params_str );
830         }
831         return 0;
832 }