gnunet_plugin_lib.h (4858B)
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 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 #if ! defined (__GNUNET_UTIL_LIB_H_INSIDE__) 22 #error "Only <gnunet_util_lib.h> can be included directly." 23 #endif 24 25 /** 26 * @addtogroup libgnunetutil 27 * Multi-function utilities library for GNUnet programs 28 * @{ 29 * 30 * @author Christian Grothoff 31 * 32 * @file 33 * Plugin loading and unloading 34 * 35 * @defgroup plugin Plugin library 36 * Plugin loading and unloading 37 * @{ 38 */ 39 40 #ifndef GNUNET_PLUGIN_LIB_H 41 #define GNUNET_PLUGIN_LIB_H 42 43 #ifdef __cplusplus 44 extern "C" 45 { 46 #if 0 /* keep Emacsens' auto-indent happy */ 47 } 48 #endif 49 #endif 50 51 52 /** 53 * Signature of any function exported by a plugin. 54 * 55 * @param arg argument to the function (context) 56 * @return some pointer, NULL if the plugin was 57 * shutdown or if there was an error, otherwise 58 * the plugin's API on success 59 */ 60 typedef void * 61 (*GNUNET_PLUGIN_Callback) (void *arg); 62 63 64 /** 65 * Test if a plugin exists. 66 * 67 * Note that the library must export a symbol called 68 * "library_name_init" for the test to succeed. 69 * 70 * @param pd project data with library search path 71 * @param library_name name of the plugin to test if it is installed 72 * @return #GNUNET_YES if the plugin exists, #GNUNET_NO if not 73 */ 74 enum GNUNET_GenericReturnValue 75 GNUNET_PLUGIN_test (const struct GNUNET_OS_ProjectData *pd, 76 const char *library_name); 77 78 79 /** 80 * Setup plugin (runs the "init" callback and returns whatever "init" 81 * returned). If "init" returns NULL, the plugin is unloaded. 82 * 83 * Note that the library must export symbols called 84 * "library_name_init" and "library_name_done". These will be called 85 * when the library is loaded and unloaded respectively. 86 * 87 * @param pd project data with library search path 88 * @param library_name name of the plugin to load 89 * @param arg argument to the plugin initialization function 90 * @return whatever the initialization function returned, NULL on error 91 */ 92 void * 93 GNUNET_PLUGIN_load (const struct GNUNET_OS_ProjectData *pd, 94 const char *library_name, 95 void *arg); 96 97 98 /** 99 * Signature of a function called by #GNUNET_PLUGIN_load_all(). 100 * 101 * @param cls closure 102 * @param library_name full name of the library (to be used with 103 * #GNUNET_PLUGIN_unload) 104 * @param lib_ret return value from the initialization function 105 * of the library (same as what #GNUNET_PLUGIN_load would 106 * have returned for the given library name) 107 */ 108 typedef void 109 (*GNUNET_PLUGIN_LoaderCallback) (void *cls, 110 const char *library_name, 111 void *lib_ret); 112 113 114 /** 115 * Load all compatible plugins with the given base name. 116 * 117 * Note that the library must export symbols called 118 * "basename_ANYTHING_init" and "basename_ANYTHING__done". These will 119 * be called when the library is loaded and unloaded respectively. 120 * 121 * @param pd project data with library search path 122 * @param basename basename of the plugins to load 123 * @param arg argument to the plugin initialization function 124 * @param cb function to call for each plugin found 125 * @param cb_cls closure for @a cb 126 */ 127 void 128 GNUNET_PLUGIN_load_all (const struct GNUNET_OS_ProjectData *pd, 129 const char *basename, 130 void *arg, 131 GNUNET_PLUGIN_LoaderCallback cb, 132 void *cb_cls); 133 134 135 /** 136 * Unload plugin (runs the "done" callback and returns whatever "done" 137 * returned). The plugin is then unloaded. 138 * 139 * @param library_name name of the plugin to unload 140 * @param arg argument to the plugin shutdown function 141 * @return whatever the shutdown function returned, typically NULL 142 * or a "char *" representing the error message 143 */ 144 void * 145 GNUNET_PLUGIN_unload (const char *library_name, 146 void *arg); 147 148 149 #if 0 /* keep Emacsens' auto-indent happy */ 150 { 151 #endif 152 #ifdef __cplusplus 153 } 154 #endif 155 156 /* ifndef GNUNET_PLUGIN_LIB_H */ 157 #endif 158 159 /** @} */ /* end of group */ 160 161 /** @} */ /* end of group addition */ 162 163 /* end of gnunet_plugin_lib.h */