src/include/gnunet_plugin_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * Plugin loading and unloading
  24  *
  25  * @defgroup plugin  Plugin library
  26  * Plugin loading and unloading
  27  * @{
  28  */
  29
  30 #ifndef GNUNET_PLUGIN_LIB_H
  31 #define GNUNET_PLUGIN_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_common.h"
  42 #include "gnunet_configuration_lib.h"
  43
  44
  45 /**
  46  * Signature of any function exported by a plugin.
  47  *
  48  * @param arg argument to the function (context)
  49  * @return some pointer, NULL if the plugin was
  50  *         shutdown or if there was an error, otherwise
  51  *         the plugin's API on success
  52  */
  53 typedef void *
  54 (*GNUNET_PLUGIN_Callback) (void *arg);
  55
  56
  57 /**
  58  * Test if a plugin exists.
  59  *
  60  * Note that the library must export a symbol called
  61  * "library_name_init" for the test to succeed.
  62  *
  63  * @param library_name name of the plugin to test if it is installed
  64  * @return #GNUNET_YES if the plugin exists, #GNUNET_NO if not
  65  */
  66 int
  67 GNUNET_PLUGIN_test (const char *library_name);
  68
  69
  70 /**
  71  * Setup plugin (runs the "init" callback and returns whatever "init"
  72  * returned).  If "init" returns NULL, the plugin is unloaded.
  73  *
  74  * Note that the library must export symbols called
  75  * "library_name_init" and "library_name_done".  These will be called
  76  * when the library is loaded and unloaded respectively.
  77  *
  78  * @param library_name name of the plugin to load
  79  * @param arg argument to the plugin initialization function
  80  * @return whatever the initialization function returned, NULL on error
  81  */
  82 void *
  83 GNUNET_PLUGIN_load (const char *library_name,
  84                     void *arg);
  85
  86
  87 /**
  88  * Signature of a function called by #GNUNET_PLUGIN_load_all().
  89  *
  90  * @param cls closure
  91  * @param library_name full name of the library (to be used with
  92  *        #GNUNET_PLUGIN_unload)
  93  * @param lib_ret return value from the initialization function
  94  *        of the library (same as what #GNUNET_PLUGIN_load would
  95  *        have returned for the given library name)
  96  */
  97 typedef void
  98 (*GNUNET_PLUGIN_LoaderCallback) (void *cls,
  99                                  const char *library_name,
 100                                  void *lib_ret);
 101
 102
 103 /**
 104  * Load all compatible plugins with the given base name.
 105  *
 106  * Note that the library must export symbols called
 107  * "basename_ANYTHING_init" and "basename_ANYTHING__done".  These will
 108  * be called when the library is loaded and unloaded respectively.
 109  *
 110  * @param basename basename of the plugins to load
 111  * @param arg argument to the plugin initialization function
 112  * @param cb function to call for each plugin found
 113  * @param cb_cls closure for @a cb
 114  */
 115 void
 116 GNUNET_PLUGIN_load_all (const char *basename,
 117                         void *arg,
 118                         GNUNET_PLUGIN_LoaderCallback cb,
 119                         void *cb_cls);
 120
 121
 122 /**
 123  * Unload plugin (runs the "done" callback and returns whatever "done"
 124  * returned).  The plugin is then unloaded.
 125  *
 126  * @param library_name name of the plugin to unload
 127  * @param arg argument to the plugin shutdown function
 128  * @return whatever the shutdown function returned, typically NULL
 129  *         or a "char *" representing the error message
 130  */
 131 void *
 132 GNUNET_PLUGIN_unload (const char *library_name,
 133                       void *arg);
 134
 135
 136 #if 0                           /* keep Emacsens' auto-indent happy */
 137 {
 138 #endif
 139 #ifdef __cplusplus
 140 }
 141 #endif
 142
 143 /* ifndef GNUNET_PLUGIN_LIB_H */
 144 #endif
 145
 146 /** @} */  /* end of group */
 147
 148 /* end of gnunet_plugin_lib.h */