plugable modules
[utils]

Plugable Module functions. More...


Classes

struct  GF_BaseInterface
 Base Interface. More...
struct  GF_InterfaceRegister
 Interface Registry. More...

Defines

#define GF_DECL_MODULE_INTERFACE
 common module interface
#define GF_REGISTER_MODULE_INTERFACE(_ifce, _ifce_type, _ifce_name, _ifce_author)
 module interface registration
#define GPAC_MODULE_EXPORT
 module interface function export. Modules that can be compiled in libgpac rather than in sharde libraries shall use this macro to declare the 3 exported functions
#define GPAC_MODULE_STATIC_DELARATION(__name)
 module interface function export. Modules that can be compiled in libgpac rather than in sharde libraries shall use this macro to declare the 3 exported functions

Typedefs

typedef struct __tag_mod_man GF_ModuleManager

Functions

GF_ModuleManager * gf_modules_new (const char *directory, GF_Config *cfgFile)
 module manager construtcor
void gf_modules_del (GF_ModuleManager *pm)
 module manager destructor
u32 gf_modules_refresh (GF_ModuleManager *pm)
 refreshes modules
u32 gf_modules_get_count (GF_ModuleManager *pm)
 get module count
const char ** gf_modules_get_module_directories (GF_ModuleManager *pm, u32 *num_dirs)
 get all modules directories
const char * gf_modules_get_file_name (GF_ModuleManager *pm, u32 index)
 get module file name
const char * gf_module_get_file_name (GF_BaseInterface *ifce)
 get module file name
GF_BaseInterfacegf_modules_load_interface (GF_ModuleManager *pm, u32 index, u32 InterfaceFamily)
 loads an interface
GF_BaseInterfacegf_modules_load_interface_by_name (GF_ModuleManager *pm, const char *mod_name, u32 InterfaceFamily)
 loads an interface by module name
GF_Err gf_modules_close_interface (GF_BaseInterface *interface_obj)
 interface shutdown
const char * gf_modules_get_option (GF_BaseInterface *interface_obj, const char *secName, const char *keyName)
 interface option query
GF_Err gf_modules_set_option (GF_BaseInterface *interface_obj, const char *secName, const char *keyName, const char *keyValue)
 interface option update
GF_Config * gf_modules_get_config (GF_BaseInterface *ifce)
 get config fiole


Detailed Description

This section documents the plugable module functions of the GPAC framework. A module is a dynamic/shared library providing one or several interfaces to the GPAC framework. A module cannot provide several interfaces of the same type. Each module must export the following functions:
        u32 *QueryInterfaces(u32 interface_type);
This function is used to query supported interfaces. It returns a zero-terminated array of supported interface types.
        GF_BaseInterface *LoadInterface(u32 interface_type);
This function is used to load an interface. It returns the interface object, NULL if error.
        void ShutdownInterface(GF_BaseInterface *interface);
This function is used to destroy an interface.

Each interface must begin with the interface macro in order to be type-casted to the base interface structure.
        struct {
                GF_DECL_MODULE_INTERFACE
                extensions;
        };

Define Documentation

#define GF_DECL_MODULE_INTERFACE

This is the module interface declaration macro. It must be placed first in an interface structure declaration.

#define GF_REGISTER_MODULE_INTERFACE ( _ifce,
_ifce_type,
_ifce_name,
_ifce_author   ) 

This is the module interface registration macro. A module must call this macro whenever creating a new interface.

  • _ifce: interface being registered
  • _ifce_type: the four character code defining the interface type.
  • _ifce_name: a printable string giving the interface name (const char *).
  • _ifce_author: a printable string giving the author name (const char *).
    This is a sample GPAC codec interface declaration:
    GF_BaseInterface *MyDecoderInterfaceLoad() {
            GF_MediaDecoder *ifce;
            GF_SAFEALLOC(ifce, GF_MediaDecoder);
            GF_REGISTER_MODULE_INTERFACE(ifce, GF_MEDIA_DECODER_INTERFACE, "Sample Decoder", "The Author")
            //follows any initialization private to the decoder
            return (GF_BaseInterface *)ifce;
    }
    


Function Documentation

GF_ModuleManager* gf_modules_new ( const char *  directory,
GF_Config *  cfgFile 
)

Constructs a module manager object.

Parameters:
directory absolute path to the directory where the manager shall look for modules
Deprecated:
{Module manager uses now infomation from cfg file}
Parameters:
cfgFile GPAC configuration file handle. If this is NULL, the modules won't be able to share the configuration file with the rest of the GPAC framework.
Returns:
the module manager object

void gf_modules_del ( GF_ModuleManager *  pm  ) 

Destroys the module manager

Parameters:
pm the module manager

u32 gf_modules_refresh ( GF_ModuleManager *  pm  ) 

Refreshes all modules in the manager directory and load unloaded ones

Parameters:
pm the module manager
Returns:
the number of loaded modules

u32 gf_modules_get_count ( GF_ModuleManager *  pm  ) 

Gets the number of modules found in the manager directory

Parameters:
pm the module manager
Returns:
the number of loaded modules

const char** gf_modules_get_module_directories ( GF_ModuleManager *  pm,
u32 *  num_dirs 
)

Update module manager with all modules directories

Parameters:
pm the module manager
num_dirs the number of module directories
Returns:
The list of modules directories

const char* gf_modules_get_file_name ( GF_ModuleManager *  pm,
u32  index 
)

Gets a module shared library file name based on its index

Parameters:
pm the module manager
index the 0-based index of the module to query
Returns:
the name of the shared library module

const char* gf_module_get_file_name ( GF_BaseInterface ifce  ) 

Gets a module shared library file name based on its index

Parameters:
ifce the module instance to query
Returns:
the name of the shared library module

GF_BaseInterface* gf_modules_load_interface ( GF_ModuleManager *  pm,
u32  index,
u32  InterfaceFamily 
)

Loads an interface in the desired module.

Parameters:
pm the module manager
index the 0-based index of the module to load the interface from
InterfaceFamily type of the interface to load
Returns:
the interface object if found and loaded, NULL otherwise.

GF_BaseInterface* gf_modules_load_interface_by_name ( GF_ModuleManager *  pm,
const char *  mod_name,
u32  InterfaceFamily 
)

Loads an interface in the desired module

Parameters:
pm the module manager
mod_name the name of the module (shared library file) or of the interface as declared when registered.
InterfaceFamily type of the interface to load
Returns:
the interface object if found and loaded, NULL otherwise.

GF_Err gf_modules_close_interface ( GF_BaseInterface interface_obj  ) 

Closes an interface

Parameters:
interface_obj the interface to close

const char* gf_modules_get_option ( GF_BaseInterface interface_obj,
const char *  secName,
const char *  keyName 
)

Gets an option from the config file associated with the module manager

Parameters:
interface_obj the interface object used
secName the desired key parent section name
keyName the desired key name
Returns:
the desired key value if found, NULL otherwise.

GF_Err gf_modules_set_option ( GF_BaseInterface interface_obj,
const char *  secName,
const char *  keyName,
const char *  keyValue 
)

Sets an option in the config file associated with the module manager

Parameters:
interface_obj the interface object used
secName the desired key parent section name
keyName the desired key name
keyValue the desired key value
Note:
this will also create both section and key if they are not found in the configuration file

GF_Config* gf_modules_get_config ( GF_BaseInterface ifce  ) 

Gets the configuration file for the module instance

Parameters:
interface_obj the interface object used
Returns:
handle to the config file


doxygen