src/plugin/plugin.h

   1 /** @file plugin.h
   2  *  Declarations for the core plugin system
   3 */
   4 /*  2ooM: The Master of Orion II Reverse Engineering Project
   5  *  Copyright (C) 2006 Nick Bowler
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License
  18  *  along with this program; if not, write to the Free Software
  19  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  20  **
  21  * $HeadURL$
  22  * $Date$
  23  * $Revision$
  24  * $Author$
  25  */
  26
  27 #ifndef _PLUGIN_H
  28 #define _PLUGIN_H
  29
  30 /** Module name for logging */
  31 #define PLUGIN_MODULENAME "plugin"
  32
  33 /**@defgroup PluginCore Plugin core system routines
  34  * @{
  35  */
  36
  37 /** Initialize the plugin system.
  38  * Performs any prologue required for dynamically loading plugins, then finds
  39  * plugins to open by searching system and/or user directories for them.
  40  * A plugin is considered loaded if the dynamic linker succeeded, whether any
  41  * plugins have registered with other subsystems such as the VFS is left to
  42  * the caller to determine.
  43  *
  44  * @see plugin_exit
  45  * @return The number of plugins loaded, or -1 on error.
  46  */
  47 int plugin_init(void);
  48
  49 /** Shut down the plugin system.
  50  * Unloads all plugins and then shuts down the plugin system.  Note that all
  51  * subsystems which use plugins must be shut down prior to shutting down
  52  * plugins - otherwise this call will fail and nothing will be unloaded.
  53  *
  54  * @return 0 on successful shutdown, -1 on error.
  55  */
  56 int plugin_exit(void);
  57
  58 /** Load a plugin.
  59  * Attempts to load the specified plugin.  Succeeds if the plugin was
  60  * successfully loaded into memory - success does not indicate that the
  61  * plugin has actually registered with any subsystem such as VFS.  The system
  62  * must first be initialized by a call to plugin_init() before using this
  63  * routine.
  64  *
  65  * @see plugin_init
  66  * @param name The name to attempt to load
  67  * @return 0 on sucess, -1 on failure.
  68  */
  69 int plugin_open(const char *name);
  70
  71 /*@}*/
  72
  73 /**@defgroup PluginServices Plugin service routines
  74  * @{
  75  */
  76
  77 /** Register a plugin service.
  78  * Associates the given tag with a registration function.  Once the service
  79  * is registered, plugins may be used to extend the functionality of that
  80  * service.  Note that, when possible, plugin services should be registered
  81  * prior to the call to plugin_init(), as this will allow the automatic loading
  82  * to work properly.  NOTE: tag must not be modified or freed after registering
  83  * a service.  It is recommended to use a constant string.
  84  *
  85  * @see plugin_delservice
  86  * @see plugin_init
  87  * @param tag Unique string identifier for this service
  88  * @param regfunc Function to call on plugin registration
  89  * @param delfunc Function to call on plugin unregistration
  90  * @return 0 on success, -1 if the service could not be registered
  91  */
  92 int plugin_addservice(const char *tag,
  93                       int (*regfunc)(const char *name, void *data),
  94                       int (*delfunc)(const char *name, void *data));
  95
  96 /** Unregister a plugin service.
  97  * Disassociates the given tag with a registration function.  New plugins which
  98  * attempt to use the old tag will fail.  IMPORTANT: This does not guarantee
  99  * that plugins which use a service are unloaded!  This merely prevents new
 100  * plugins from being registered with the service.
 101  *
 102  * @see plugin_addservice
 103  * @param tag String identifier previously registered with plugin_addservice()
 104  * @return 0 on success, -1 if the service could not be unregistered.
 105  */
 106 int plugin_delservice(const char *tag);
 107
 108 /** Extend a plugin service.
 109  * Provides the given registration data to the service associated with tag,
 110  * extending the service's functionality.  The details of the data to be passed
 111  * to a service depends on that service, usually a struct containing function
 112  * pointers and/or options.
 113  *
 114  * @see plugin_shunservice
 115  * @see plugin_addservice
 116  * @param tag String identifer previously registered with plugin_addservice()
 117  * @param name String identifier for the module to be loaded
 118  * @param data Service-specific data structure of registration data
 119  * @return The return value of the registration function, -1 on failure.
 120  */
 121 int plugin_useservice(const char *tag, const char *name, void *data);
 122
 123 /** Remove extension from a service.
 124  * Provides the given unregistration data to the service associated with tag,
 125  * removing functionality from that service.
 126  *
 127  * @see plugin_useservice
 128  * @see plugin_addservice
 129  * @param tag String identifer previously registered with plugin_addservice()
 130  * @param name String identifier for the module to be unloaded
 131  * @param data Service-specific data structure of unregistration data
 132  * @return The return value of the registration function, -1 on failure.
 133  */
 134 int plugin_shunservice(const char *tag, const char *name, void *data);
 135
 136 /*@}*/
 137
 138 #endif