Class Documentation

Name:Module
Version:1.0
ID:ID_MODULE
Status:Stable
Category:System
Include:system/module.h
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2001. 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.

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.

Structure

The Module object consists of the following public fields:

ModBase  The Module's function base (jump table) must be read from this field.
Name  The name of the module.
TableType  The type of function table that you want to acquire from the Module.
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: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).