Kernel

Version:3.4
Status:Stable
Date:April 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1996-2004. All rights reserved.
Short:  The object kernel interface controls and maintains the system.



Description

The Pandora object kernel is a function library that provides the features expected of a traditional kernel, while also providing a fully featured object oriented programming interface. This makes it a unique hybrid that allows for better portability and services. Support for the management of memory and resources are all present, plus you will also find extensive support for class management and field and object handling.

The portability of the object kernel has been ensured by keeping the functions as generalised as possible. Depending on the intended platform, the object kernel can be developed to run independently (i.e. as a real kernel) or it can leech functionality from a dedicated kernel (as is the case with the Linux version). It is vital that when running on a host environment that the temptation to use the host's functions are avoided, or you will lose compatibility with other computer systems running the Pandora Engine.

For summarised information about how the system works, please refer to the General Documentation which covers all aspects of the design and object orientation in the system. From here on in the subject matter is very technical, so if you do not have any background knowledge of the Pandora Engine, please read the beginner manuals before continuing.

Function Index
AccessMemory  Grants access to public memory blocks.
AccessObject  Grants exclusive access to public objects.
AccessSemaphore  Grants access to semaphores.
Action  This function is responsible for executing action routines.
ActionList  Returns a pointer to the kernel's most current action table.
ActionMsg  Provides a mechanism for sending actions to objects that belong to other tasks.
ActionTags  This is a tag-based version of the Action() function.
AllocMemory  Allocates system memory blocks.
AllocSemaphore  Allocates a new public semaphore.
AllocateClassID  Generates dynamic class ID's.
AllocateID  Generates unique ID's for various purposes within the Pandora Engine.
CheckAction  Checks objects to see whether or not they support certain actions.
CheckMemoryExists  Checks if a memory block still exists.
CheckObjectExists  Checks if a particular object is still available in the system.
ClearMemory  Clears large blocks of memory very quickly.
CloneMemory  Makes an exact duplicate of a memory block.
CreateObject  Provides a fast way of creating and initialising new objects.
CurrentContext  Returns a pointer to the object that has the current context.
CurrentTaskID  Returns the object ID of the current Task.
DPrintF  Sends formatted strings to the debugger.
DebugState  Turns debug messages on and off.
DeregisterFD  Removes previously register FD's from the system.
FastFindObject  Searches for objects by name.
FindClass  Finds the relevant Class object for a particular class ID.
FindObject  Searches for objects by name and class.
FindPrivateObject  Searches for objects by name.
Forbid  Locks other tasks out of the shared memory and object areas.
FreeMemory  Frees private memory blocks allocated from AllocMemory().
FreeMemoryID  Frees public memory blocks allocated from AllocMemory().
FreeSemaphore  Frees an allocated semaphore.
GetClassID  Returns the class ID of an object.
GetField  Retrieves single field values from objects.
GetFieldVariable  Retrieves field values by converting them into strings.
GetFields  Retrieves multiple field values in a single function call.
GetMessage  Reads messages from message queues.
GetName  Retrieves object names.
GetOwnerID  Returns the unique ID of an object's owner.
GetResource  Retrieves miscellaneous resource identifiers.
ListChildren  Returns a list of all children belonging to an object.
ListMemory  Returns a list of public or private memory blocks that have been allocated in the system.
ListObjects  Returns a list of objects that match specific parameters.
ManageAction  Allows modules to intercept and manage action calls.
MemoryIDInfo  Returns information on memory ID's.
MemoryPtrInfo  Returns information on memory addresses.
NewObject  Creates new objects.
NotifySubscribers  Used to send notification messages to action subscribers.
ObtainMethod  Returns a direct pointer to an object's method code.
Permit  Releases a lock obtained from Forbid().
ProcessMessages  Processes system messages that are queued in the Task's message buffer.
RandomNumber  Generates random numbers.
ReallocMemory  Reallocates memory blocks.
RegisterFD  Registers a file descriptor for monitoring when the task is asleep.
ReleaseMemory  Releases memory blocks from access locks.
ReleaseObject  Releases objects from exclusive use.
ReleaseSemaphore  Releases a locked semaphore.
ResolveClassName  Used to resolve unique class ID's from class names.
ResolveFields  Converts field names into globally supported Field ID's.
ScanMessages  Scans a message queue for multiple occurances of a message type.
SelfDestruct  Destroys the task and frees its resources.
SendError  Sends basic error messages to the active debugger.
SendMessage  Send messages to message queues.
SetContext  Tells the system which object currently has resource control.
SetField  Used to set field values of objects.
SetFieldVariable  Sets any field using an abstract string value.
SetFields  Sets the values of multiple object fields.
SetName  Sets the name of an object.
SetOwner  Changes object ownership dynamically.
SetResource  Sets miscellaneous resource identifiers.
StepBack  Steps back the debugging tree.
StrCompare  Compares strings to see if they are identical.
SubscribeAction  Used for listening to action activity in foreign objects.
SubscribeActionTags  Used for listening to action activity in foreign objects.
SubscribeChannel  Used for listening to the data channels of foreign objects.
SubscribeField  Used for responding to field activity in foreign objects.
SubscribeTimer  Subscribes an object to the system's timer service.
SystemTime  Returns the current system time, in milliseconds.
TotalChildren  Calculates the total number of children belonging to an object.
UnsubscribeAction  Removes action subscriptions from external objects.
UnsubscribeChannel  Removes data channel subscriptions from an external object.
UnsubscribeField  Removes field-based subscriptions from an object.
UnsubscribeTimer  Unsubscribes an object from the system's timer service.
UpdateMessage  Updates the data of any message that is queued.
WaitTime  Waits for a specified amount of seconds and/or microseconds.
WatchPublicMemory  Monitors public memory blocks for foreign access.

 

Function:AccessMemory()
Short:Grants access to public memory blocks.
Synopsis:ERROR AccessMemory(MEMORYID MemoryID, LONG Flags, APTR *Address)
Arguments:
MemoryID  The ID of the memory block that you want to access.
Flags  Set to MEM_READ, MEM_WRITE or MEM_READWRITE according to your requirements.
Address  Must point to an APTR variable that will store the resolved address.

In order to gain access to a block of public memory, the AccessMemory() function must be called to page the block into your task's memory space. If the MemoryID is valid and the block is available, a valid address pointer. will be returned that you may use for direct read/write operations. For your convenience, this function may also be used to resolve the memory addresses of private memory block IDs.

Public memory blocks should never be locked for long periods of time. You must match all locks that you make with calls to ReleaseMemory() inside a reasonable time frame. Always keep in mind that other tasks may be waiting to gain access to memory blocks that you lock.

Please note that the address that is returned is specific to your task only and cannot be passed to any other task in the system.

Result
ERR_Okay  The function executed successfully.
ERR_Args  Invalid arguments were passed to the function.
ERR_LockFailed  An internal lock failure has occurred.
ERR_DeadLock  Access cannot be granted because another task has locked the block and is currently sleeping on a response from your task.
ERR_TimeOut  While waiting for the memory block to become accessible, sufficient time elapsed for a time-out to occur.
ERR_SystemCorrupt  The task has lost its process ID.
ERR_MemoryDoesNotExist  The MemoryID that you supplied does not refer to an existing memory block.
ERR_MarkedForDeletion  The memory block cannot be accessed because it has been marked for deletion.
ERR_SystemLockedUp  Access to the global memory pool was denied.

Function:AccessObject()
Short:Grants exclusive access to public objects.
Synopsis:ERROR AccessObject(LONG ObjectID, LONG Milliseconds, OBJECTPTR *Result)
Arguments:
ObjectID   The unique ID of the object that you want exclusive access to. If you only know the name of the object, use FindObject() to acquire the correct object ID.
Milliseconds   The amount of milliseconds you are prepared to wait before your attempt will timeout. The maximum wait is 60 seconds (60,000 milliseconds). Use a value of 0 if you do not want to wait.
Result   Must refer to an OBJECTPTR variable that will store the resulting object address.

This function is provided so that tasks can gain temporary exclusive access to public objects. It is specially designed to prevent more than one task from having access to a specific object at any given moment. The AccessObject() function also works on private objects for reasons of consistency.

Once you call this function, it will immediately attempt to page the object's address space into your task. If it cannot do this, the function will wait until the object becomes available. This must occur within the amount of time specified by the Milliseconds argument. If the time runs out, the function will return with an ERR_TimeOut error code. If successful, ERR_Okay will be returned and you will have exclusive access to the object through the address pointed to in the Result variable. Once you are done with the object, call ReleaseObject() so that other tasks can access it.

If this function fails, the Result variable will be automatically set to a NULL pointer on return.

Result
ERR_Okay  Exclusive access has been granted.
ERR_Args  Invalid arguments were specified.
ERR_MarkedForDeletion  The object that you want to access is marked for deletion.
ERR_MissingClass  The class that is associated with the object is mysteriously unavailable.
ERR_NoMatchingObject  The supplied ObjectID does not match any known object in the system.

Function:AccessSemaphore()
Short:Grants access to semaphores.
Synopsis:ERROR AccessSemaphore(LONG SemaphoreID, LONG TimeOut, LONG Flags)
Arguments:
SemaphoreID  The ID of an allocated semaphore.
TimeOut  The total number of microseconds to wait before timing out.
Flags  Optional flags.

The AccessSemaphore() function will give your task access to a semaphore once it becomes available. If the semaphore is available immediately then the function will return instantly. If other processes have blocked the semaphore through their usage, your task will be put to sleep for up to the time specified in the Timeout parameter. If you do not specify a Timeout, then the function will return immediately with an ERR_Timeout error.

Each time you call AccessSemaphore(), the system will try to 'block' the semaphore by default, which means you get exclusive access to the resource represented by the semaphore. If you only need non-blocking access to the semaphore, you must use the SMF_NONBLOCKING flag. In this mode, the system will decrement the semaphore counter by 1 and return. If the semaphore counter reaches a value of zero then the function will wait until one of the accessing processes releases its hold on the semaphore.

You must match each call to AccessSemaphore() with a call to the ReleaseSemaphore() function.

Result
ERR_Okay  Access has been granted to the semaphore.
ERR_Args  A valid SemaphoreID was not specified.
ERR_Timeout  Your task was put to sleep and the timeout was met before the semaphore became available.
ERR_SystemCorrupt  The internal semaphore management array is corrupt.
ERR_Forbid  A call to the Forbid() function failed.
ERR_ArrayFull  There are too processes waiting on this semaphore for you to be put on the queue.
ERR_DeadLock  Your process cannot be put to sleep because it would cause a system deadlock.

Function:Action()
Short:This function is responsible for executing action routines.
Synopsis:ERROR Action(ACTIONID ActionID, OBJECTPTR Object, APTR Parameters)
Arguments:
ActionID  An action or method ID must be specified here (e.g. AC_Query). Action ID's are obtained from the "system/actioncodes.h" include file.
Object  A pointer to the object that is going to perform the action.
Parameters  If the action or method is documented as taking parameters, point to the relevant parameter structure here. Pre-defined parameter structures are obtained from the "system/actions.h" include file.

This function is the key entry point for executing actions and method routines. An action is a predefined function call that can be called on any object, while a method is a function call that is specific to a particular object type. You can find a complete list of available actions and their associated details in the Action List document. If an object supports methods, they will be listed in the object's class document.

Here are two examples that demonstrate how to make an action call. The first performs an initialisation, which does not require any additional arguments. The second performs a move operation, which requires three additional arguments to be passed to the Action() function:

   1. Action(AC_Init, Picture, NULL);

   3. struct acMove move;
      move.XChange = 30;
      move.YChange = 15;
      move.ZChange = 0;
      Action(AC_Move, Window, &move);

If the target object does not support the action code that you have specified, an error code of ERR_NoSupport will be returned. If you need to test an object to see if it supports a particular action, use the CheckAction() function.

If you need to send an action to an object that does not belong to your task space, use the ActionMsg() function. If you're in a situation where you only have an object ID and are unsure as to whether or not the object is in your task space, use ActionMsg() anyway as it will divert to the Action() function if the object is local.

If you are writing a class and need to know how to add support for a particular action, look it up in the Action Support Guide.

Result
ERR_Okay  The function executed successfully.
ERR_Args  Incorrect arguments passed to function (missing ActionID or Object).
ERR_NoAction  The action is not supported by the object's supporting class.
ERR_ObjectCorrupt  The object that was received is badly corrupted in a critical area.

Function:ActionList()
Short:Returns a pointer to the kernel's most current action table.
Synopsis:struct ActionTable * ActionList(void)

If you need a dynamic list of all the actions supported by the object kernel, including information on ID's, names, arguments and structure sizes, use the ActionList() function. This function will return an array that is arranged into a look-up table, sorted by action ID. The ActionTable structure is defined as follows:

   struct ActionTable {
      STRING Name;
      struct FunctionField *Args;
      LONG Size;
   };

The Name field specifies the name of the action. The Args field refers to the action's argument definition structure, which lists the argument names and their relevant types. This is matched by the Size field, which indicates the byte-size of the action's related argument structure. If the action does not support arguments, the Args and Size fields will be set to NULL. Here are two argument definition examples:

   struct FunctionField argsCopyData[] = {
      { "Destination", ARG_LONG  },
      { NULL, NULL }
   };

   struct FunctionField argsResize[] = {
      { "Width",  ARG_DOUBLE },
      { "Height", ARG_DOUBLE },
      { "Depth",  ARG_DOUBLE },
      { NULL, NULL }
   };

The argument types that can be set by actions are limited to those listed in the following table:

