libgpac
Documentation of the core library of GPAC
module.h File Reference

plugable dynamic module. More...

#include <gpac/config_file.h>
#include <gpac/main.h>
+ Include dependency graph for module.h:
+ This graph shows which files directly or indirectly include this file:

Data Structures

struct  GF_BaseInterface
 Base Interface. More...
 
struct  GF_InterfaceRegister
 Interface Registry. More...
 
#define GF_DECL_MODULE_INTERFACE
 Plugable Dynamic Modules. More...
 
#define GF_REGISTER_MODULE_INTERFACE(_ifce, _ifce_type, _ifce_name, _ifce_author)
 module interface registration More...
 
#define GPAC_MODULE_EXPORT
 static module declaration
 
#define GPAC_MODULE_STATIC_DECLARATION(__name)
 module interface More...
 
#define GF_MODULE_STATIC_DECLARE(_name)    GF_InterfaceRegister *gf_register_module_##_name()
 declare a module for loading More...
 
#define GF_MODULE_LOAD_STATIC(_name)    gf_module_load_static(gf_register_module_##_name)
 load a static module given its name More...
 
GF_Err gf_module_load_static (GF_InterfaceRegister *(*register_module)())
 load a static module given its interface function More...
 
u32 gf_modules_count ()
 get module count More...
 
const char * gf_modules_get_file_name (u32 index)
 get module file name More...
 
const char * gf_module_get_file_name (GF_BaseInterface *ifce)
 get module file name More...
 
GF_BaseInterfacegf_modules_load (u32 index, u32 InterfaceFamily)
 loads an interface More...
 
GF_BaseInterfacegf_modules_load_by_name (const char *mod_name, u32 InterfaceFamily, Bool rebrowse_all)
 loads an interface by module name More...
 
GF_Err gf_modules_close_interface (GF_BaseInterface *interface_obj)
 interface shutdown More...
 
GF_BaseInterfacegf_module_load (u32 ifce_type, const char *name)
 module load More...
 
void * gf_modules_load_filter (u32 index, void *fsess)
 filter module load More...
 
const char * gf_module_get_key (GF_BaseInterface *ifce, char *key)
 query module option More...
 
Bool gf_module_get_bool (GF_BaseInterface *ifce, char *key_name)
 query module option as boolean More...
 
Bool gf_module_get_int (GF_BaseInterface *ifce, char *key_name)
 query module option as int More...
 

Detailed Description

>


Data Structure Documentation

◆ GF_BaseInterface

struct GF_BaseInterface

This structure represent a base interface, e.g. the minimal interface declaration without functionalities. Each interface is type-casted to this structure and shall always be checked against its interface type. API Versioning is taken care of in the interface type itsel, changing at each modification of the interface API

Macro Definition Documentation

◆ GF_DECL_MODULE_INTERFACE

#define GF_DECL_MODULE_INTERFACE

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);
uint32_t u32
Definition: setup.h:326

This function is used to query supported interfaces. It returns a zero-terminated array of supported interface types.

GF_BaseInterface *LoadInterface(u32 interface_type);
Base Interface.
Definition: module.h:93

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 {
extensions;
};
#define GF_DECL_MODULE_INTERFACE
Plugable Dynamic Modules.
Definition: module.h:77

common module interface

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

◆ GF_REGISTER_MODULE_INTERFACE

#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;
    }
    #define GF_SAFEALLOC(__ptr, __struct)
    Memory allocation for a structure.
    Definition: tools.h:235
    #define GF_REGISTER_MODULE_INTERFACE(_ifce, _ifce_type, _ifce_name, _ifce_author)
    module interface registration
    Definition: module.h:118

◆ GPAC_MODULE_STATIC_DECLARATION

#define GPAC_MODULE_STATIC_DECLARATION (   __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

◆ GF_MODULE_STATIC_DECLARE

#define GF_MODULE_STATIC_DECLARE (   _name)     GF_InterfaceRegister *gf_register_module_##_name()

