Class Documentation

Name:Module
Version:1.0
ID:ID_MODULE
Status:Stable
Category:System
Include:system/module.h
Date:January 2004
Author:Rocklyte Systems
Copyright:  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.
Method:Exec()
Short:Executes module functions from scripts.
Arguments:
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.

Result
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:

FlagDescription
JMP_LVOLVO jump type (Amiga standard).
JMP_STRUCTURE  Structured function list (Linux, C/C++ standard).