TypeDescription
ARG_LONGA 32-bit integer value ranging from -2,147,483,647 to 2,147,483,648.
ARG_LARGEA 64-bit integer value.
ARG_PTRA standard 32-bit address space pointer.
ARG_STRINGA 32-bit address space pointer that refers to a null-terminated string.
ARG_DOUBLEA 64-bit floating point value.
ARG_OBJECTThis flag is sometimes set in conjunction with the ARG_LONG type. It indicates that the argument refers to an object ID.
ARG_PTRSIZEThis argument type can only be used if it follows an ARG_PTR type, and if the argument itself is intended to reflect the size of the buffer referred to by the previous ARG_PTR argument.
ARG_RESULTThis special flag is set in conjunction with the other data-based argument types. Example: If the developer is required to supply a pointer to a LONG field in which the function will store a result, the correct argument definition will be ARG_RESULT|ARG_LONG|ARG_PTR. To make the definition of these argument types easier, ARG_PTRRESULT, ARG_LONGRESULT and ARG_FLOATRESULT macros are also available for use.

 

Result
This function returns a pointer to the object kernel's action table (struct ActionTable *). If a failure occurs, NULL will be returned.

Please note that the first entry in the ActionTable list has all fields driven to NULL, because valid action ID's start from one, not zero. The final action in the list is also terminated with NULL fields in order to indicate an end to the list. Knowing this can be helpful if you wish to search the list or calculate the total number of actions supported by the kernel.


Function:ActionMsg()
Short:Provides a mechanism for sending actions to objects that belong to other tasks.
Synopsis:ERROR ActionMsg(LONG ActionID, OBJECTID Object, APTR Args)
Arguments:
ActionID  The ID of the action that you want to execute.
ObjectID  The ID of the object to receive the action.
Args  The argument structure related to the specific action that you are calling.

ActionMsg() provides the necessary functionality to execute an action on any shared object that does not reside within your task space. The function works first by testing the object to see if it it belongs to your task space, or someone else's task space. If the object is yours then the action will be called immediately, as if Action() was called under normal circumstances. Otherwise, the action call will be sent to the object's owner as a message and the function will immediately return to your program.

Once an action has been sent, you need to work on the assumption that its owner will respond to the message and execute the action. If the Task does not respond, then likely causes may include a task crash, buggy programming or an extended busy period.

There is one exception to the rule: In cases where an action or method returns a result (e.g. the Read and Write actions do this), the ActionMsg() function will actually ask the other Task to send back the result information. This causes the function to sleep for a short period of time until it receives the result information from the other Task. By doing this, the normal behaviour that would be expected of an action that returns results is preserved.

Result
ERR_Okay  The message was successfully passed to the object (this is not indicative of whether or not the object was actually successful in executing the action).
ERR_Args  A NULL value was detected in the ActionID or ObjectID arguments.
ERR_NoMatchingObject  There is no object for the given ObjectID.

Function:ActionTags()
Short:This is a tag-based version of the Action() function.
Synopsis:ERROR ActionTags(ACTIONID ActionID, OBJECTPTR Object, Tags...)
Arguments:
ActionID  The ID of the action or method that you want to execute.
Object  The object that is to receive the action.
Tags  Each argument that would normally be specified in the action structure must be listed as tags, in the same order as the fields in the original action structure. There is no need to terminate the tag-list.

This function is identical to the Action() function in every respect, except that it allows you to send action arguments as tags rather than in a structure. Here are a few examples:

   ActionTags(AC_Resize, Object, 100, 300, 200);
   ActionTags(MT_Rename, Object, "athene:documents.txt");

Whether you choose to use ActionTags() or Action() to make your action calls is a matter of personal preference. However, be aware that ActionTags() does not support actions or methods that return results in the argument structure - e.g. Read and Write actions are not supported.

Result
ERR_Okay  The action was executed successfully.
ERR_Args  Invalid arguments were supplied to the function.
ERR_IllegalMethodID  The ActionID is not a supported method of the target object.

Function:AllocMemory()
Short:Allocates system memory blocks.
Synopsis:ERROR AllocMemory(LONG Size, LONG Flags, APTR *Address, MEMORYID *MemoryID)
Arguments:
Size  The size of the memory block.
Flags  Flag specifications - set to NULL to allocate a standard data memory block.
Address  Set this argument to refer to an APTR type to store an address reference to the allocated memory block.
MemoryID  Set this argument to refer to a MEMORYID type to store a unique ID reference to the allocated memory block. This is compulsory when allocating public memory blocks.

The AllocMemory() function is used to allocate blocks of memory from the system memory pool. To allocate a new block you need to specify its Size, allocation Flags and Address and/or MemoryID arguments to store references to the allocation. Here is an example:

   APTR Address;

   if (AllocMemory(1000, MEM_DATA, &Address, NULL) IS ERR_Okay) {
      ...
      FreeMemory(Address);
   }

A number of flag definitions are available that affect the memory allocation process. They are:

FlagDescription
MEM_DATAThe default type, MEM_DATA, is used to indicate a standard memory allocation from system RAM.
MEM_PUBLICPublic memory can be allocated by specifying this flag. Public memory blocks are accessible by all tasks, but access can only be gained by knowing the unique memory ID and utilising the AccessMemory() function.
MEM_CODEIf the memory will contain executable program code, set this flag.
MEM_UNTRACKED  Allocating an untracked memory block will prevent the memory block from being tracked back to the object holding the current context.
MEM_STRINGThis flag is used to aid debugging - set it if the memory block will be used to store printable string data.
MEM_NOBLOCKING  If this flag is set against a public memory block then the access blocking mechanism will be permanently turned off for all accesses to that particular memory block. This means that multiple tasks can have full read/write access to the memory block at once regardless of the flags passed to AccessMemory().
MEM_NOCLEARIf this flag is set, the memory block's data will not be cleared by the AllocMemory() function.
MEM_FIXEDThis flag can be applied to public memory blocks that need to be mapped to a fixed address that is common to all tasks. For instance, if the system locks the memory block to address 0x56084000 for your task, then all other tasks that map the memory block will also see it at that address. This flag is typically used for supporting absolute code execution.
MEM_CALLERThis flag is useable only in routines that support a class method. It forces the memory allocation to be resourced against the object that made the method call. This is particularly important in methods that return memory blocks that do not form a part of the object itself.
MEM_TASKTells the allocation function to track the memory block to the current Task, as opposed to the current object.
MEM_RESERVEDThis special flag is used to allocate shared memory blocks that require reserved ID numbers. When using the MEM_RESERVED flag, you are required to set the longword pointed to by the MemoryID argument to the ID that you wish to reserve. If that memory ID is already taken, the AllocMemory() call will fail.

You will notice that you have the option of receiving the memory allocation as an address pointer and/or as a unique memory ID. When allocating private memory, you can generally just accept an address result and drive the MemoryID argument to NULL. However when allocating public memory, you should always retrieve the MemoryID, and optionally the Address pointer if you need immediate access to the block.

If the block is allocated as private and you retrieve both the MemoryID and Address pointer, or if the allocation is public and you choose to retrieve the Address pointer, an internal call will be made to AccessMemory() to lock the memory block and resolve its address. This means that before freeing the memory block, you must make a call to the ReleaseMemory() function to remove the lock, or it will remain in memory till your Task is terminated.

Memory that is allocated through AllocMemory() is automatically cleared with zero-byte values. When allocating large blocks it may be wise to turn off this feature - you can do this by setting the MEM_NOCLEAR flag.

Result
ERR_Okay  The memory block was allocated successfully.
ERR_Args  Incorrect arguments were specified (no Size, or no Address and no MemoryID).
ERR_Failed  The block could not be allocated due to insufficient memory space.
ERR_ArrayFull  Although memory space for the block was available, all available memory records are in use.
ERR_LockFailed  The function failed to gain access to the public memory control semaphore.
ERR_SystemCorrupt  The internal tables that manage memory allocations are corrupt.
ERR_AccessMemory  The block was allocated but access to it was not granted, causing failure.
ERR_ResourceExists  This error is returned if MEM_RESERVED was used and the memory block ID was found to already exist.

Function:AllocSemaphore()
Short:Allocates a new public semaphore.
Synopsis:ERROR AllocSemaphore(STRING Name, LONG Value, LONG Flags, LONG *Semaphore)
Arguments:
Name  The name of the semaphore (up to 12 characters, case-sensitive) that you want to create or find. This argument is optional.
Value  The starting value of the semaphore can be specified here. The minimum starting value is 1, for a simple blocking semaphore.
Flags  Special flags, currently SMF_EXISTS is supported.
Semaphore  A reference to the semaphore will be returned through this pointer.

The AllocSemaphore() function is used to create new semaphores and join existing ones. To create a simple semaphore for private usage, you only need to provide this function with a return value in the Semaphore parameter. If you want to share a semaphore with other processes, you need to give it a unique name limited to 15 characters. The Value argument is optional and only needs to be used if you need more complex signalling for your program.

Semaphores are most commonly used to control access to shared resources, typically in shared memory areas. For instance, if you create a shared memory area for read/write operations between tasks, you need a control system to prevent the tasks from writing to the memory at the same time (allowing multiple read access is usually non-harmful and quite convenient). Using a semaphore is perfect for controlling this type of situation.

For a simple blocking semaphore, you should set a value of 1 in the Value parameter. If you want to allow multiple processes to read from the resource then you should set the Value much higher - 100 or more. In this mode, there are two ways for processes to access the semaphore - blocking and non-blocking mode. Either type of access is achieved through the AccessSemaphore() function. Blocking mode is the default and will grant you full access to the resource if it succeeds. Non-blocking access grants you limited access to the resource - typically considered 'read only' access. Multiple processes can have non-blocking access at the same time, but only one process may have access when blocking mode is required. If you set a value of 100, then the number of non-blocking accesses will be limited to 100 processes. Any more processes than this wishing to use the semaphore will need to wait until some of the accesses are released. If 50 processes currently have read access and a new process requires blocking access, it will have to wait until all 50 read accesses are released. The specifics of this are discussed in the documentation for AccessSemaphore() and ReleaseSemaphore().

The handle returned in the Semaphore argument is global, so if you want to secretly share an anonymous semaphore with other processes, you may do so if you pass the handle to them. The other processes will still need to call AllocSemaphore() to register their interest, but they need to add the SMF_EXISTS Flag and also pass the semaphore handle to this function via the Semaphore parameter.

To free a semaphore after you have allocated it, call the FreeSemaphore() function. It is possible to call AllocSemaphore() with the same Name as many times as you like because the calls will nest, but you must match them all with FreeSemaphore() calls. A semaphore will not be completely freed from the system until all processes that have gained access drop their control of the semaphore.

Result
ERR_Okay  The semaphore was successfully allocated.
ERR_Args  The SemaphoreID argument was not supplied.
ERR_ArrayFull  Allocation failed as the semaphore array is at full capacity.
ERR_Forbid  Internal system locking failure.

Function:AllocateClassID()
Short:Generates dynamic class ID's.
Synopsis:ERROR AllocateClassID(STRING Name, CLASSID *ClassID)
Arguments:
Name  The name of the class that requires an ID.
ClassID  Must refer to a CLASSID variable that will store the resulting ID.

This function generates unique ID's that can be used for unregistered classes. ID's that are allocated through this function are permanent for the duration that the system is active. There is no need to free allocated class ID's when you are finished with them.

Result
ERR_Okay  A unique ID was successfully allocated and placed in the ClassID variable.

Function:AllocateID()
Short:Generates unique ID's for various purposes within the Pandora Engine.
Synopsis:LONG AllocateID(LONG Type)
Arguments:
Type  The type of ID that you are requesting.

This function generates unique ID's that can be used in certain areas of the object kernel. Simply tell this function the type of unique ID that you want to retrieve, and it will pass a unique ID back to you. The following ID types are currently supported:

TypeDescription
IDTYPE_MESSAGE  Message ID's are allocated for the purpose of sending uniquely identifiable messages between tasks.
IDTYPE_GLOBAL  Global ID's have no particular association with anything.

ID allocations are permanent, so there is no need to free an allocated ID when you are finished with it.

Result
A unique ID matching the requested type will be returned. This function can return NULL if the Type you supplied is unrecognised, or if an internal error occurred.


Function:CheckAction()
Short:Checks objects to see whether or not they support certain actions.
Synopsis:ERROR CheckAction(OBJECTPTR Object, ACTIONID ActionID)
Arguments:
Object  Pointer to the object that you want to check.
ActionID  One of the action ID's as specified in the "system/actioncodes.h" include file.

This function checks if a particular object supports a given action or method ID. To check if a Picture object supports the Query action for instance, a code segment such as this would be sufficient:

   if (CheckAction(Picture, AC_Query) IS ERR_Okay) {
      ...
   }
Result
ERR_Okay  The object supports the specified action.
ERR_False  The action is not supported.
ERR_Args  Incorrect arguments detected.
ERR_LostClass  The object has lost its class reference (object corrupt).

Function:CheckMemoryExists()
Short:Checks if a memory block still exists.
Synopsis:ERROR CheckMemoryExists(MEMORYID MemoryID)
Arguments:
MemoryID  The ID of the memory block that you wish to look for.

If you need to know whether or not a specific memory block still exists, you can check by using the CheckMemoryExists() function. Simply provide it with the ID of the block that you are interested in and it will return an error code of ERR_Okay if it is in the system at the time of calling.

Result
ERR_Okay  The block exists.
ERR_False  The block does not exist.
ERR_Args  You supplied a MemoryID of NULL.
ERR_SystemCorrupt  The internal memory tables are corrupt.

