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