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_BaseInterface *	gf_modules_load (u32 index, u32 InterfaceFamily)
	loads an interface More...
GF_BaseInterface *	gf_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_BaseInterface *	gf_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);

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;
};

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;
  }

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

_name

the 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_module

the 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

index

the 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

ifce	the 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

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_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_name	the name of the module (shared library file) or of the interface as declared when registered.
InterfaceFamily	type of the interface to load
rebrowse_all	if 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_obj

the 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_type	type of module interface to load
name	name 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

index	index of the filter module to load
fsess	opaque 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

ifce	the module instance to query
key	the 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

ifce	the module instance to query
key_name	the 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

ifce	the module instance to query
key_name	the key to query

Returns

integer value of key, 0 if not found