Function:CheckObjectExists()
Short:Checks if a particular object is still available in the system.
Synopsis:ERROR CheckObjectExists(OBJECTID ObjectID, STRING Name)
Arguments:
ObjectID  The object ID that you want to look for.
Name  If the ID is not known, specify the Name of the object here. Otherwise set to NULL.

The CheckObjectExists() function checks for the existence of an object within the system. CheckObjectExists() is commonly used to check for the presence of shared objects, which can be removed from the system at any time by other tasks.

This function allows you to check for an object either by ID or name. Please note that in the case of name checking, it is possible for multiple objects with the same name to exist at the time of calling this function.

Result
ERR_Okay  The object exists.
ERR_False  The object ID does not exist.
ERR_Args  Neither of the ObjectID or Name arguments were specified.

Function:ClearMemory()
Short:Clears large blocks of memory very quickly.
Synopsis:ERROR ClearMemory(APTR Memory, LONG Length)
Arguments:
Memory  Pointer to the memory block that you want to clear.
Length  The total number of bytes that you want to clear.

Use the ClearMemory() function when you need to clear a block of memory as efficiently as possible.

Result
ERR_Okay  The memory was cleared.
ERR_Args  The Memory argument was not specified.

Function:CloneMemory()
Short:Makes an exact duplicate of a memory block.
Synopsis:ERROR CloneMemory(APTR Address, LONG Flags, APTR *NewAddress, MEMORYID *NewMemoryID)
Arguments:
Address  Pointer to the memory block that you want to clone.
Flags  Specifies the memory flags that you want to use for your newly cloned memory block. See AllocMemory() for flag definitions.
NewAddress  Set this argument to refer to an APTR type, to store an address reference to the cloned memory block.
NewMemoryID  Set this argument to refer to a MEMORYID type, to store a unique ID reference to the cloned memory block.

This function allows you to make a duplicate of any memory block that has been allocated from AllocMemory(). The new memory block will be completely identical to the block you have specified, except for the type of memory, which you can alter through the Flags argument. The contents of the original memory block will be copied over to the duplicate block.

You will notice that you have the option of receiving the cloned memory as an address pointer and/or as a unique memory ID. When allocating private memory, you can generally just accept an address result and drive the MemoryID argument to NULL. However when cloning public memory, you should always retrieve the MemoryID, and optionally the Address pointer if you need immediate access to the cloned block.

If the block is cloned as private memory and you retrieve both the MemoryID and Address pointer, or if the allocation is public and you choose to retrieve the Address pointer, an internal call will be made to AccessMemory() to lock the memory block. This means that before freeing the memory block, you must make a call to the ReleaseMemory() function to remove the lock, or it will remain in memory.

Remember to free the cloned memory block when you are finished with it.

Result
ERR_Okay  A duplicate of the memory block was successfully created.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Access to the newly created memory block was denied to the function.
ERR_AllocMemory  Failed to allocate the duplicate memory block.

Function:CreateObject()
Short:Provides a fast way of creating and initialising new objects.
Synopsis:ERROR CreateObject(LONG ClassID, LONG Flags, OBJECTPTR *Object, OBJECTID *ObjectID, Tags...)
Arguments:
ClassID  Set to a class ID obtained from the "system/register.h" file or from ResolveClassName().
Flags  Flag specifications - set to NULL to allocate a standard private object.
Object  Set this argument to refer to an OBJECTPTR type to store an address reference to the new object.
ObjectID  Set this argument to refer to an OBJECTID type to store a unique ID reference to the new object.
Tags  Field tags are specified here. See the SetFields() function for information on the arrangement of these tags. Remember to terminate the tag-list with TAGEND.

CreateObject() is an enhanced version of the NewObject() function. It performs the same activity as NewObject(), but will also set field values and initialise the object automatically for you. In other words, this function is provided for your convenience, and is not an integral part of the system's object management services.

Please refer to the NewObject() function for information on the allocation of new objects. Also see the SetFields() function for an outline of the formatting details of the tag arguments.

Result
ERR_Okay  The object was created successfully.
ERR_Args  Invalid arguments were specified.
ERR_NewObject  The NewObject() function failed.
ERR_Init  The Init action failed.
ERR_SetField  The SetFields() function failed.

Function:CurrentContext()
Short:Returns a pointer to the object that has the current context.
Synopsis:OBJECTPTR CurrentContext(void)

The CurrentContext() function returns a pointer to the object that has the current context. In order for an object to have the context of the current Task, it must have been successfully set from the SetContext() function.

CurrentContext() is typically used to find out what object is currently receiving resource allocations. It is useful in improving the management of resources that your code may be allocating.

Result
Returns an object pointer (of which the Task has exclusive access to). This function rarely returns a NULL pointer - this is only possible during the initial startup and shutdown sequences of the object kernel.


Function:CurrentTaskID()
Short:Returns the object ID of the current Task.
Synopsis:OBJECTID CurrentTask(void)

The CurrentTaskID() function returns the object ID of the Task that is making the call - i.e. "you". Task objects' are used for storing data that is specific to a running program. Refer to the Task class for details.

There are some cases where CurrentTaskID() can return a NULL value. This can occur if there is no related Task object, or if the Task object has been corrupted. For this reason it is recommended that calls to CurrentTask() are enclosed within an IF statement.

If there is a legitimate circumstance where there is no current task (for example if this function is called during kernel initialisation) then the "system task" may be returned (the system task controls and maintains the kernel).

It is also possible to retrieve a direct pointer to the task's object structure by calling the CurrentTask() function. This saves on the time required to access and release the task object when using ID's.

Result
Returns a unique ID reference to the current Task object or NULL if failure. You will need to use the AccessObject() function if you need to gain direct access to the Task object.


Function:DPrintF()
Short:Sends formatted strings to the debugger.
Synopsis:void DPrintF(STRING Header, STRING Array, ...)
Arguments:
Header  A short name for the first column. Usually function names are placed here, so that it is obvious who is sending the message.
Array  The first member of the array must be a string. All other members of the array must be supplied according to the string formatting, 1 parameter for every % symbol that you have used.

The DPrintF() function follows the same functionality and rules as the ANSI printf() function. The only difference is that it prints directly to the debug window. Due to internal limits your string is limited to a total of 256 bytes output, although you should keep everything within 80 bytes to avoid running onto a second row. You can supply a maximum amount of 5 '%' parameters to this function.

The following example will print the default width of a Screen object to the debug window.

   if (NewObject(ID_SCREEN, NULL, &Screen, NULL) IS ERR_Okay) {
      if (Action(AC_Init, Screen, NULL)) {
         DPrintF("Demo:","The width of the screen is: %d", Screen->Width);
      }
      Action(AC_Free, Screen, NULL);
   }

Function:DebugState()
Short:Turns debug messages on and off.
Synopsis:LONG DebugState(LONG State, LONG Level)
Arguments:
State  Set to TRUE to turn messages on, FALSE to turn messages off. Any other value will be ignored.
Level  Indicates the level of detail that you want from debug output. The higher the number, the more messages that will be printed. Valid settings range from 0 to 10.

This function provides a switch for turning debug messages on and off. This is useful for turning off messages just before running intense looping sequences. It is also used to dynamically alter the amount of detail printed to the debugger, using the Level argument.

Calls to this function will nest according to the State argument, so if the function is called twice with State set to FALSE, then it must be called twice again with State set to TRUE to reenable debugging.

Result
Returns the debug level that was set prior to calling this function.


Function:DeregisterFD()
Short:Removes previously register FD's from the system.
Synopsis:void DeregisterFD(LONG FD)
Arguments:
FD  The file descriptor that you want to deregister.

The DeregisterFD() function is used to de-register file descriptors that you have registered via the RegisterFD() function. Once removed, the task will no longer monitor the FD for activity.


Function:FastFindObject()
Short:Searches for objects by name.
Synopsis:ERROR FastFindObject(STRING Name, CLASSID ClassID, OBJECTID *Array, LONG ArraySize, LONG *Count)
Arguments:
Name  The name of the object that you are looking for.
ClassID  Setting this field to a class ID will filter the results down to a specific class type.
Array  Pointer to the array that will store the results.
ArraySize  Indicates the size of the array that you have supplied. Must be set to a value of 1 or greater.
Count  Set this pointer to a longword so that FastFindObject() can tell you how many objects were stored in your array. This argument can be set to NULL if you wish.

The FastFindObject() function is an optimised implementation of the FindObject() function. You can use it to search for objects in the system by their name and/or class. Unlike FindObject(), which will return an allocated memory block that lists all of the objects that were found, FastFindObject() requires that you provide a memory area to write the results to. This saves the cost of allocation time, which can be expensive in some situations.

The following code example is a typical illustration of this function's use. It finds the most recent object created with a given name:

   OBJECTID SystemPointerID;
   FastFindObject("SystemPointer", ID_POINTER, &SystemPointerID, 1, NULL);

If FastFindObject() cannot find any objects with the name that you are looking for, it will return an error code.

The list is sorted so that the oldest private object is placed at the start of the list, and the most recent public object is placed at the end. This will assist you in situations where you may be looking for the oldest or youngest object to have the particular name that you have searched for. Preference is also given to objects that have been created by your own task, so foreign objects are also pushed towards to the top of the list.

Result
ERR_Okay  At least one object was found and stored in the supplied array.
ERR_Args  The Name/ClassID, Array or ArraySize arguments were not supplied.
ERR_Search  No objects matching the given name could be found.
ERR_AccessMemory  Access to the RPM_SharedObjects memory block was denied.

Function:FindClass()
Short:Finds the relevant Class object for a particular class ID.
Synopsis:OBJECTPTR FindClass(CLASSID ClassID, OBJECTPTR LastClass)
Arguments:
ClassID  A class ID as specified in "system/register.h" or obtained from ResolveClassName(). If NULL, all classes currently loaded by the Pandora Engine will be returned in no particular order.
LastClass  Points to the last received Class structure if continuing a search, otherwise NULL to start a new search.

This function is used to search the system for all members of a specific class. If you wanted to search for all members of the Picture class for example, the following code could be used:

   OBJECTPTR Class;

   Class = NULL;
   while (Class = FindClass(ID_PICTURE, Class)) {
      ...
   }

If a matching class is found in the system, it will be returned immediately. The base class is always returned first, while subsequent calls to this function will return sub-classes. Once all of the matching classes have been discovered, a NULL pointer will be returned to indicate an end to the search.

Please note that if you are looking for a specific sub-class, you should call ResolveClassName() and then call this function with the resulting sub-class ID.

Result
Returns a pointer to the Class structure that has been found as a result of the search, or NULL if no matching classes were found.


Function:FindObject()
Short:Searches for objects by name and class.
Synopsis:ERROR FindObject(STRING Name, CLASSID ClassID, OBJECTID **List, LONG *Count)
Arguments:
Name  The name of the object that you are looking for.
ClassID  Setting this field to a class ID will filter the results down to a specific class type.
List  On success, a memory block containing a list of ObjectID's will be placed in this variable.
Count  The total number of objects listed in the List array will be stored in this variable.

The FindObject() function is used to search for objects in the system by name and class type. If the function cannot find any object with the name or class that you are looking for, then it will return an error code. If it does find one or more matching objects, then a complete list of them will be returned in an allocated memory block.

The List is sorted so that the oldest object is placed at the start of the list, and the most recent is placed at the end. This will assist you in situations where you may be looking for the oldest or youngest object that has the particular name that you have searched for.

The List is returned as an allocated memory block. Please call FreeMemory() on the List pointer so that it is not left in memory after you have used it.

Result
ERR_Okay  One or more objects have been found and are listed.
ERR_Search  There are no objects in the system with the given name or class type.
ERR_Args  Invalid arguments were specified.
ERR_Memory  The function failed to allocate enough memory for the List array.
ERR_AccessDenied  The function failed to gain access to the PublicObjects structure (internal error).

Function:FindPrivateObject()
Short:Searches for objects by name.
Synopsis:ERROR FindPrivateObject(STRING Name, OBJECTPTR *Object)
Arguments:
Name  The name of the object that you are looking for.
Object  Pointer to an OBJECTPTR variable that will store the discovered object address.

The FindPrivateObject() function is provided as a simple implementation of the FastFindObject() function. This implementation is specifically limited to finding private objects by name only. It is capable of returning only one object address in its search results. Unlike FastFindObject(), this function returns directly accessible object addresses that may be used immediately after a successful search.

If multiple objects with the same name exists, the most recently created object will be returned by this function.

If you require more advanced functionality for object searches, please use the FastFindObject() function.

Result
ERR_Okay  A matching object was found.
ERR_Args  The Name and/or Object argument was not specified.
ERR_Search  No objects matching the given name could be found.

Function:Forbid()
Short:Locks other tasks out of the shared memory and object areas.
Synopsis:ERROR Forbid(void)

Use the Forbid() function to aggressively lock out the kernel's shared memory and shared object services. This allows you to use the shared areas of the object kernel without encountering race conditions caused by other tasks trying to access the same areas. Calls to Forbid() must be followed with a call to Permit() to undo the lock.

Due to the powerful nature of this function, you should only ever use it in small code segments and never in areas that involve communication with other tasks. Locking for extended periods of time (over 4 seconds) may also result in your task being automatically killed off by the system.

Multiple calls to Forbid() will nest.

Result
ERR_Okay  Success.
ERR_LockFailed  Failed to acquire a lock on the system.

Function:FreeMemory()
Short:Frees private memory blocks allocated from AllocMemory().
Synopsis:ERROR FreeMemory(APTR Address)
Arguments:
Address  Points to the start of a memory block to be freed.