When using GPAC as a static library, if GPAC_MODULE_CUSTOM_LOAD is defined, this macro can be used with GF_MODULE_STATIC_DECLARE() and gf_module_refresh() to load individual modules.

Warning
function load_all_modules You will need to patch src/utils/module.c

◆ GF_MODULE_LOAD_STATIC

#define GF_MODULE_LOAD_STATIC (   _name)     gf_module_load_static(gf_register_module_##_name)

Use this function to load a statically compiled module. GF_MODULE_STATIC_DECLARE() should be called before and gf_modules_refresh() after loading all the needed modules.

Parameters
_namethe module name
See also
GF_MODULE_STATIC_DECLARE() gf_modules_refresh()

Function Documentation

◆ gf_module_load_static()

GF_Err gf_module_load_static ( GF_InterfaceRegister *(*)()  register_module)
Parameters
register_modulethe register interface function
Returns
error if any

◆ gf_modules_count()

u32 gf_modules_count ( )

Gets the number of modules found in the manager directory

Returns
the number of loaded modules

◆ gf_modules_get_file_name()

const char* gf_modules_get_file_name ( u32  index)

Gets a module shared library file name based on its index

Parameters
indexthe 0-based index of the module to query
Returns
the name of the shared library module

◆ gf_module_get_file_name()

const char* gf_module_get_file_name ( GF_BaseInterface ifce)

Gets a module shared library file name based on its index

Parameters
ifcethe module instance to query
Returns
the name of the shared library module

◆ gf_modules_load()

GF_BaseInterface* gf_modules_load ( u32  index,
u32  InterfaceFamily 
)

Loads an interface in the desired module.

Parameters
indexthe 0-based index of the module to load the interface from
InterfaceFamilytype of the interface to load
Returns
the interface object if found and loaded, NULL otherwise.

◆ gf_modules_load_by_name()

GF_BaseInterface* gf_modules_load_by_name ( const char *  mod_name,
u32  InterfaceFamily,
Bool  rebrowse_all 
)

Loads an interface in the desired module

Parameters
mod_namethe name of the module (shared library file) or of the interface as declared when registered.
InterfaceFamilytype of the interface to load
rebrowse_allif GF_TRUE, locate an interface for this type if not found by name
Returns
the interface object if found and loaded, NULL otherwise.

◆ gf_modules_close_interface()

GF_Err gf_modules_close_interface ( GF_BaseInterface interface_obj)

Closes an interface

Parameters
interface_objthe interface to close
Returns
error if any

◆ gf_module_load()

GF_BaseInterface* gf_module_load ( u32  ifce_type,
const char *  name 
)

Loads a module based on a preferred name. If not found, check for predefined names for the given interface type in fthe global config and loads by predefined name. If still not found, enumerate modules.

Parameters
ifce_typetype of module interface to load
namename of preferred module
Returns
the loaded module, or NULL if not found

◆ gf_modules_load_filter()

void* gf_modules_load_filter ( u32  index,
void *  fsess 
)

Loads a filter module (not using GF_BaseInterface) from its index. Returns NULL if no such filter.

Parameters
indexindex of the filter module to load
fsessopaque handle passed to the filter loader
Returns
the loaded filter register, or NULL if not found

◆ gf_module_get_key()

const char* gf_module_get_key ( GF_BaseInterface ifce,
char *  key 
)

Loads a key from config in the module options.

Parameters
ifcethe module instance to query
keythe key to query
Returns
the key value or null

◆ gf_module_get_bool()

Bool gf_module_get_bool ( GF_BaseInterface ifce,
char *  key_name 
)

Loads a boolean key from config in the module options.

Parameters
ifcethe module instance to query
key_namethe key to query
Returns
GF_TRUE if key is found and equals yes, true or 1, GF_FALSE otherwise

◆ gf_module_get_int()

Bool gf_module_get_int ( GF_BaseInterface ifce,
char *  key_name 
)

Loads an integer key from config in the module options.

Parameters
ifcethe module instance to query
key_namethe key to query
Returns
integer value of key, 0 if not found