tstools/DtsEdit/src/gpac/module.h

   1 /*\r
   2  *                      GPAC - Multimedia Framework C SDK\r
   3  *\r
   4  *                      Copyright (c) Jean Le Feuvre 2000-2005 \r
   5  *                                      All rights reserved\r
   6  *\r
   7  *  This file is part of GPAC / common tools sub-project\r
   8  *\r
   9  *  GPAC is free software; you can redistribute it and/or modify\r
  10  *  it under the terms of the GNU Lesser General Public License as published by\r
  11  *  the Free Software Foundation; either version 2, or (at your option)\r
  12  *  any later version.\r
  13  *   \r
  14  *  GPAC is distributed in the hope that it will be useful,\r
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  17  *  GNU Lesser General Public License for more details.\r
  18  *   \r
  19  *  You should have received a copy of the GNU Lesser General Public\r
  20  *  License along with this library; see the file COPYING.  If not, write to\r
  21  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. \r
  22  *\r
  23  */\r
  24 \r
  25 #ifndef _GF_MODULE_H_\r
  26 #define _GF_MODULE_H_\r
  27 \r
  28 #ifdef __cplusplus\r
  29 extern "C" {\r
  30 #endif\r
  31 \r
  32 /*!\r
  33  *      \file <gpac/module.h>\r
  34  *      \brief plugable module functions.\r
  35  */\r
  36 \r
  37 /*!\r
  38  *      \addtogroup mods_grp plugable modules\r
  39  *      \ingroup utils_grp\r
  40  *      \brief Plugable Module functions\r
  41  *\r
  42  *This section documents the plugable module functions of the GPAC framework.\r
  43  *A module is a dynamic/shared library providing one or several interfaces to the GPAC framework.\r
  44  *A module cannot provide several interfaces of the same type. Each module must export the following functions:\r
  45  \code\r
  46  *      Bool QueryInterface(u32 interface_type);\r
  47  \endcode\r
  48  *      This function is used to query supported interfaces. It returns non zero if the module handles this interface type, 0 otherwise.\n\r
  49  \code\r
  50         GF_BaseInterface *LoadInterface(u32 interface_type);\r
  51  \endcode\r
  52  *      This function is used to load an interface. It returns the interface object, NULL if error.\n\r
  53  \code\r
  54         void ShutdownInterface(GF_BaseInterface *interface);\r
  55  \endcode\r
  56  *This function is used to destroy an interface.\n\n\r
  57  *Each interface must begin with the interface macro in order to be type-casted to the base interface structure.\r
  58  \code\r
  59         struct {\r
  60                 GF_DECL_MODULE_INTERFACE\r
  61                 extensions;\r
  62         };\r
  63  \endcode\r
  64  *      @{\r
  65  */\r
  66 \r
  67 #include <gpac/config_file.h>\r
  68 \r
  69 typedef struct __tag_mod_man GF_ModuleManager;\r
  70 \r
  71 /*!\r
  72  *\brief common module interface\r
  73  *\hideinitializer\r
  74  *\r
  75  *This is the module interface declaration macro. It must be placed first in an interface structure declaration.\r
  76 */\r
  77 #define GF_DECL_MODULE_INTERFACE        \\r
  78         u32 InterfaceType;                              \\r
  79         const char *module_name;                \\r
  80         const char *author_name;                \\r
  81         void *HPLUG;                                    \\r
  82 \r
  83 /*!\r
  84  *\brief Base Interface\r
  85  *\r
  86  *This structure represent a base interface, e.g. the minimal interface declaration without functionalities. Each interface is\r
  87  *type-casted to this structure and shall always be checked against its interface type. API Versioning is taken care of in the \r
  88  *interface type itsel, changing at each modification of the interface API\r
  89  */\r
  90 typedef struct\r
  91 {\r
  92         GF_DECL_MODULE_INTERFACE\r
  93 } GF_BaseInterface;\r
  94 \r
  95 /*!\r
  96  *\brief module interface registration\r
  97  *\hideinitializer\r
  98  *\r
  99  *This is the module interface registration macro. A module must call this macro whenever creating a new interface.\r
 100  *- \e _ifce: interface being registered\r
 101  *- \e _ifce_type: the four character code defining the interface type.\r
 102  *- \e _ifce_name: a printable string giving the interface name (const char *).\r
 103  *- \e _ifce_author: a printable string giving the author name (const char *).\r
 104  *\n\r
 105  *This is a sample GPAC codec interface declaration:\r
 106  \code\r
 107 GF_BaseInterface *MyDecoderInterfaceLoad() {\r
 108         GF_MediaDecoder *ifce;\r
 109         GF_SAFEALLOC(ifce, GF_MediaDecoder);\r
 110         GF_REGISTER_MODULE_INTERFACE(ifce, GF_MEDIA_DECODER_INTERFACE, "Sample Decoder", "The Author")\r
 111         //follows any initialization private to the decoder\r
 112         return (GF_BaseInterface *)ifce;\r
 113 }\r
 114  \endcode\r
 115 */\r
 116 #define GF_REGISTER_MODULE_INTERFACE(_ifce, _ifce_type, _ifce_name, _ifce_author) \\r
 117         _ifce->InterfaceType = _ifce_type;      \\r
 118         _ifce->module_name = _ifce_name ? _ifce_name : "unknown";       \\r
 119         _ifce->author_name = _ifce_author ? _ifce_author : "gpac distribution"; \\r
 120         \r
 121 /*!\r
 122  *\brief module manager construtcor\r
 123  *\r
 124  *Constructs a module manager object.\r
 125  *\param directory absolute path to the directory where the manager shall look for modules\r
 126  *\param cfgFile GPAC configuration file handle. If this is NULL, the modules won't be able to share the configuration\r
 127  *file with the rest of the GPAC framework.\r
 128  *\return the module manager object\r
 129 */\r
 130 GF_ModuleManager *gf_modules_new(const char *directory, GF_Config *cfgFile);\r
 131 /*!\r
 132  *\brief module manager destructor\r
 133  *\r
 134  *Destroys the module manager\r
 135  *\param pm the module manager\r
 136  */\r
 137 void gf_modules_del(GF_ModuleManager *pm);\r
 138 /*!\r
 139  *\brief refreshes modules\r
 140  *\r
 141  *Refreshes all modules in the manager directory and load unloaded ones\r
 142  *\param pm the module manager\r
 143  *\return the number of loaded modules\r
 144  */\r
 145 u32 gf_modules_refresh(GF_ModuleManager *pm);\r
 146 \r
 147 /*!\r
 148  *\brief get module count\r
 149  *\r
 150  *Gets the number of modules found in the manager directory\r
 151  *\param pm the module manager\r
 152  *\return the number of loaded modules\r
 153  */\r
 154 u32 gf_modules_get_count(GF_ModuleManager *pm);\r
 155 \r
 156 /*!\r
 157  *\brief get module file name\r
 158  *\r
 159  *Gets a module shared library file name based on its index\r
 160  *\param pm the module manager\r
 161  *\param index the 0-based index of the module to query\r
 162  *\return the name of the shared library module\r
 163  */\r
 164 const char *gf_modules_get_file_name(GF_ModuleManager *pm, u32 index);\r
 165 \r
 166 /*!\r
 167  *\brief loads an interface\r
 168  *\r
 169  *Loads an interface in the desired module.\r
 170  *\param pm the module manager\r
 171  *\param index the 0-based index of the module to load the interface from\r
 172  *\param InterfaceFamily type of the interface to load\r
 173  *\return the interface object if found and loaded, NULL otherwise.\r
 174  */\r
 175 GF_BaseInterface *gf_modules_load_interface(GF_ModuleManager *pm, u32 index, u32 InterfaceFamily);\r
 176 \r
 177 /*!\r
 178  *\brief loads an interface by module name\r
 179  *\r
 180  *Loads an interface in the desired module\r
 181  *\param pm the module manager\r
 182  *\param mod_name the name of the module (shared library file) or of the interface as declared when registered.\r
 183  *\param InterfaceFamily type of the interface to load\r
 184  *\return the interface object if found and loaded, NULL otherwise.\r
 185  */\r
 186 GF_BaseInterface *gf_modules_load_interface_by_name(GF_ModuleManager *pm, const char *mod_name, u32 InterfaceFamily);\r
 187 \r
 188 /*!\r
 189  *\brief interface shutdown\r
 190  *\r
 191  *Closes an interface\r
 192  *\param interface_obj the interface to close\r
 193  */\r
 194 GF_Err gf_modules_close_interface(GF_BaseInterface *interface_obj);\r
 195 \r
 196 /*!\r
 197  *\brief interface option query\r
 198  *\r
 199  *Gets an option from the config file associated with the module manager \r
 200  *\param interface_obj the interface object used\r
 201  *\param secName the desired key parent section name\r
 202  *\param keyName the desired key name\r
 203  *\return the desired key value if found, NULL otherwise.\r
 204  */\r
 205 const char *gf_modules_get_option(GF_BaseInterface *interface_obj, const char *secName, const char *keyName);\r
 206 /*!\r
 207  *\brief interface option update\r
 208  *\r
 209  *Sets an option in the config file associated with the module manager \r
 210  *\param interface_obj the interface object used\r
 211  *\param secName the desired key parent section name\r
 212  *\param keyName the desired key name\r
 213  *\param keyValue the desired key value\r
 214  *\note this will also create both section and key if they are not found in the configuration file\r
 215  */\r
 216 GF_Err gf_modules_set_option(GF_BaseInterface *interface_obj, const char *secName, const char *keyName, const char *keyValue);\r
 217 \r
 218 /*!\r
 219  *\brief get config fiole\r
 220  *\r
 221  *Gets the configuration file for the module instance\r
 222  *\param interface_obj the interface object used\r
 223  *\return handle to the config file\r
 224  */\r
 225 GF_Config *gf_modules_get_config(GF_BaseInterface *ifce);\r
 226 \r
 227 /*! @} */\r
 228 \r
 229 #ifdef __cplusplus\r
 230 }\r
 231 #endif\r
 232 \r
 233 \r
 234 #endif          /*_GF_MODULE_H_*/\r
 235 \r