module.h File Reference

plugable dynamic module. More...

#include <gpac/config_file.h>

Data Structures
struct	GF_BaseInterface
	Base Interface. More...
struct	GF_InterfaceRegister
	Interface Registry. More...
#define	GF_DECL_MODULE_INTERFACE
	Plugable Dynamic Modules.
#define	GF_REGISTER_MODULE_INTERFACE(_ifce, _ifce_type, _ifce_name, _ifce_author)
	module interface registration
#define	GPAC_MODULE_EXPORT
	static module declaration
#define	GPAC_MODULE_STATIC_DECLARATION(__name)
	module interface
#define	GF_MODULE_STATIC_DECLARE(_name)    GF_InterfaceRegister *gf_register_module_##_name()
	declare a module for loading
#define	GF_MODULE_LOAD_STATIC(_name)    gf_module_load_static(gf_register_module_##_name)
	load a static module given its name
GF_Err	gf_module_load_static (GF_InterfaceRegister *(*register_module)())
	load a static module given its interface function
u32	gf_modules_count ()
	get module count
const char *	gf_modules_get_file_name (u32 index)
	get module file name
const char *	gf_module_get_file_name (GF_BaseInterface *ifce)
	get module file name
GF_BaseInterface *	gf_modules_load (u32 index, u32 InterfaceFamily)
	loads an interface
GF_BaseInterface *	gf_modules_load_by_name (const char *mod_name, u32 InterfaceFamily)
	loads an interface by module name
GF_Err	gf_modules_close_interface (GF_BaseInterface *interface_obj)
	interface shutdown
GF_BaseInterface *	gf_module_load (u32 ifce_type, const char *name)
	module load
void *	gf_modules_load_filter (u32 index, void *fsess)
	filter module load

Detailed Description

plugable dynamic module.

>

---

Data Structure Documentation

GF_BaseInterface

struct GF_BaseInterface

Base Interface.

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

Plugable Dynamic Modules.

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
	)

module interface registration

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_EXPORT

#define GPAC_MODULE_EXPORT

static module declaration

GPAC_MODULE_STATIC_DECLARATION

#define GPAC_MODULE_STATIC_DECLARATION

(

__name

)

module interface

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()

declare a module for loading

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)

load a static module given its 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

)

load a static module given its interface function

Parameters

register_module

the register interface function

Returns

error if any

gf_modules_count()

u32 gf_modules_count

(

)

get module 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

)

get module file name

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

)

get module file name

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

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
	)

loads an interface by module name

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

Returns

the interface object if found and loaded, NULL otherwise.

gf_modules_close_interface()

GF_Err gf_modules_close_interface

(

GF_BaseInterface *

interface_obj

)

interface shutdown

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
	)

module load

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
	)

filter module load

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