2 * GPAC - Multimedia Framework C SDK
\r
4 * Copyright (c) Jean Le Feuvre 2000-2005
\r
5 * All rights reserved
\r
7 * This file is part of GPAC / common tools sub-project
\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
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
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
25 #ifndef _GF_MODULE_H_
\r
26 #define _GF_MODULE_H_
\r
33 * \file <gpac/module.h>
\r
34 * \brief plugable module functions.
\r
38 * \addtogroup mods_grp plugable modules
\r
39 * \ingroup utils_grp
\r
40 * \brief Plugable Module functions
\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
46 * Bool QueryInterface(u32 interface_type);
\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
50 GF_BaseInterface *LoadInterface(u32 interface_type);
\r
52 * This function is used to load an interface. It returns the interface object, NULL if error.\n
\r
54 void ShutdownInterface(GF_BaseInterface *interface);
\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
60 GF_DECL_MODULE_INTERFACE
\r
67 #include <gpac/config_file.h>
\r
69 typedef struct __tag_mod_man GF_ModuleManager;
\r
72 *\brief common module interface
\r
75 *This is the module interface declaration macro. It must be placed first in an interface structure declaration.
\r
77 #define GF_DECL_MODULE_INTERFACE \
\r
78 u32 InterfaceType; \
\r
79 const char *module_name; \
\r
80 const char *author_name; \
\r
84 *\brief Base Interface
\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
92 GF_DECL_MODULE_INTERFACE
\r
96 *\brief module interface registration
\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
105 *This is a sample GPAC codec interface declaration:
\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
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
122 *\brief module manager construtcor
\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
130 GF_ModuleManager *gf_modules_new(const char *directory, GF_Config *cfgFile);
\r
132 *\brief module manager destructor
\r
134 *Destroys the module manager
\r
135 *\param pm the module manager
\r
137 void gf_modules_del(GF_ModuleManager *pm);
\r
139 *\brief refreshes modules
\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
145 u32 gf_modules_refresh(GF_ModuleManager *pm);
\r
148 *\brief get module count
\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
154 u32 gf_modules_get_count(GF_ModuleManager *pm);
\r
157 *\brief get module file name
\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
164 const char *gf_modules_get_file_name(GF_ModuleManager *pm, u32 index);
\r
167 *\brief loads an interface
\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
175 GF_BaseInterface *gf_modules_load_interface(GF_ModuleManager *pm, u32 index, u32 InterfaceFamily);
\r
178 *\brief loads an interface by module name
\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
186 GF_BaseInterface *gf_modules_load_interface_by_name(GF_ModuleManager *pm, const char *mod_name, u32 InterfaceFamily);
\r
189 *\brief interface shutdown
\r
191 *Closes an interface
\r
192 *\param interface_obj the interface to close
\r
194 GF_Err gf_modules_close_interface(GF_BaseInterface *interface_obj);
\r
197 *\brief interface option query
\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
205 const char *gf_modules_get_option(GF_BaseInterface *interface_obj, const char *secName, const char *keyName);
\r
207 *\brief interface option update
\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
216 GF_Err gf_modules_set_option(GF_BaseInterface *interface_obj, const char *secName, const char *keyName, const char *keyValue);
\r
219 *\brief get config fiole
\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
225 GF_Config *gf_modules_get_config(GF_BaseInterface *ifce);
\r
234 #endif /*_GF_MODULE_H_*/
\r