This function frees memory areas allocated from AllocMemory(). Crash protection is incorporated into various areas of this function. If the memory header or tail is missing from the block, then it is assumed that a routine has has over-written the memory boundaries, or you are attempting to free a non-existant allocation. Such problems are immediately reported to the system debugger. Bear in mind that it does pay to save your development work if such a message appears, as it indicates that important memory areas could have been destroyed.

For speed reasons, this function only supports private memory. If you wish to free a public memory block, you will need to use the FreeMemoryID() function instead.

Result
ERR_Okay  The memory block was freed successfully.
ERR_Args  You passed an Address argument of NULL.
ERR_Memory  The memory address that you supplied is not a recognised memory block.

Function:FreeMemoryID()
Short:Frees public memory blocks allocated from AllocMemory().
Synopsis:ERROR FreeMemoryID(MEMORYID MemoryID)
Arguments:
MemoryID  The unique ID of the memory block.

When a public memory block is no longer required, it can be freed from the system with this function. The action of freeing the block will not necessarily take place immediately - if another Task is using the block for example, deletion cannot occur for safety reasons. In a case such as this, the block will be marked for deletion and will be freed once all Tasks have stopped using it.

Result
ERR_Okay  The memory block was freed or marked for deletion.
ERR_Args  A NULL value was passed for the MemoryID.
ERR_MemoryDoesNotExist  The MemoryID that you supplied was not found in the system.
ERR_LockFailed  Failed to lock the public memory control semaphore.

Function:FreeSemaphore()
Short:Frees an allocated semaphore.
Synopsis:ERROR FreeSemaphore(LONG Semaphore)
Arguments:
Semaphore  The handle of the semaphore that you want to deallocate.

The FreeSemaphore() function is used to deallocate semaphores when you are no longer in need of them. You must call FreeSemaphore() for each time that you have called the AllocSemaphore() function. If you still have locks on the semaphore at the time that you call this function, the semaphore will not be removed from the system until those locks are released.

A semaphore is never completely removed from the system until all processes have given up their allocations against the semaphore.

Result
ERR_Okay  The semaphore was freed successfully.
ERR_Args  A semaphore handle was not specified.
ERR_Search  The supplied semaphore handle was not found in the internal semaphore list.

Function:GetClassID()
Short:Returns the class ID of an object.
Synopsis:CLASSID GetClassID(OBJECTID ObjectID)
Arguments:
ObjectID  The object ID that you want to know the class of.

This function can be used on any valid object ID to retrieve the ID of its class. This is the quickest way to retrieve the class of an object without having to gain exclusive access to the object first.

Please note that if you already have access to an object through an address pointer, the quickest way to learn of its class is to read the ClassID field in the object header.

Result
Returns the class ID of the object or NULL if failure.


Function:GetField()
Short:Retrieves single field values from objects.
Synopsis:ERROR GetField(OBJECTPTR Object, LONG FieldID, LONG ResultType, APTR Result)
Arguments:
Object  Pointer to an object.
FieldID  The ID of the field that you wish to read.
ResultType  The type of value that the field should be converted to.
Result  Pointer to the variable that will store the result.

The GetField() function is used to read field values from objects. You don't need to know anything about the object structure in order to read information from it - you just need to know what field you want to read.

The following code segment illustrates how to read values from an object:

   LONG XCoord, YCoord;

   GetField(Object, FID_XCoord, FT_LONG, &XCoord);
   GetField(Object, FID_YCoord, FT_LONG, &YCoord);

As GetField() is based on field ID's that reflect field names ("FID's"), you will find that there are occasions where there is no reserved ID for the field that you wish to read. To convert field names into their relevant IDs, call the ResolveFields() function. Reserved field ID's are listed in the "system/fields.h" include file.

When reading a field you are required to make an educated guess as to its type, in order to prevent a type mismatch from occurring. For instance, reading a coordinate field would mean that the field is a number, so you should read the field as a numeric type rather than choosing a pointer type.

Available field types are listed in the following table:

TypeDescription
FT_FLOATA 32-bit floating point value.
FT_LONGA 32-bit integer value.
FT_DOUBLEA 64-bit floating point value.
FT_LARGEA 64-bit integer value.
FT_POINTER  A standard 32-bit address space pointer.
FT_STRING  A 32-bit pointer that refers to a string.

The variable that you point to in the Result argument must match the ResultType that you have specified, or you will risk crashing your program code.

Result
ERR_Okay  The field value was read successfully.
ERR_Args  Invalid arguments were specified.
ERR_NoFieldAccess  Permissions for this field indicate that it is not readable.
ERR_UnsupportedField  The FieldID is not supported by the object's class.

Function:GetFieldVariable()
Short:Retrieves field values by converting them into strings.
Synopsis:ERROR GetFieldVariable(OBJECTPTR Object, STRING Field, STRING Buffer, LONG Size)
Arguments:
Object  Pointer to an object.
Field  The name of the field that is to be retrieved.
Buffer  Pointer to a buffer space large enough to hold the expected field value.
Size  The size of the buffer that has been provided, in bytes.

The GetFieldVariable() function is used in situations where you need to retrieve the value of a field without knowing the field's type or any details beyond the field name. Although simple to use, it is the slowest of the field retrieval instructions because the field's value must be converted from its original type into a string.

You need to provide a buffer that is large enough to hold the expected value. If the buffer is not large enough then the resulting value will be cut short. 256 bytes is considered a large enough buffer for most occasions. In more extreme circumstances, a buffer as large as 1kb may be needed.

This function does not support pointer based fields as they cannot be translated, although an exception is made for string field types.

Result
ERR_Okay  The field was value retrieved.
ERR_UnsupportedField  The requested field is not supported by the object's class.
ERR_NoFieldAccess  Permissions for this field state that it is not readable.
ERR_Mismatch  The field value cannot be converted into a string.

Function:GetFields()
Short:Retrieves multiple field values in a single function call.
Synopsis:ERROR GetFields(OBJECTPTR Object, { FIELD FieldID, APTR Value }...)
Arguments:
Object  Pointer to the object that you want to access.
FieldID  The ID of the field that you want to get.
Value  Points to the storage area that is to receive the field value.

This function can be used to grab the values of multiple fields in a single function call. It is primarily provided to give a speed increase over calling the GetField() function multiple times. The arguments passed to this function are tag-based and must be terminated with a TAGEND marker, as shown in the following example:

   LONG Width, Height;

   GetFields(Screen,
      FID_Width|TLONG,  &Width,
      FID_Height|TLONG, &Height,
      TAGEND);

The field ID's that you specify must be logically or'd with tag definitions that indicate the type of values that you want to get from each field. For instance, if want to retrieve a field in floating point format, then you must use the TFLOAT tag and supply a pointer to a FLOAT variable. Please note that failing to set the tag values correctly can often cause a program to crash.

The recognised tag types are TPTR, TSTRING, TLONG, TLARGE, TFLOAT, and TDOUBLE.

If the GetFields() does not return an ERR_Okay code, you should work on the assumption that all of the field settings failed, meaning that your routine should abort in most cases. This function aborts immediately and makes no attempt to 'salvage' any other fields that may be left in the list, or undo earlier field settings that were successful.

For information on the field retrieval process, refer to the GetField() function.

Result
ERR_Okay  The field values were retrieved successfully.
ERR_Args  Invalid arguments were specified.
ERR_UnsupportedField  One of the fields is not supported by the target object.

Function:GetMessage()
Short:Reads messages from message queues.
Synopsis:ERROR GetMessage(MEMORYID QueueID, LONG Type, LONG Flags, APTR Buffer, LONG Size)
Arguments:
QueueID  The memory ID of the message queue is specified here. If NULL, the message queue of the local Task will be used.
Type  The message type that you would like to receive, or NULL if you would like to receive the next message on the queue.
Flags  This argument is reserved for future use. Set it to NULL.
Buffer  Pointer to a buffer that is large enough to hold the incoming message information. If set to NULL then all accompanying message data will be destroyed.
Size  The byte-size of the buffer that you have supplied.

The GetMessage() function is used to read messages that have been stored in message queues. You can use this function to read the next immediate message stored on the queue, or the first message on the queue that matches a particular Type. It is also possible to call this function in a loop to clear out all messages, until an error code other than ERR_Okay is returned.

Messages will often (although not always) carry data that is relevant to the message type. To retrieve this data you need to supply a buffer, preferably one that is large enough to receive all the data that you expect from your messages. If the buffer is too small, the message data will be cut off to fit inside the buffer.

Message data is written to the supplied buffer with a Message structure (struct Message), which is immediately followed up with the actual message data. The message structure includes the following fields:

FieldDescription
LONG TypeThe message type ID.
LONG Size  The size of the message data, in bytes. If there is no data associated with the message, the Size will be set to NULL.
Result
ERR_Okay  The message was successfully retrieved from the message queue.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Failed to gain access to the message queue.
ERR_Search  No more messages are left on the queue, or no messages that match the given Type are on the queue.

Function:GetName()
Short:Retrieves object names.
Synopsis:ERROR GetName(OBJECTPTR Object, STRING Buffer, LONG Length)
Arguments:
Object  Pointer to the object that you want to get the name of.
Buffer  Pointer to a string buffer that will store the object name.
Length  The total size of the string buffer.

The object kernel allows names to be assigned to objects for the purpose of easy identification. Naming is also important for scripts and identification from a user point of view. Calling GetName() will return the name of any object that you have access to. If the target object has not been assigned a name, then you will receive a null-string.

The length of an object name is limited to the value indicated by the MAX_NAMELEN definition in the "main.h" include file.

Result
ERR_Okay  The name of the object was successfully written to the Buffer.
ERR_Args  The arguments are invalid.

Function:GetOwnerID()
Short:Returns the unique ID of an object's owner.
Synopsis:OBJECTID GetOwnerID(OBJECTID ObjectID)
Arguments:
ObjectID  The ID of the object that you want to examine.

This function can be used on any valid object ID to retrieve the unique ID of its owner. This is the quickest way to retrieve the owner of an object without having to gain exclusive access to the object first.

Please note that if you already have access to an object through an address pointer, the quickest way to learn of its owner is to read the OwnerID field in the object header.

Result
Returns the ID of the object's owner. If the object does not have a owner (i.e. if it is untracked) or if the ID that you provided is invalid, this function will return NULL.


Function:GetResource()
Short:Retrieves miscellaneous resource identifiers.
Synopsis:LARGE GetResource(LONG Resource)
Arguments:
Resource  The ID of the resource that you want to obtain.

The GetResource() function is used to retrieve miscellaneous resource ID's that are either global or local to your task. To retrieve a resource you need to make a reference to it with the Resource parameter. Currently the following resource ID's are available:

ResourceDescription
RES_MESSAGEQUEUE  Use this resource to retrieve the message queue ID of the current task.
RES_TIMEOUTUse this resource to retrieve the timeout value used when the current task goes to sleep (measured in milliseconds).
RES_KERNELVERSIONUse this resource to retrieve the kernel version number.
RES_KERNELREVISIONUse this resource to retrieve the kernel revision number.
RES_CURRENTTASKUse this resource to get the object ID of the current task.
RES_CURRENTTASKPTRUse this resource to get a direct pointer to the current task's object structure.
RES_TOTALMEM.
RES_FREEMEM.
RES_SHAREDMEM.
RES_TOTALSWAP.
RES_FREESWAP.

Result
Returns the value of the resource that you have requested. If the resource ID is not known by the kernel, NULL is returned.


Function:ListChildren()
Short:Returns a list of all children belonging to an object.
Synopsis:ERROR ListChildren(OBJECTID ObjectID, struct ChildEntry *List, LONG *Count)
Arguments:
ObjectID  The ID of the object that you wish to examine.
List  Must refer to an array of ChildEntry structures.
Count  The longword that this argument refers to must be set with a value that indicates the size of your list array. Before returning, this argument will be updated with the total number of entries listed in the array.

The ListChildren() function provides the necessary means for listing an object's children in a single function call.

You need to provide an empty array of ChildEntry structures in the List argument, so that this function has an area to write the results to. The Count argument must point to a longword that indicates the size of the array that you have supplied. Before returning, the ListChildren() function will update the Count variable so that it reflects the total number of children that were written to the array.

The definition of the ChildEntry structure is as follows:

   struct ChildEntry {
      OBJECTID ObjectID;
      LONG ClassID;
   };

The ClassID field is included to assist you in finding specific object types.

Objects that are specially marked with the CHILD flag are not returned in the resulting list; such objects are considered to be private extensions of the targetted parent.

Result
ERR_Okay  Zero or more children were found and listed.
ERR_Args  Invalid arguments were specified.

Function:ListMemory()
Short:Returns a list of public or private memory blocks that have been allocated in the system.
Synopsis:ERROR ListMemory(LONG Flags, struct ListMemory **List)
Arguments:
Flags  Set to MEM_PUBLIC to retrieve public memory blocks, otherwise set to NULL for private memory blocks.
List  Must refer to a "struct ListMemory *" variable to store the resulting array pointer.

The ListMemory() function is typically used for debugging and memory monitoring purposes. It is capable of returning a complete list of public memory blocks, or all private blocks that are local to your task.

The function will return the list by allocating an array and storing it in the variable provided by the List argument. The ListMemory structure used to create the array contains the following fields:

FieldDescription
MEMORYID MemoryIDUnique memory ID.
OBJECTID ObjectIDThe object that the memory block belongs to.
APTR AddressMemory address (applies only to private memory blocks).
LONG SizeSize of the memory block in bytes.
WORD AccessCount  The total count of locks on this memory block.
WORD FlagsThe flags associated with this memory block.
OBJECTID LockIDRefers to the Task that has a current lock on the block.
OBJECTID TaskIDRefers to the Task that created and has overall ownership of the block.

