Manages the loading of system libraries.

The Module class is used to load and maintain the modules that are installed on the user's system. A number of modules are available in the core platform as standard, which you can use in the development of your programs. Examples of existing modules can be found in both the modules: folder.

To load a module and interact with its API, create a module object and initialise it. The following code segment illustrates in C++:

DisplayBase *DisplayBase;
auto modDisplay = objModule::create::global(fl::Name("display"));
if (modDisplay) modDisplay->getPtr(FID_ModBase, &DisplayBase);

To do the same in Fluid:

mGfx = mod.load('display')

It is critical that the module object is permanently retained until the program no longer needs its functionality.

Structure

The Module class consists of the following fields:

Access

Name

Type

Comment

Flags MOF Optional flags.

Name	Description
MOF::LINK_LIBRARY	Module refers to a symbolic link library (e.g. libz DLL or SO)
MOF::STATIC	This flag prevents the loaded module code from being unloaded when the module object is freed. This may be needed in cases where a module is designed with the presumption that it will remain in memory after being loaded by the developer.
MOF::SYSTEM_PROBE	Indicates that the module is being probed. Do not use outside of the core library.

FunctionList const struct Function * Refers to a list of public functions exported by the module.

After initialisation, the FunctionList will refer to an array of public functions that are exported by the module. The FunctionList array consists of Function structs in the following format:

Field	Type	Description
Address	APTR	Pointer to the function entry point
Name	CSTRING	Name of the function
Args	const struct FunctionField *	A list of parameters accepted by the function

ModBase APTR The Module's function base (jump table) must be read from this field.

Initialising a module will create a jump table that is referenced in the ModBase field. The jump table contains vectors that point to all functions that are published by the module. This is considered an internal feature that is hidden by system headers.

If the module is unloaded at any time then the jump table becomes invalid.

Name STRING The name of the module.

This string pointer specifies the name of the module. This name will be used to load the module from the modules: folder, so this field actually reflects part of the module file name. It is also possible to specify sub-directories before the module name itself - this could become more common in module loading in future.

It is critical that file extensions do not appear in the Name string, e.g. display.dll as not all systems may use a .dll extension.

Methods

The following methods are currently supported:

ResolveSymbol Resolves library symbol names to their address pointers.

ERR mod::ResolveSymbol(OBJECTPTR Object, CSTRING Name, APTR * Address)

Parameter	Description
Name	The name of the symbol to resolve.
Address	The address of the symbol will be returned in this parameter.

This method will convert symbol names to their respective address pointers. The module code must have been successfully loaded into memory or an ERR::FieldNotSet error will be returned. If the symbol was not found then ERR::NotFound is returned.

Error Codes

Okay	Operation successful.
NotFound	The symbol was not found.
NoSupport	The host platform does not support this method.
FieldNotSet	The module has not been successfully initialised.
NullArgs	Function call missing argument value(s)

MOF Type

Module flags

Name	Description
MOF::LINK_LIBRARY	Module refers to a symbolic link library (e.g. libz DLL or SO)
MOF::STATIC	This flag prevents the loaded module code from being unloaded when the module object is freed. This may be needed in cases where a module is designed with the presumption that it will remain in memory after being loaded by the developer.
MOF::SYSTEM_PROBE	Indicates that the module is being probed. Do not use outside of the core library.

Function Structure

Function list array structure

Field	Type	Description
Address	APTR	Pointer to the function entry point
Name	CSTRING	Name of the function
Args	const struct FunctionField *	A list of parameters accepted by the function

Module Class

Structure

Methods

MOF Type

Function Structure