Class Documentation
Module |
1.0 |
ID_MODULE |
Stable |
System |
system/module.h |
January 2004 |
Rocklyte Systems |
Rocklyte Systems, 1996-2004. All rights reserved. |
Description
The Module class is used to load and maintain the modules that are
installed on the Pandora Engine system. A large number of modules are
available in the Pandora Engine as standard, which you can use in the
development of your programs. Examples of existing modules can be found
in both the "system:modules/" and "system:classes/"
directories.
If you want to load a module file for the purpose of utilising its
functionality, you will need to create a Module object and initialise it.
The following code segment illustrates:
struct Module *StringsMod;
struct StringsBase *StringsBase;
if (NewPrivateObject(ID_MODULE, NULL, &StringsMod) IS ERR_Okay) {
SetField(StringsMod, FID_Name, FT_POINTER, "strings");
if (Action(AC_Init, StringsMod, NULL) IS ERR_Okay) {
GetField(StringsMod, FID_ModBase, FT_POINTER, &StringsBase);
}
}
After a Module is initialised there is very little that you need to do
with the object itself, besides reading the Modules's function base from
the ModBase field. Keep in mind that you must not free the Module object
until you are finished with the functions that it provides.
Modules can also be used in scripts if you need to make API calls during
script processing. The Exec method is provided for the purpose of
function execution in scripts. The following example illustrates:
<module name="kernel"/>
<action object="[modkernel]" method="exec"
&function="waittime" &args="3, 500000"/>
</module"/>
Notice that setting the Name field will tell the object what module to
load and also sets the object name to "modName" for future reference. The
module object will automatically terminate itself when it reaches the closing
tag. If you would like to keep the module for ongoing function calls, set
the Static field to TRUE.
A list of officially recognised modules that export function tables can
be found in the Module Index manual.
If you would like to learn more about modules in general, refer to the
Module Interfaces
manual. If you would like to write a new module, please read the
Module Development
Guide.
Methods
The Module class implements the following methods:
Exec | Executes module functions from scripts. |
Structure
The Module object consists of the following public fields:
Actions | Used to gain direct access to a module's actions. |
ModBase | The Module's function base (jump table) must be read from this field. |
Name | The name of the module. |
Static | Set to TRUE to make the module static. |
TableType | The type of function table that you want to acquire from the Module. |
Exec() |
Executes module functions from scripts. |
STRING Function | The name of the function that you want to call. |
STRING Args | String-list of arguments to pass to the function (optional). |
|
The Exec method provides a means for the execution of module functions
in scripts, such as DML. To use it, you need to know the name of the function
that you are going to execute and provide the necessary arguments for function
execution.
Arguments must be presented as a comma separated list of values. The values
can be in integer format or as a string of characters. If necessary, strings
may be encapsulated in double or single quotes at your option. Any arguments
that you do not provide will be passed as zero values to the function.
Currently the means for interpreting results from function calls is
not provided by the Exec method.
ERR_Okay | The function was called (whether or not the function itself was successful is not indicated here). |
ERR_Args | Invalid arguments were specified. |
ERR_Search | The requested function does not exist in the module. |
ERR_BufferOverflow | The supplied arguments were too large for internal buffers. |
|
|
Field: | Actions |
Short: | Used to gain direct access to a module's actions. |
Type: | APTR * |
Status: | Get |
This field provides direct access to the actions of a module. You can use
it in the development of a class or function based module so that your code
can hook into the Pandora Engine's action system. This allows you to create
a module that blends in seamlessly with the system's object oriented
design.
The Actions field itself points to a list of action routines that are
arranged into a lookup table, sorted by action ID. You can hook into an
action simply by writing to its index in the table with a pointer to the
routine that you want to use for that action. For example:
GetField(Module, FID_Actions, FT_POINTER, &Actions);
Actions[AC_ActionNotify] = MODULE_ActionNotify;
The synopsis of the routines that you use for hooking into the action list
must match the following:
ERROR MODULE_ActionNotify(OBJECTPTR Module, APTR Args);
It is recommended that you refer to the Action Support Guide before hooking
into any action that you have not written code for before.
|
|
Field: | ModBase |
Short: | The Module's function base (jump table) must be read from this field. |
Type: | APTR |
Status: | Read |
When a module is initialised, a jump table is created and placed in
this field. Once you grab the ModBase, you can use it to call any of the
Module's functions. How you call functions from the table is dependent on
the TableType setting (more on this soon).
The jump table that is created is not shared between Tasks -
each process gets its own unique jump table when it opens a Module. This
allows each Module to use a different function model between versions,
without losing backwards compatibility. When a Module is opened it can
check the Version number argument and then pass a tailor-made function
list back to your program. So, if a function had to change in future (e.g.
add new arguments), your older program would simply be routed to a routine
that provides backwards compatibility to the newer function model. Newly
written programs would of course go straight to the expected function.
Secondly, you have the option of what kind of function base you would
like to be returned (this is where the TableType
comes in). On the Amiga, the following code standard is used to make
library calls with the Motorola 680x0 CPUs:
move.l KernelBase(pc),a6
jsr _LVOFunctionCall(a6)
However if you are programming in C, you will typically be using this
method:
KernelBase->FunctionCall();
Library calls in other CPUs and languages can be completely different.
This is quite important when producing a cross platform binary as there
could be some confusion as to what function base should be returned. So,
the Module object allows you to specify exactly what sort of function
base you want returned.
Remember that after you free your Module, the function base returned from
the ModBase field will become invalid.
|
|
Field: | Name |
Short: | The name of the module. |
Type: | STRING |
Status: | Read/Init |
This string pointer specifies the name of the Module. This name will
be used to load the module from the "system:modules/" directory,
so this field actually reflects part of the Module's 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 important that you do not use file extensions in the Name
string, e.g. "screen.mod" as not all systems may use a ".mod" extension.
|
|
Field: | Static |
Short: | Set to TRUE to make the module static. |
Type: | LONG |
Status: | Read/Init |
When used in scripts, a module object will automatically terminate itself
once it reaches the closing tag (it will be assumed that your function calls
will be taken between the opening and closing tag statements). If you would
rather that the object stays in the system, set this field to TRUE. You will
need to manually free the module once you are finished making function calls.
|
|
Field: | TableType |
Short: | The type of function table that you want to acquire from the Module. |
Type: | LONG |
Status: | Read/Init |
This field can be specified prior to initialisation so that you can get
tailor-made jump tables. Generally the default type will suffice, but
on some systems or even in some languages, a specific type of jump table may
be more appropriate. The currently available types are:
MHF_JMP_LVO | LVO jump type (Amiga standard). |
MHF_JMP_STRUCTURE | Structured function list (Linux, C/C++ standard). |
|
|