The ListMemory array is terminated with a final entry that has all fields driven to NULL.

Result
ERR_Okay  The function succeeded in listing the system's memory blocks.
ERR_Args  You failed to set the List argument.
ERR_LockFailed  Failed to gain access to the public memory control semaphore.
ERR_AllocMemory  The function failed to allocate the memory needed to create the list.

Function:ListObjects()
Short:Returns a list of objects that match specific parameters.
Synopsis:ERROR ListObjects(CLASSID ClassID, LONG Flags, struct ObjectInfo **List)
Arguments:
ClassID  The ID of the class that you are interested in, or NULL to ignore class types. Note that you may only scan for base classes and not child classes.
Flags  Filtering flags. LOF_PRIVATE and/or LOF_PUBLIC must be set at a minimum.
List  Refers to an address pointer that will store the resulting array.

The ListObjects() function is used to scan objects that are within reach of your process' task space. It returns basic information on objects that the task itself has created, as well as all publicly accessible objects. You are required to provide the ID of the class that you wish to scan for and flags to determine what information you are interested in retrieving.

Currently supported Flags are:

ResourceDescription
LOF_PRIVATERetrieve information on public objects (recognisable by negative object ID's).
LOF_PUBLICRetrieve information on private objects (recognisable by positive object ID's).
LOF_NAMESInclude object names in the ObjectInfo array.

The results of the search are returned in the List argument as an allocated memory block. You will need to free this memory block using FreeMemory() once you are no longer using it. The list is terminated once you reach a NULL entry in the Next field.

The ObjectInfo structure consists of the following fields:

TypeFieldDescription
*ObjectInfoNext Refers to the next entry in the object list.
OBJECTPTR Object The address of the object is specified here unless the object is public, in which case it is NULL.
OBJECTID ObjectID The unique ID of the object is set here.
OBJECTID OwnerID The owner of the object is set here, if it has one.
MEMORYID MessageMIDThe message queue used for communicating with the object is defined here (useful only for public objects).
CLASSID ClassID The class ID of the object.
UBYTE Name[] The name of the object is set here (if it has one). You must set the LOF_NAMES flag if you wish to retrieve object names.
Result
ERR_Okay  At least one object was found and listed.
ERR_Args  The List argument was not specified.
ERR_Search  No objects matching the specified parameters were found.

Function:ManageAction()
Short:Allows modules to intercept and manage action calls.
Synopsis:ERROR ManageAction(LONG ActionID, APTR Routine)
Arguments:
ActionID  The action that is to be managed.
Routine  Pointer to the routine that will manage the object.

Any module can manage an action of its choosing by calling this function with a pointer to a management routine. To remove management of an action, call this function with NULL in the Routine argument.

The routine that is used to manage the action must be in the format ERROR Routine(OBJECTPTR, APTR Parameters). An incorrectly defined routine could crash the system if it mis-reads the stack arguments.

This function is not intended to be called by executable based programs, as the 'area of effect' will be limited to the program itself rather than having a global impact.

Result
ERR_Okay  Success.
ERR_Args  Invalid arguments detected.
ERR_Memory  The management array could not be expanded to accomodate the management routine (internal error).

Function:MemoryIDInfo()
Short:Returns information on memory ID's.
Synopsis:ERROR MemoryIDInfo(MEMORYID MemoryID, LONG Version, struct MemInfo *MemInfo)
Arguments:
MemoryID  Pointer to a valid memory ID.
Version  Must be set to VER_MemoryInfo.
MemInfo  Pointer to a MemInfo structure.

This function can be used to get special details on the attributes of a memory block. It will return information on the Start address, ObjectID, MemoryID, Size and Flags of the memory block that you are querying. The following code segment illustrates correct use of this function:

   struct MemInfo Info;
   if (MemoryIDInfo(MemoryID, VER_MemoryInfo, &Info) IS ERR_Okay) {
      DPrintF("Example:","Memory block #%d is %d bytes large.", Info.MemoryID, Info.Size);
   }

The MemInfo structure consists of the following fields:

FieldDescription
APTR StartThe starting address of the memory block (does not apply to public blocks).
OBJECTID ObjectIDThe object that owns the memory block.
LONG SizeThe size of the memory block in bytes.
WORD AccessCountThe total number of current locks on the memory block.
WORD FlagsThe type of memory.
MEMORYID MemoryID  The unique memory ID.
OBJECTID LockIDRefers to the Task that has a current lock on the block.
OBJECTID TaskIDRefers to the Task that created the block.

If the call to MemoryIDInfo() fails, the MemInfo structure's fields will be driven to NULL and an error code will be returned.

Result
ERR_Okay  Memory analysis successful.
ERR_Args  Invalid arguments were detected.
ERR_MemoryDoesNotExist  The memory ID does not exist.
ERR_SystemCorrupt  Internal memory tables are corrupt.

Function:MemoryPtrInfo()
Short:Returns information on memory addresses.
Synopsis:ERROR MemoryPtrInfo(APTR Memory, LONG Version, struct MemInfo *MemInfo)
Arguments:
Memory  Pointer to a valid memory area.
Version  Must be set to VER_MemoryInfo.
MemInfo  Pointer to a MemInfo structure.

This function can be used to get special details on the attributes of a memory block. It will return information on the Start address, ObjectID, MemoryID, Size and Flags of the memory address that you are querying. The following code segment illustrates correct use of this function:

   struct MemInfo Info;
   if (MemoryPtrInfo(Memory, VER_MemoryInfo, &Info) IS ERR_Okay) {
      DPrintF("Example:","Address $%x is %d bytes large.", Info.Start, Info.Size);
   }

The MemInfo structure consists of the following fields:

FieldDescription
APTR StartThe starting address of the memory block.
OBJECTID ObjectIDThe object that owns the memory block.
LONG SizeThe size of the memory block in bytes.
WORD AccessCountThe total number of current locks on the memory block.
WORD FlagsThe type of memory.
MEMORYID MemoryID  The unique memory ID.
OBJECTID LockIDRefers to the Task that has a current lock on the block.
OBJECTID TaskIDRefers to the Task that created the block.

If the call to MemoryPtrInfo() fails, the MemInfo structure's fields will be driven to NULL and an error code will be returned.

Result
ERR_Okay  Memory analysis successful.
ERR_Args  Invalid arguments were detected.
ERR_MemoryDoesNotExist  There is no record that matches the supplied memory address.

Function:NewObject()
Short:Creates new objects.
Synopsis:ERROR NewObject(LONG ClassID, LONG Flags, OBJECTPTR *Object, OBJECTID *ObjectID, STRING Name)
Arguments:
ClassID  One of the ID's as specified in the "system/register.h" file.
Flags  Flag specifications - set to NULL to allocate a standard private object.
Object  Set this argument to refer to an OBJECTPTR type to store an address reference to the new object.
ObjectID  Set this argument to refer to an OBJECTID type to store a unique ID reference to the new object.
Name  Enabled only if NF_NAME or NF_UNIQUE are specified as Flags. The Name refers to the name that you want to give the object.

The NewObject() function is used to create new objects and register them for use within the object kernel. It can create all possible object types from any one of the classes that have been installed on the system. After creating a new object, you can then proceed to set its fields and initialise it with the Init action so that it can be used as intended.

The ClassID argument identifies the class that the object is to be based upon. Pre-defined class ID's are defined in the "system/register.h" include file and a complete list of known classes is available in the Class Index. ID's for unregistered classes can be found dynamically by using the ResolveClassName() function.

The Flags argument supports a variety of options that affect object creation. The following table describes all flags permitted for use with the NewObject() function:

FlagDescription
NF_UNTRACKEDAn object created with this flag will not be tracked back to the object that created it. If combined with the NF_PUBLIC flag, the object can also remain in memory when the object's related Task is terminated.
NF_PUBLICBy using the NF_PUBLIC flag, you can allocate public objects rather than the default private type. A public object can be accessed and interacted with by any application directly, because the object structure and its data lies in public memory. Public objects can be accessed directly via exclusive access only (refer to the AccessObject() and ReleaseObject() functions).
NF_CHILDThis object type can only be allocated when writing code for a class module. Child objects can only be accessed when the task is running in the context of the child's parent. There is no other way to gain access to these object types. Child objects do not appear in object lists, effectively making them hidden from everything except the parent object.
NF_SHAREDUse this flag if you want to provide foreign tasks with a means of finding and talking to the created object. If you have already specified the NF_PUBLIC field, it is not necessary to use the NF_SHARED flag, as all public objects have shared attributes.
NF_UNIQUEUse this flag if you need to allocate an object which has a guaranteed unique name. By using NF_UNIQUE, you can prevent your code from shadowing an object that exists with the same name. This can be imperative when creating shared and public objects. If it is discovered that an identically named object exists, NewObject() will return ERR_ObjectExists. This flag works in conjunction with the Name argument.
NF_NAMEIf you would like to use the Name argument to give your object a name, you must set the NF_NAME flag or your specification will be ignored.

You will notice that you have the option of receiving the object allocation as an address pointer and/or as a unique object ID. When allocating private objects, you can generally just accept an address result and drive the ObjectID argument to NULL. However when allocating public objects, you should always retrieve the ObjectID, along with the Object address so that you can initialise the new object before releasing it.

If the object is allocated as private and you retrieve both the ObjectID and Object pointer, or if the allocation is public and you retrieve the Object pointer, an internal call will be made to AccessObject() to lock the object and retrieve its address pointer. This means that your call to NewObject() must be matched with a call to the ReleaseObject() function to remove the lock. If the lock is not released, foreign tasks will never be able to access the object, and attempts to Free the object will fail.

By default, new objects are always tracked to the object that holds the current context. If necessary, it is possible to track a new object to a different owner by using the SetOwner() function after calling NewObject().

To destroy an object created with NewObject(), use the Free action.

Result
ERR_Okay  The object was created successfully.
ERR_Args  Invalid arguments were supplied to the function.
ERR_MissingClass  The class that you requested in the ClassID argument could not be found in the system, or the ClassID itself was invalid.
ERR_Failed  General failure.
ERR_ObjectExists  An object with the name you provided already exists in the system (applies only when the NF_UNIQUE flag has been used).

Function:NotifySubscribers()
Short:Used to send notification messages to action subscribers.
Synopsis:void NotifySubscribers(OBJECTPTR Object, ACTIONID ActionID, APTR Args, LONG Flags)
Arguments:
Object  Pointer to the object that you received at the action entry point.
ActionID  The ActionID that you represent.
Args  Pointer to the arguments that you received at the action entry point.
Flags  Optional flags are specified here.

This function can be used by classes that want total control over the timing of action subscriber notification. The system default for notifying action subscribers is to call them after an action has taken place. However, this can be inconvenient if the code for an action wants to perform some extra procedures after the subscribers have been notified. The solution is to use NotifySubscribers(), then continue on with the rest of the routine. If you do this then you should call the function once - anything more will break the system regulations.

The Flags argument currently accepts the following settings:

FieldDescription
NSF_EXCLUSIVE  Instead of messaging each object, the function will attempt to gain exclusive access to each of the subscribed objects and send the notification directly.

 


Function:ObtainMethod()
Short:Returns a direct pointer to an object's method code.
Synopsis:ERROR ObtainMethod(OBJECTPTR Object, LONG MethodID, APTR *Result)
Arguments:
Object  The object to retrieve the method from.
MethodID  The method ID.
Result  The resulting method routine will be stored in this variable.

This function allows you to gain "direct access" to any method of an object's class. Use of this function is only encouraged in areas where speed is essential - e.g. for drawing multiple pixels to a Bitmap.

If succsessful, a pointer to the routine will be returned, which you can call according to the method's calling convention.

Result
ERR_Okay  The method was fetched and stored in the Result variable.
ERR_Args  Incorrect arguments were detected.
ERR_LostClass  The object has lost its class pointer.
ERR_NoMethods  The object does not support any methods.

Function:Permit()
Short:Releases a lock obtained from Forbid().
Synopsis:ERROR Permit(void)

Use the Permit() function to release the system after you have made a call to Forbid().

Result
ERR_Okay  Success.

Function:ProcessMessages()
Short:Processes system messages that are queued in the Task's message buffer.
Synopsis:ERROR ProcessMesages(struct NextMsg *NextMsg, LONG Flags)
Arguments:
NextMsg  Must point to a NextMsg structure to store the function results. If set to NULL, the ProcessMessages() function will not return information on the next message on the queue.
Flags  Optional flags are specified here.

The ProcessMessages() function is used for two purposes:

  • To automatically process system messages that have been sent to the current Task.
  • To report on the current status of the Task's message queue. This involves returning information on user messages that must be processed by the code responsible for maintaining the Task's message queue.

Each Task that opens the Pandora Engine is assigned a message queue by default (refer to the Task class for details). Responding to incoming messages is vital - the queue is the only official point of communication that your Task has with the rest of the system and other Tasks within it. Failing to call the ProcessMessages() function on a regular basis may cause a back-log of messages to be generated, as well as causing problems with areas such as the graphical interface. It is recommended that you call the ProcessMessages() function in the main loop of your program on a frequent basis - around 10 to 30 times per second is sufficient, or you can use this function to permanently wait for messages to arrive.

A "system message" is a pre-defined message type that has a specific purpose within the object kernel. The most obvious example of this is the action message type, which is sent by the ActionMsg() function. Because of the complex code requirements to translate these message types, the ProcessMessages() function is designed to handle them automatically, relieving you from having to deal with them. System messages are never sent to custom message queues - only Task based queues, which is what this function specifically deals with.

A "user message" is a message type that has an unrecognised message type ID, which prevents the ProcessMessages() function from automatically dealing with it. Such message types must be dealt with by the Task, which can choose to respond to the message or ignore it, depending on whether or not it understands the message information. Unique message ID's can be acquired from the AllocateID() function.

On occasion this function will return with system messages that cannot be processed internally, and must be interpreted by the Tasks's message handler. Currently this includes the following message types:

TypeDescription
MSGID_QUIT  Indicates that the user or an external program has requested that the Task be terminated. This message can be sent if the user has hit CTRL-C, or if you have created a main window with a close gadget that has been clicked by the user.

When calling the ProcessMessages() function you are expected to provide a NextMsg structure so that the function can return messages requiring a personal response. If you want to put off responding to these messages types then you can drive the NextMsg argument to NULL, but be aware that you must respond to these messages at some point, or they will gradually fill up the message queue. Before returning, the ProcessMessages() function will fill the NextMsg structure with information on the next message in the queue requiring a task-based response. To receive or destroy the message, you need to follow-up with a call to the GetMessage() function.

The NextMsg structure consists of the following fields:

FieldDescription
LONG TypeThe type (ID) of message that is next on the queue. If there are no messages on the queue that require a task based response, the Type field will be set to NULL.
LONG SizeThe size of the next message's data area, in bytes.
LONG Count  The total number of messages left on the queue that require a task based response.

A number of flags are available that affect message processing. They are:

FlagDescription
MF_CLEAR  Specifying this flag will cause the ProcessMessages() function to process the system messages on the queue and clear every unrecognised user message type, thus providing a guarantee that the message queue will be empty when the function returns.
MF_WAITThis flag causes the function to sleep until new messages arrive. The function will process system messages automatically, and will only return when messages requiring a task-based response are received (e.g. MSGID_QUIT or a user message type). Note that if you have specified a message handler routine with a call to SetResource(RES_MESSAGEHANDLER, &handler), then user messages will be sent to your message handler automatically. In this case, ProcessMessages() never returns unless your handler returns ERR_Terminate in order to stop message processing.

For more information on sending and receiving messages, refer to the GetMessage() and SendMessage() functions.

Result
ERR_Okay  Incoming messages were processed successfully.

Function:RandomNumber()
Short:Generates random numbers.
Synopsis:LONG RandomNumber(LONG Range)
Arguments:
Range  A range between 1 and 2,147,483,648. An invalid range of 0 or less will result in a value of 0 being returned.

This function generates a random number as quickly as possible. In some cases it will use various hardware attributes in order to create guaranteed random numbers. The routine uses one divide to determine the range and will automatically change the random seed value each time you call it. Remember that all generated numbers fall one value BELOW the Range that you specify. Add 1 to your Range if you want to make up for this.

Result
Returns a number greater or equal to 0, and less than Range.


Function:ReallocMemory()
Short:Reallocates memory blocks.
Synopsis:ERROR ReallocMemory(APTR Memory, LONG Size, APTR *Result, MEMORYID *ResultID)
Arguments:
Memory  Pointer to a memory block obtained from AllocMemory().
Size  The new size to be set for the memory block.
Result  Point to an APTR variable to store the resulting pointer to the new memory block.
ResultID  Point to a MEMORYID variable to store the resulting memory block's unique ID.

This function is used to reallocate memory blocks to new lengths. You can shrink or expand a memory block as you wish. The data of your original memory block will be copied over to the new block. If the new block is of a larger size, the left-over bytes will be filled with zero-byte values. If the new block is smaller, you will lose some of the original data.

The original block will be destroyed as a result of calling this function unless the reallocation process fails, in which case your existing memory block will remain valid.

If the memory block is public, the original address will be automatically released and freed on success. The ID of the original memory block will also be preserved in the new block when reallocating public memory.

Result
ERR_Okay  A pointer to the newly allocated memory block has been placed in the Result argument.
ERR_Args  Invalid arguments detected.
ERR_AllocMemory  The function failed to allocate the extra memory space.
ERR_Memory  The memory block to be re-allocated is invalid.

Function:RegisterFD()
Short:Registers a file descriptor for monitoring when the task is asleep.
Synopsis:ERROR RegisterFD(LONG FD, void (*Routine)(LONG FD))
Arguments:
FD  The file descriptor that you want to set.
Routine  The routine that will read from the descriptor when data is detected on it. The template for the function is "void Routine(LONG FD)".

This function will register a file desriptor that will be monitored for activity when the task is sleeping. If activity occurs on the descriptor then the function specified in the Routine parameter will be called. The routine must read all of information from the descriptor, as the task will not be able to sleep until all the data is cleared. If the Routine parameter is not set, the system will automatically clear the FD's content by reading from it.

The file descriptor must be non-blocking if you are not going to set the Routine parameter. The fnctl() function will be used by RegisterFD() to ensure that the O_NONBLOCK flag is set against the descriptor.

This function applies to Linux and Unix based systems only. Because it is system dependent, you are encouraged not to use it unless circumstances are forcing you to.

Please call the DeregisterFD() function once the file descriptor is no longer in use.

Result
ERR_Okay  The FD was successfully registered.
ERR_Args  The FD was set to a value of -1.
ERR_ArrayFull  The maximum number of registerable file descriptors has been reached.
ERR_NoSupport  The system kernel does not support file descriptors.

Function:ReleaseMemory()
Short:Releases memory blocks from access locks.
Synopsis:MEMORYID ReleaseMemory(APTR Address)
Arguments:
Address  Pointer to the memory address that you want to release.

After gaining access to a memory block through AccessMemory(), you will need to release it with this function once you are done with it. By releasing the memory, the access count will decrease and any tasks waiting for usage will then be given a chance for access.

Note that this function does not free the memory block - use FreeMemoryID() for this purpose.

Result
Returns the memory ID of the block that was released or NULL if an error occurred.


Function:ReleaseObject()
Short:Releases objects from exclusive use.
Synopsis:ERROR ReleaseObject(OBJECTPTR Object)
Arguments:
Object  Points to an object address that you have exclusive access to.

If you have obtained exclusive access to an object through AccessObject() and you want to free the lock for other tasks, call this function. Once this function returns, you will no longer have exclusive access to the specified Object (this will make the Object address invalid).

Result
ERR_Okay  Success.
ERR_Args  The Object argument has not been set.
ERR_NoStats  The object is missing its Stats structure (object corrupt).
ERR_NoExclusiveLock  There is no exclusive lock to be freed.
ERR_Memory  The object address is invalid.

Function:ReleaseSemaphore()
Short:Releases a locked semaphore.
Synopsis:ERROR ReleaseSemaphore(LONG Semaphore, LONG Flags)
Arguments:
Semaphore  The semaphore handle that you want to release.
Flags  Must be set to the flags originally pased to AccessSemaphore().

Use the ReleaseSemaphore() function for each time you have called the AccessSemaphore() function. You need to pass this function the same flags that you used in your initial call to AccessSemaphore(). Thus if you used the SMF_NONBLOCKING flag earlier, then you must use it in the Flags parameter to maintain semaphore integrity.

This function returns immediately if you attempt to release a non-existant lock.

Result
ERR_Okay  The semaphore was released.
ERR_Args  The SemaphoreID is invalid.
ERR_Failed  You don't have a lock on the semaphore for what you are attempting to release.
ERR_Forbid  A call to the Forbid() function failed.

Function:ResolveClassName()
Short:Used to resolve unique class ID's from class names.
Synopsis:CLASSID ResolveClassName(STRING Name)
Arguments:
Name  The name of the class that you want to resolve.

This function is used in situations where the name of a class is known, but the ID is not. If for example you want to resolve the class ID of the Picture class, calling this function with an argument of "Picture" will suffice for retrieving the class ID.

Result
Returns the class ID identifed from the class name, or NULL if the class could not be found.


Function:ResolveFields()
Short:Converts field names into globally supported Field ID's.
Synopsis:ERROR ResolveFields( { STRING FieldName, FIELD *FieldID } ...)
Arguments:
FieldName  The name of the field that you want to resolve.
FieldID  Pointer to a LONG value that will store the FieldID.

This function is used to convert field names into ID's. You will need to use it on a regular basis in order to use functions that are based on field ID's, such as GetField(), SetField() and CreateObject().

The following example illustrates how to convert multiple field names into their relevant ID's:

   FIELD FID_Width, FID_XCoord, FID_YCoord;

   ResolveFieldNames("Width",  &FID_Width,
                     "XCoord", &FID_XCoord,
                     "YCoord", &FID_YCoord,
                     TAGEND);
Result
ERR_Okay  The field values were converted successfully.
ERR_Args  No tag-list was provided.
ERR_AccessMemory  Access to the field management block was denied.
ERR_AllocMemory  The function failed to allocate a new field dictionary.
ERR_Memory  A call to MemoryIDInfo() failed.

Function:ScanMessages()
Short:Scans a message queue for multiple occurances of a message type.
Synopsis:ERROR ScanMessages(APTR Queue, LONG *Index, LONG Type, APTR Buffer, LONG Size)
Arguments:
Queue  An address pointer for a message queue (use AccessMemory() to get an address from a message queue ID).
Index  Pointer to a 32-bit value that must initially be set to zero. The ScanMessages() function will automatically update this variable with each call so that it can remember its analysis position.
Type  The message type that you want to scan for, or NULL if you want to scan all messages in the queue.
Buffer  Pointer to a buffer that is large enough to hold the message information. Set to NULL if you are not interested in the message data.
Size  The byte-size of the buffer that you have supplied.

Use the ScanMessages() function to scan a message queue for information without affecting the state of the queue. To use this function, you need to establish a connection to the queue by using the AccessMemory() function first to gain access. Then make repeated calls to ScanMessages() to analyse the queue until it returns an error code other than ERR_Okay. Use ReleaseMemory() to let go of the message queue when you are done with it.

Here is an example that scans the queue of the active task:

   if (AccessMemory(GetResource(RES_MESSAGEQUEUE), MEM_READ, &queue) IS ERR_Okay) {
      while (ScanMessages(queue, &index, MSGID_QUIT, NULL, NULL) IS ERR_Okay) {
         ...
      }
      ReleaseMemory(queue);
   }

Messages will often (although not always) carry data that is relevant to the message type. To retrieve this data you need to supply a buffer, preferably one that is large enough to receive all the data that you expect from your messages. If the buffer is too small, the message data will be cut off to fit inside the buffer.

Message data is written to the supplied buffer with a Message structure (struct Message), which is immediately followed up with the actual message data. The message structure includes the following fields:

Result
ERR_Okay  The next message in the queue was successfully analysed.
ERR_Args  Invalid arguments were supplied to the function.
ERR_Search  No more messages are left on the queue, or no messages that match the given Type are on the queue.

Function:SelfDestruct()
Short:Destroys the task and frees its resources.
Synopsis:void SelfDestruct(void)

This function destroys the task that called this function and then proceeds to free all of its resources as represented by its resource nodes. This is a completely safe and effective way for a task to destroy itself, and can be used for deconstructing a task when it has got into unrecoverable circumstances.

This function will not return.


Function:SendError()
Short:Sends basic error messages to the active debugger.
Synopsis:ERROR SendError(LONG Header, LONG Error)
Arguments:
Header   You must specify a valid header code in this argument, as listed in the "system/errors.h" include file. Valid examples of existing codes are ERH_Kernel, ERH_Message, ERH_Error.
Error   Pre-defined error strings are provided in the "system/errors.h" include file. You will need to search this file for the correct message that you want to send to the user (use a basic keyword to find what you are looking for, e.g. "module" for module related messages).

This function is used to quickly send messages to the system debugger. It uses the codes listed in the system/errors.h file to display the correct string to the user. As an example, if you write a program which is managing files and an error occurs during a write operation, you could send a message such as this:

   SendError(ERH_Error, ERR_Write);

The user will then see a message such as "An error occurred while writing data to a file.".

Result
Returns the same code that you specified in the error argument.


Function:SendMessage()
Short:Send messages to message queues.
Synopsis:ERROR SendMessage(MEMORYID QueueID, LONG Type, LONG Flags, APTR Data, LONG Size)
Arguments:
QueueID  The memory ID of the destination message queue.
Type  The message Type/ID being sent. Unique type ID's can be obtained from AllocateID().
Flags  Set to MF_WAIT if you are prepared to wait in situations where the message queue is too full to accept the new message.
Data  Pointer to the data that will be written to the queue. Set to NULL if there is no data to write.
Size  The byte-size of the data being written to the message queue.

The SendMessage() function is used to write messages to message queues. To write a message to a queue, you must know the memory ID of that queue and be able to provide this function with a message type ID that the queue's handler will understand. If necessary, you can also attach data to the message if it has relevance to the message type.

If the message queue is found to be full, or if the size of your message is larger than the total size of the queue, this function will immediately return with an ERR_ArrayFull error code. If you are prepared to wait for the queue handler to process the waiting messages, specify MF_WAIT in the Flag argument. There is a maximum time-out period of 10 seconds in case the Task responsible for handling the queue is failing to process its messages.

The available Flags that affect this function's behaviour are:

FlagDescription
MF_ADDThe default behaviour - this will add the message to the end of the queue.
MF_NODUPLICATE  If the Type argument matches a message already inside the queue, the new message will not be added and the function will immediately return with ERR_Okay.
MF_UPDATEIf the Type argument matches a message already inside the queue, the data for that message will be deleted, then the new message will be added to the end of the queue.
MF_WAITThis flag tells the function to wait before adding the message if the queue is at maximum capacity.
Result
ERR_Okay  The message was successfully written to the message queue.
ERR_Args  Invalid arguments were passed to the function.
ERR_ArrayFull  The message queue is full.
ERR_TimeOut  The message queue is full and the queue handler has failed to process them over a reasonable time period.
ERR_AccessMemory  Access to the message queue memory was denied.

Function:SetContext()
Short:Tells the system which object currently has resource control.
Synopsis:OBJECTPTR SetContext(OBJECTPTR Object)
Arguments:
Object  Pointer to the object that will take on the new context.

This function provides a way of telling the system which object has control of the current Task. Through the use of this function, you can assign resources to an object as you allocate them. This is particularly important for memory and object handling. For example:

   Action(AC_Init, Screen, NULL);
   PrevContext = SetContext(Screen);

     NewObject(ID_BITMAP, NULL, &Bitmap, NULL);
     AllocMemory(1000, MEM_DATA, &memory, NULL);;

   SetContext(PrevContext);
   Action(AC_Free, Screen, NULL);

In the above code we allocated a Bitmap and a memory block, both of which will be contained by the Screen. When the Free action is called, both the Bitmap and memory block will be freed automatically because they are dependent on the Screen's existence. Please keep in mind that the following is incorrect:

   Action(AC_Init, Screen, NULL);
   PrevContext = SetContext(Screen);

      NewObject(ID_BITMAP, NULL, &Bitmap, NULL);
      AllocMemory(1000, MEM_DATA, &memory, NULL);

   SetContext(PrevContext);
   Action(AC_Free, Screen, NULL);
   Action(AC_Free, Bitmap, NULL);
   FreeMemory(memory);

Freeing the Bitmap and Memory block AFTER the Screen is invalid, however we are allowed to free them before the Screen if necessary.

SetContext() is intended for use by modules and classes. Only on rare occasions will you need to concern yourself with this function. The object kernel will automatically set the correct context when calling any action or method of a class, as do the field management functions.

Result
Returns a pointer to the previous context. Because contexts will nest, you need to call SetContext() a second time with the returned pointer, in order to keep the Task stable.


Function:SetField()
Short:Used to set field values of objects.
Synopsis:ERROR SetField(OBJECTPTR Object, FIELD FieldID, LONG Type, APTR Value)
Arguments:
Object  Pointer to the object that you wish to set.
FieldID  The universal ID of the field you wish to write to.
Type  Indicates the type of value that is being written to the field.
Value  Points to the value that will be written to the field.

The SetField() function is used to write field values to objects. You don't need to know anything about the object structure in order to write information to it - you just need to know what field you want to set.

The following code segment illustrates how to write values to an object:

   LONG XCoord, YCoord;

   SetField(Object, FID_XCoord, FT_LONG, &XCoord);
   SetField(Object, FID_YCoord, FT_LONG, &YCoord);

As SetField() is based on field ID's that reflect field names, you will find that there are occasions where there is no reserved ID for the field that you wish to write. To convert field names into their relevant IDs, call the ResolveFields() function. Reserved field ID's are listed in the "system/fields.h" include file.

When writing to a field you are required to make an educated guess as to its type, in order to prevent a type mismatch from occurring. For instance, writing to a coordinate field would mean that the field is a number, so you should write to the field with a simple numeric type. If you have read the object's class documentation to learn the field type, then use that type in order to prevent a field conversion from taking place.

Available field types are listed in the following table:

TypeDescription
FT_FLOATA 32-bit floating point value.
FT_LONGA 32-bit integer value.
FT_DOUBLEA 64-bit floating point value.
FT_LARGEA 64-bit integer value.
FT_POINTER  A standard 32-bit address space pointer.
FT_STRING  A 32-bit pointer that refers to a string.

The variable that you point to in the Value argument must match the Type that you have specified, or you will risk crashing your program code.

Result
ERR_Okay  The field value was updated.
ERR_Args  Invalid arguments were specified.
ERR_UnsupportedField  The specified field is not support by the object's class.
ERR_NoFieldAccess  The field is read-only.

Function:SetFieldVariable()
Short:Sets any field using an abstract string value.
Synopsis:ERROR SetFieldVariable(OBJECTPTR Object, STRING Field, STRING Value)
Arguments:
Object  Pointer to the object to be accessed.
Field  The name of the field that you want to set.
Value  A string value to be written to the field.

The SetFieldVariable() function is used in situations where a program wants to set a field, without having to know the field's type or any details beyond the field name. Although simple to use, it is the slowest of the field setting instructions because the Value that is passed must be converted from a string to the correct field type.

This function has some programmed intelligence, and will convert references to flags and lookup tables to the correct numeric values (e.g. setting the Flags field of a Render object with "STICKY|MASK" will result in the references being converted to the correct hexadecimal value).

Setting ObjectID based fields also enables special support for the commands "self", "owner" and ID numbers (identifiable by a hash and a following number, such as "#14592"). In all other cases the Value string is considered to refer to an object's name. The "self" keyword will translate to the object specified by the Object argument, and Owner will likewise translate to the owner of that Object.

Because this function was primarily designed for situations where speed is not so much of a factor in comparison to convenience, it is commonly used by script languages and other types of batch processing routines.

Result
ERR_Okay  The field was set successfully.
ERR_Search  The named field does not exist in the object.
ERR_Args  Invalid arguments were passed to the function.

Function:SetFields()
Short:Sets the values of multiple object fields.
Synopsis:ERROR SetFields(*Object, { LONG FieldID, VARIABLE Value }...)
Arguments:
Object  Pointer to the object that you want to access.
FieldID  The ID of the field that you want to set.
Value  The value that you want to set in the field.

This function can be used to set the values of more than one field in a single function call, by using tags. It is provided for the purpose of giving a speed increase over calling the SetField() function multiple times.

The tags that you pass to this function must be arranged in a format of field ID's and values. The following example illustrates:

   SetFields(Render,
      FID_Name|TSTRING,  "MyRender",
      FID_Width|TLONG,   50,
      FID_Height|TLONG,  100,
      FID_XCoord|TFLOAT, 86.5,
      FID_YCoord|TFLOAT, 40.0,
      TAGEND);

The field ID's that you specify must be logically or'd with tag definitions that indicate the type of values that you have set for each field. For instance, if you set a floating point value for a field, then you must use the TFLOAT tag so that the SetFields() function can interpret the paired value correctly. Please note that failing to set the tag values correctly can often cause a program to crash.

The recognised tag types are TPTR, TSTRING, TLONG, TLARGE, TFLOAT, and TDOUBLE. There are also two special tag types available: TUNLISTED and TTRANS. TUNLISTED will divert the field setting through the SetUnlistedField action. TTRANS can be used with string fields, forcing the string to first be parsed through StrTranslate() in the Strings module.

If this function fails, it should be assumed that all of the field settings failed. This means that your routine should abort in most cases. This function makes no attempt to 'salvage' any other fields that may be left in the list or undo any previously successful field settings.

Result
ERR_Okay  All fields were set successfully.
ERR_Args  Invalid arguments were specified.
ERR_UnsupportedField  One of the fields is not supported by the target object.
ERR_Failed  A field setting failed due to an unspecified error.

Function:SetName()
Short:Sets the name of an object.
Synopsis:ERROR SetName(OBJECTPTR Object, STRING Name)
Arguments:
Object  Pointer to the object that you want to set the name of.
Name  The name that you want to set for the object.

To set the name of an object, use this function. Please note that the length of the Name will be limited to the value indicated in the "main.h" include file, under the MAX_NAMELEN definition. If the Name is longer than the allowed length, it will be trimmed to fit.

Result
ERR_Okay  The name was set successfully.
ERR_Args  The arguments that were passed are invalid.
ERR_Search  The Object is not recognised by the system - the address may be invalid.
ERR_AccessDenied  The function could not gain access to the shared objects table (internal error).

Function:SetOwner()
Short:Changes object ownership dynamically.
Synopsis:ERROR SetOwner(OBJECTPTR Object, OBJECTPTR Owner)
Arguments:
Object  Pointer to the object that you want to set the owner for.
Owner  Pointer to the new owner for the object.

Setting the owner of an object will change its ownership to that of the object that you supply to this function. Ownership is an attribute that affects an object's position within the system hierarchy as well as impacting on the resource tracking of the object in question. Internally, setting a new owner will cause three things to happen:

  1. The new owner will be told about the object by sending it a NewChild action. If the owner rejects the object by sending back an error, SetOwner() will fail immediately.
  2. The object's class will then be told about the change by sending it a NewOwner action.
  3. The resource tracking of the new owner will be modified so that the object is accepted as its child. This means that if and when the owning object is destroyed, the new child object will be destroyed with it.

If the Object does not support the NewOwner action, or the Owner does not support the NewChild action, then the process will not fail. It will continue on the assumption that neither party is concerned about ownerhsip management.

Result
ERR_Okay  The change was successful.
ERR_Args  Invalid arguments were detected.

Function:SetResource()
Short:Sets miscellaneous resource identifiers.
Synopsis:LARGE SetResource(LONG Resource, LARGE Value)
Arguments:
Resource  The ID of the resource that you want to set.
Value  The new value that you want to set for the resource.

The SetResource() function is used to set miscellaneous resource ID's that are either global or local to your task. To set a resource you need to make a reference to it with the Resource parameter and provide a new setting in the Value parameter. Currently the following resource ID's are available:

ResourceDescription
RES_TIMEOUTUse this resource to set the default timeout value to use when the task goes to sleep (measured in milliseconds).
RES_MESSAGEHANDLERUse this resource to set the default message handler for your task. The value that you specify must be a reference to a function with the synopsis "ERROR MessageHandler(struct Message *)". Your message handling routine will be sent user messages whenever the message processing functions (like ProcessMessages() and WaitTime()) encounter them. Essentially this means that your function will be used as a callback routine. You can return any type of error code without consequence apart from special option ERR_Terminate, which allows you to tell the system to break out of timer-based message processing loops.

Result
Returns the previous value used for the resource that you have set. If the resource ID that you provide is invalid, NULL is returned.


Function:StepBack()
Short:Steps back the debugging tree.
Synopsis:void StepBack(void)

If you call the DPrintF() function and utilise its stepping feature, you will need to make a matching call to StepBack() in order to return the debugging tree to its original position. Take the following code as an example:

   DPrintF("~Hello:","World.");
      DPrintF("Goodbye:","World.");
      StepBack();
   DPrintF("Debug:","Back to normal.");

This will produce the following output:

  Hello         World.
   Goodbye      World.
  Debug         Back to normal.

If the call to StepBack() was eliminated, the debugger would be permanently put out of step, as follows:

  Hello         World.
   Goodbye      World.
   Debug        Back to normal.

As is shown here, it should become apparent that all stepping calls must be matched with a call to StepBack() or the debug tree structure will quickly become meaningless. Please ensure that when debugging complicated functions that you call StepBack() at all of your function exit points.


Function:StrCompare()
Short:Compares strings to see if they are identical.
Synopsis:ERROR StrCompare(STRING String1, STRING String2, LONG Length, LONG Flags)
Arguments:
String1  Pointer to the first string.
String2  Pointer to the second string.
Length  The maximum amount of characters that you want to compare. Does not apply to wildcard comparisons.
Flags  Optional flags.

This function compares two strings against each other. If the strings match then it returns ERR_Okay, otherwise it returns ERR_False. By default the function is not case sensitive, but you can turn on case sensitivity by specifying the STR_CASE flag.

If you set the Length to NULL, the function will compare both strings for differences until a string terminates. If all characters matched up until the termination, ERR_Okay will be returned regardless of whether or not one of the strings happened to be longer than the other.

If Length is not NULL, then the comparison will stop at the specified amount of characters. If one of the strings terminates before the specified Length is matched, ERR_False will be returned.

If the STR_MATCHLENGTH flag is specified, you can force the function into returning an ERR_Okay code only on the condition that both strings are of matching lengths. This flag is typically specified when the Length argument has been set to NULL.

If the STR_WILDCARD flag is set, the first string that is passed may contain wild card characters, which gives special meaning to the asterisk and question mark characters. This allows you to make abstract comparisons, for instance "ABC*" would match to "ABCDEF" and "1?3" would match to "1x3".

Result
ERR_Okay  The strings match.
ERR_False  The strings do not match.
ERR_Args  Invalid arguments were submitted to the function.

Function:SubscribeAction()
Short:Used for listening to action activity in foreign objects.
Synopsis:ERROR SubscribeAction(OBJECTPTR Object, ACTIONID Action, OBJECTPTR Subscriber)
Arguments:
Object  Pointer to the object that you wish to subscribe to.
Action  The ID of the action that you wish to monitor.
Subscriber  A pointer to the object that you represent goes here. If your program code does not represent a particular object, a pointer to your Task object should be specified.

The SubscribeAction() function is provided for objects that wish to be notified when actions are being executed on foreign objects. This is typically referred to as "action monitoring". Action monitoring is used for a wide variety of purposes and is especially useful for responding to events in the user interface, including pointer movement, window resizing and graphics drawing.

To subscribe to the actions of another object, you need to acquire its address pointer, then call this function with the action ID that you want to monitor. The Subscriber argument needs to indicate what object you represent - if you don't represent an object, you need to gain access to your local Task object and point to it in the Subscriber argument. The following example illustrates how to listen to a Render object's Draw action, for the purposes of drawing graphics to it:

   if (AccessObject(RenderID, 3000, &Drawable) IS ERR_Okay) {
      SubscribeAction(Drawable, AC_Draw, Self);
      ReleaseObject(Drawable);
   }

When someone calls a matching action on the object that you are listening to, its code will be executed first, then all relevant action subscribers will be notified of the event. This is done by sending each subscriber an action message (AC_ActionNotify) with information on the action ID, the ID of the object that was called, and a copy of the arguments that were used. For more detail, refer to the ActionNotify section of the Action Support Guide. If you are writing a standard executable rather than a class, refer to one the graphical example programs provided with Pandora to see how ActionNotify events can be intercepted through the Task object.

This function does not support subscriptions to methods.

When you need to terminate an action subscription, use the UnsubscribeAction() function.

Result
ERR_Okay  The subscription was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Access to the Object's subscription list was denied.
ERR_AllocMemory  A subscription list could not be allocated for the object.

Function:SubscribeActionTags()
Short:Used for listening to action activity in foreign objects.
Synopsis:ERROR SubscribeActionTags(OBJECTPTR Object, OBJECTPTR Subscriber, ACTIONID Action, ...)
Arguments:
Object  Pointer to the object that you wish to subscribe to.
Subscriber  A pointer to the object that you represent goes here. If your program code does not represent a particular object, a pointer to your Task object should be specified.
Action  The ID of the action(s) that you wish to monitor. The action list must be terminated with TAGEND.

This function is identical to SubscribeAction() in every aspect except the fact that it is tag based. The following example illustrates typical usage:

   SubscribeActionTags(object, self, AC_Draw, AC_Redimension, TAGEND);
Result
ERR_Okay  The subscription was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Access to the Object's subscription list was denied.
ERR_AllocMemory  A subscription list could not be allocated for the object.

Function:SubscribeChannel()
Short:Used for listening to the data channels of foreign objects.
Synopsis:ERROR SubscribeChannel(OBJECTPTR Object, OBJECTPTR Subscriber)
Arguments:
Object  Pointer to the object that you wish to subscribe to.
Subscriber  A pointer to the object that you represent goes here. If your program code does not represent a particular object, a pointer to your Task object should be specified.

This function is used to subscribe to objects that support data channel based messaging. Certain hardware based objects, like those originating from the Joyport and Keyboard classes are good examples of channel supportive class types.

After subscribing to an object's data channel, it will intermittently send data messages (via the DataChannel action) to the object that you referred to in the Subscriber argument. The exact formatting of the data that is sent will be documented by the class of the object that you have subscribed to. Refer to the DataChannel section in the Action List document for information on this action.

While it is possible to subscribe to the data channel of any object, if the object's documentation does not discuss data channel support, then it is unlikely that it will send the subscribed object any messages.

Result
ERR_Okay  The subscription was successful.
ERR_Args  One of the required arguments is set to NULL.
ERR_AllocMemory  The function could not allocate a channel list for the target object.
ERR_AccessMemory  Access to the target object's channel list was denied.

Function:SubscribeField()
Short:Used for responding to field activity in foreign objects.
Synopsis:ERROR SubscribeField(OBJECTPTR Object, FIELD FieldID, OBJECTPTR Subscriber)
Arguments:
Object  Pointer to the object that you wish to subscriber to.
FieldID  The ID of the field that you wish to monitor.
Subscriber  A pointer to the object that will receive the FieldNotify action must be specified here. If your program code does not represent a particular object, a pointer to your Task object should be specified.

The SubscribeField() function is used for field monitoring purposes. If you need to be alerted when a foreign object has a field updated through SetField(), SetFields() or SetFieldVariable(), you can use a field subscription to be notified of the alteration.

To subscribe to the field of another object, you need to acquire the object's address pointer, then call this function with the field ID that you want to monitor. The Subscriber argument needs to indicate what object you represent - if you don't represent an object, you need to gain access to your local Task object and point to it in the Subscriber argument. The following example illustrates how to listen to a Render object's coordinate values:

   if (AccessObject(RenderID, 3000, &Drawable) IS ERR_Okay) {
      SubscribeField(Drawable, FID_Width, Self);
      SubscribeField(Drawable, FID_Height, Self);
      ReleaseObject(Drawable);
   }

When someone writes to a subscribed field using the object kernel, all relevant field subscribers will be notified of the event. This is done by sending each subscriber an action message (AC_FieldNotify) with information on the field ID, the ID of the object that was called, and the new field value (but only if it is an integer or float - pointers cannot be provided). For more detail, refer to the FieldNotify section of the Action Support Guide.

When you need to terminate a field subscription, use the UnsubscribeField() function.

Result
ERR_Okay  The subscription was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Access to the target object's field subscriber list was denied.
ERR_AllocMemory  A subscriber list could not be allocated for the object.

Function:SubscribeTimer()
Short:Subscribes an object to the system's timer service.
Synopsis:ERROR SubscribeTimer(OBJECTID SubscriberID, LONG Interval)
Arguments:
SubscriberID  Must refer to the object that will receive the timer calls.
Interval  The total number of milliseconds to wait between timer calls (NB: a millisecond is 1/1000th of a second). If the value is signed, timer preservation will be enabled.

This function is used to send timer signals to objects at regular intervals of your choosing. Simply provide this function with the unique ID of the object that is to receive the signals, and the Interval to use before sending subsequent signals. Please note that the Interval is measured in milliseconds (1/1000th of a second).

Timer signals are sent to objects by messaging them with a Timer action. In order for an object to receive the timer signal, its class must therefore support the Timer action or the call will be wasted. Also, the Task that is responsible for the object must regularly process its message log or it will lose timer signals. The smaller the Interval that has been used, the more imperative regular message checking becomes.

A subcription to the timer service can be terminated at any time by making a call to the UnsubscribeTimer() function. If you call the SubscribeTimer() again without unsubscribing, the timer is reset and the interval is changed to the new value that you have specified. You can preserve existing timer settings if they exist for the subscriber by setting the Interval to a signed value.

Result
ERR_Okay  The subscription was successful.
ERR_ArrayFull  The Task's timer array is at capacity - no more subscriptions can be granted.

Function:SystemTime()
Short:Returns the current system time, in milliseconds.
Synopsis:LARGE SystemTime(void)

This function returns the current 'system time', in milliseconds (1/1000th of a second). The value could be derived from the amount of time elapsed since the system was turned on, or the amount elapsed since a specific date. The specifics of this are determined by the host system.

Result
Returns the system time in milliseconds.


Function:TotalChildren()
Short:Calculates the total number of children belonging to an object.
Synopsis:LONG TotalChildren(OBJECTID ObjectID)
Arguments:
ObjectID  The unique ID of the object to be examined.

This function calculates the total number of children that belong to an object. It is commonly used for object analysis and just before calls to the ListChildren() function.

Result
Returns the total number of children that belong to the object.


Function:UnsubscribeAction()
Short:Removes action subscriptions from external objects.
Synopsis:ERROR UnsubscribeAction(OBJECTPTR Object, ACTIONID Action, OBJECTID SubscriberID)
Arguments:
Object  The object that you are unsubscribing from.
ActionID  The ID of the action that will be unsubscribed, or NULL for all actions.
SubscriberID  The ID of the subscriber that was set in the original subscription call.

If you have subscribed to the action/s of a foreign object using the SubscribeAction() function, you can terminate the subscription by calling the UnsubscribeAction() function. Simply provide the ID of the action that you want to unsubscribe from as well as the unique ID of the subscriber that you used in the original subscription call.

If you have more than one subscription and you want to terminate them all, set the ActionID argument to NULL.

Result
ERR_Okay  The termination of service was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_AccessMemory  Access to the object's action subscription array was denied.

Function:UnsubscribeChannel()
Short:Removes data channel subscriptions from an external object.
Synopsis:ERROR UnsubscribeChannel(OBJECTPTR Object, OBJECTID SubscriberID)
Arguments:
Object  The object that you are unsubscribing from.
SubscriberID  The ID of the subscriber that was set in the original subscription call.

If you have subscribed to a foreign object's data channel using the SubscribeChannel() function, you can terminate the subscription by calling the UnsubscribeChannel() function. All that needs to be provided by you is the ID of the object that is to be unsubscribed.

Result
ERR_Okay  The termination of service was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_Search  The object referred to by the SubscriberID was not in the subscription list.
ERR_AccessMemory  Access to the object's channel subscription array was denied.

Function:UnsubscribeField()
Short:Removes field-based subscriptions from an object.
Synopsis:ERROR UnsubscribeField(OBJECTPTR Object, FIELD FieldID, OBJECTID SubscriberID)
Arguments:
Object  The object that you are unsubscribing from.
FieldID  The ID of the field that will be unsubscribed, or NULL for all fields.
SubscriberID  The ID of the subscriber that was set in the original subscription call.

If you have subscribed to a foreign object's field/s using the SubscribeField() function, you can terminate the subscription by calling the UnsubscribeField() function. Simply provide the ID of the field that you want to unsubscribe from as well as the unique ID of the subscriber that you used in the original subscription call.

If you have more than one subscription and you want to terminate them all, set the FieldID argument to NULL.

Result
ERR_Okay  The termination of service was successful.
ERR_Args  Invalid arguments were supplied to the function.
ERR_Search  The object referred to by the SubscriberID was not in the subscription list.
ERR_AccessMemory  Access to the object's field subscription array was denied.

Function:UnsubscribeTimer()
Short:Unsubscribes an object from the system's timer service.
Synopsis:ERROR UnsubscribeTimer(OBJECTID SubscriberID)
Arguments:
SubscriberID  The ID of the object that is to be unsubscribed from the timer service.

This function is used to terminate timer subscriptions created from the SubscribeTimer() function. All that needs to be provided by you is the ID of the object that is to be unsubscribed.

Result
ERR_Okay  The object was unsubscribed.
ERR_Args  The SubscriberID argument was set to NULL.
ERR_Search  The object ID was not found in the timer management array.

Function:UpdateMessage()
Short:Updates the data of any message that is queued.
Synopsis:ERROR UpdateMessage(APTR Queue, LONG MessageID, LONG Type, APTR Data, LONG Size)
Arguments:
Queue  Points to the message queue that you want to update.
MessageID  The ID of the message that you want to update.
Type  The type of message can be changed if you set this parameter. Set to -1 to delete the message.
Data  Pointer to a buffer that contains the new data for the message.
Size  The byte-size of the buffer that you have supplied. You may not exceed the size of the message that you are updating.

The UpdateMessage() function provides a facility for updating the content of existing messages on a queue. You are required to know the ID of the message that you are going to update and will need to provide the new message Type and/or Data that is to be set against the message.

Messages can be deleted from the queue by setting the Type to -1. There is no need to provide buffer information when deleting a message.

If you supply a data buffer, then its size should equal that of the data already set against the message. The size will be trimmed if it exceeds that of the existing message, as this function cannot expand the size of the queue.

Result
ERR_Okay  The message was successfully updated.
ERR_Args  Invalid arguments were supplied to the function.
ERR_Search  The ID that you supplied does not refer to a message in the queue.

Function:WaitTime()
Short:Waits for a specified amount of seconds and/or microseconds.
Synopsis:void WaitTime(LONG Seconds, LONG MicroSeconds)
Arguments:
Seconds  The amount of seconds to wait for.
MicroSeconds  The amount of microseconds to wait for. Please note that a microsecond is one-millionth of a second - 1/1000000.

This function waits for a period of time as specified by the Seconds and MicroSeconds arguments. While waiting, your task will continue to process incoming system messages every 10,000 micro seconds to prevent a message backlog from occurring. Message processing does not occur if the time to wait is 10,000 micro seconds or less in length.

If a user message arrives in the queue, it will remain unprocessed while the timer continues to tick down. You can alter this behaviour by setting the RES_MESSAGEHANDLER resource. This allows you to continue to intercept user messages while the timer is running down. It also gives you the ability to terminate the WaitTime() function at any time, which can be useful if a MSGID_QUIT message arrives in your message queue.


Function:WatchPublicMemory()
Short:Monitors public memory blocks for foreign access.
Synopsis:ERROR WatchPublicMemory(APTR Memory, MEMORYID MemoryID, LONG Timer)
Arguments:
Memory  Pointer to the memory address of the public block that you are monitoring (address must be obtained through AccessMemory().
MemoryID  The ID of the memory block that you are monitoring.
Timer  The time-out value, measured in milliseconds. If the time-out expires before some other task uses the memory block, ERR_TimeOut will be returned by this function. If the time-out value is set to less than zero, the function will wait indefinitely.

This function is used to "watch" public memory blocks. Calling this function on a public memory block will cause your Task to stop and wait until a foreign Task uses and releases that block. When it does so, your Task will be awoken and the function will return, alerting you to the fact that someone else has used and possibly altered the memory block.

To wait on a block, you first need to gain access to it with the AccessMemory() function. After doing so, call this function with the address that you have locked along with the ID of the public memory block. Please note that this function will release the access lock before returning, so do not follow-up with a ReleaseMemory() call when this function returns. You will need to call AccessMemory() again if you want to inspect the memory block afterwards.

To prevent excessive waiting, you can specify a Timer in case the block you are monitoring is not accessed within a reasonable amount of time. When the time-out expires, the function will return with an error of ERR_TimeOut. If you don't mind waiting indefinitely then the Timer argument can be set to zero, but this is not recommended for normal practice.

This function does not work on private memory blocks.

Result
ERR_Okay  The memory has been accessed and released by a foreign task.
ERR_Args  Invalid arguments were supplied to the function.
ERR_LockFailed  The function failed to gain access to the public memory control semaphore.
ERR_MemoryDoesNotExist  The supplied MemoryID could not be found in internal memory records.
ERR_TimeOut  The time-out period expired before anyone used the memory block.