The core library provides system calls and controls for the Kotuku system.

The Kotuku Core is a system library that provides a universal API that works on multiple platforms. It follows an object oriented design with granular resource tracking to minimise resource usage and memory leaks.

The portability of the core has been safe-guarded by keeping the functions as generalised as possible. When writing code for a target platform it will be possible for the application to be completely sandboxed if the host's system calls are avoided.

This documentation is intended for technical reference and is not suitable as an introductory guide to the framework.

Functions

Events

BroadcastEvent | GetEventID | SubscribeEvent | UnsubscribeEvent

Fields

FieldName | FindField

Files

AddInfoTag | AnalysePath | CompareFilePaths | CopyFile | CreateFolder | CreateLink | DeleteFile | DeleteVolume | IdentifyFile | LoadFile | MoveFile | OpenDir | ReadFileToBuffer | ReadInfoTag | ResolveGroupID | ResolvePath | ResolveUserID | ScanDir | SetDefaultPermissions | SetVolume | UnloadFile

Memory

AllocResource | CheckResourceExists | FreeResource | PinResource | TrackResource | UnpinResource

Messages

AddMsgHandler | ProcessMessages | ScanMessages | SendMessage | UpdateMessage | WaitForObjects

Objects

AccessObject | Action | ActionList | AsyncAction | AsyncCancel | AsyncPending | AsyncWait | CheckAction | ClassDatabase | CurrentContext | FindClass | FindObject | FreeObject | GetActionMsg | GetClassID | GetObjectPtr | GetOwnerID | InitObject | ListChildren | LockObject | NewObject | NotifySubscribers | ParentContext | QueueAction | ReleaseObject | ResolveClassID | ResolveClassName | SetName | SetOwner | SubscribeAction | UnsubscribeAction

System

AdjustLogLevel | AllocateID | CurrentTask | GenCRC32 | GetResource | GetSystemState | GetThreadID | PreciseTime | RegisterFD | SetLogCallback | SetResource | SetResourcePath | SubscribeTimer | UpdateTimer | WaitTime | WakeThread

Structures

ActionArray | ActionTable | ChildEntry | ClassRecord | ClipRectangle | ColourFormat | DateTime | DirInfo | Edges | FRGB | Field | FieldArray | FieldDef | FileFeedback | FileInfo | FunctionField | HSV | InputEvent | Message | ObjectSignal | OpenInfo | OpenTag | RGB16 | RGB32 | RGB8 | RGBPalette | ResourceRecord | SystemState | Unit | dcAudio | dcDeviceInput | dcKeyEntry | dcRequest

Classes

CompressedStream | Compression | Config | File | MetaClass | Module | Script | StorageDevice | Task | Thread | Time

Constants

AC | CCF | CONTYPE | EVG | FBK | IDTYPE | JET | JTYPE | LDF | LOC | MEM | MSF | MSGID | NF | OPF | PERMIT | PMF | RDF | RES | RFD | RP | RSF | TOI | VOLUME

AccessObject()

Grants exclusive access to objects via unique ID.

This function resolves an object ID to its address and acquires a lock on the object so that other threads cannot use it simultaneously.

If the Object is already locked, the function will wait until it becomes available. This must occur within the amount of time specified in the Milliseconds parameter. If the time expires, the function will return with an ERR::TimeOut error code. If successful, ERR::Okay is returned and a reference to the object's address is stored in the Result variable.

It is crucial that calls to AccessObject() are followed with a call to ReleaseObject() once the lock is no longer required. Calls to AccessObject() will also nest, so they must be paired with ReleaseObject() correctly.

It is recommended that C++ developers use the ScopedObjectLock class to acquire object locks rather than making direct calls to AccessObject(). The following example illustrates lock acquisition within a 1 second time limit:

{
   kt::ScopedObjectLock<OBJECTPTR> obj(my_object_id, 1000);
   if (lock.granted()) {
      obj.acDraw();
   }
}

Error Codes

Action()

This function is responsible for executing action routines.

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 class implementation. You can find a complete list of available actions and their associated details in the Kotuku Wiki. The actions and methods supported by any class will be referenced in their auto-generated documentation.

Here are two examples that demonstrate how to make an action call. The first performs an activation, 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::Activate, Image, nullptr);

2. struct acMove move = { 30, 15, 0 };
   Action(AC::Move, Window, &move);

In all cases, action calls in C++ can be simplified by using their corresponding stub functions:

1.  acActivate(Image);

2a. acMove(Window, 30, 15, 0);

2b. Window->move(30, 15, 0);

If the class of an object does not support the Action ID, an error code of ERR::NoSupport is returned. To test an object to see if its class supports an action, use the CheckAction() function.

Error Codes

ActionList()

Returns the global action table.

This function returns an array of all actions supported by the Core, including name, arguments and structure size. The ID of each action is indicated by its index within the array.

Index zero is an empty record because valid action IDs start from one rather than zero.

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. The following illustrates two argument definition examples:

struct FunctionField argsCopyData[] = {
   { "Destination", FD_INT  },
   { nullptr, 0 }
};

struct FunctionField argsResize[] = {
   { "Width",  FD_DOUBLE },
   { "Height", FD_DOUBLE },
   { "Depth",  FD_DOUBLE },
   { nullptr, 0 }
};

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

Supplementary flags can be combined with the above types to provide additional information about the argument:

AddInfoTag()

Adds new tags to FileInfo structures.

This function adds file tags to FileInfo structures. It is intended for use by the Core and external drivers only. Tags allow extended attributes to be associated with a file, for example the number of seconds of audio in an MP3 file.

Error Codes

AddMsgHandler()

Adds a new message handler for processing incoming messages.

This function allows handlers to be added for the interception of incoming messages. Message handling works as follows:

During a call to ProcessMessages(), each incoming message will be scanned to determine if a message handler is able to process that message. All handlers that accept the message type will be called with a copy of the message structure and any additional data. The message is then removed from the message queue.

When calling AddMsgHandler(), the MsgType acts as a filter so that only messages with the same type identifier will be passed to the handler. The Routine parameter must point to the function handler, which will follow this definition:

ERR handler(APTR Meta, MSGID MsgID, INT MsgType, APTR Message, INT MsgSize)

The handler must return ERR::Okay if the message was handled. This means that the message will not be passed to message handlers that are yet to receive the message. Throw ERR::NothingDone if the message has been ignored or ERR::Continue if the message was processed but may be analysed by other handlers. Throw ERR::Terminate to break the current ProcessMessages() loop. When using Tiri, this is best achieved with raise ERR_Terminate in the handler.

The handler will be identified by a unique pointer returned in the Handle parameter. This handle will be garbage collected or can be passed to FreeResource() once it is no longer required.

Error Codes

AdjustLogLevel()

Adjusts the base-line of all log messages.

This function adjusts the detail level of all outgoing log messages. To illustrate, setting the Delta value to 1 would result in level 5 (API) log messages being bumped to level 6. If the user's maximum log level output is 5, no further API messages will be output until the base-line is reduced to normal.

The main purpose of AdjustLogLevel() is to reduce log noise. For instance, creating a new desktop window will result in a large number of new log messages. Raising the base-line by 2 before creating the window would eliminate the noise if the user has the log level set to 5 (API). Re-running the program with a log level of 7 or more would make the messages visible again.

A secondary use of this function is to increase the verbosity of log messages when debugging an area of interest. For instance, if a program is run with a warning level of 2 and we want to see the log output for a function at API level, call AdjustLogLevel() with a Delta of -3 to raise the base-line to 5.

Adjustments to the base-line are accumulative, so small increments of 1 or 2 are encouraged. To revert logging to the previous base-line, call this function again with a negation of the previously passed value.

Note: This function is complemented by the SetResource() function with the RES::LOG_LEVEL option, which permanently changes the log level for the duration of the program.

Result

Returns the absolute base-line value that was active prior to calling this function.

AllocResource()

Allocates a managed memory block on the heap.

AllocResource() reserves an area of memory of Size bytes and tracks it using the supplied resource manager. If no Manager is provided, the default memory manager is used. The function returns a pointer to the allocated memory block in Address. The allocated memory is automatically associated with the current execution context, allowing it to be automatically cleaned up when the context is destroyed.

Example usage:

APTR address;
if (!AllocResource(1000, MEM::NIL, &address, nullptr)) {
   // Use memory block...
   FreeResource(address);
}

Memory blocks are automatically associated with their owning object context, enabling automatic cleanup when the owner is destroyed. This prevents memory leaks in object-oriented code.

Error Codes

AllocateID()

Generates unique ID's for general purposes.

This function generates unique ID's that can be used in other Core functions. A Type indicator is required and the resulting number will be unique to that Type only.

ID allocations are permanent, so there is no need to free the allocated ID once it is no longer required.

Result

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

AnalysePath()

Analyses paths to determine their type (file, folder or volume).

This function will analyse a path and determine the type of file that the path is referring to. For instance, a path of user:documents/ would indicate a folder reference. A path of system: would be recognised as a volume. A path of user:documents/copyright.txt would be recognised as a file.

Ambiguous references are analysed to get the correct type - for example user:documents/helloworld could refer to a folder or file, so the path is analysed to check the file type. On exceptional occasions where the path could be interpreted as either a folder or a file, preference is given to the folder.

File path approximation is supported if the Path is prefixed with a ~ character (e.g. ~images:photo could be matched to photo.jpg in the same folder).

To check if a volume name is valid, call ResolvePath() first and then pass the resulting path to this function.

If the queried path does not exist, a fail code is returned. This behaviour makes the AnalysePath() function a good candidate for testing the validity of a path string.

Error Codes

AsyncAction()

Submit an action for asynchronous execution against an object.

This function submits an action or method for asynchronous execution against Object. The runtime allocates a worker thread to execute the action; the caller does not manage threads directly. Please refer to the Action() function for general information on action execution.

To receive feedback of the action's completion, use the Callback parameter and supply a function. The prototype for the callback routine is callback(ACTIONID ActionID, OBJECTPTR Object, ERR Error, APTR Meta)

Actions targeting the same object are serialised through a per-object FIFO queue. If an async action is already in-flight for the given object, subsequent calls to AsyncAction() will queue the request rather than spawning a competing thread. The next queued action is dispatched after the current action's callback has been processed on the main thread (or immediately after the action completes if no callback was provided). Actions targeting different objects execute in parallel as independent workers. Any actions submitted during callback execution — including actions targeting the same object — are appended to the tail of the queue and do not preempt previously queued work.

Execution proceeds in two phases per action. During the 'worker phase', the worker thread holds an exclusive lock on the object and executes the action. On completion, ownership transfers directly to the main thread for the 'callback phase'. At no point between worker completion and callback return is the object available to another worker. Only after the callback returns does the next queued action begin.

Callbacks are processed when the main thread makes a call to ProcessMessages(), so as to maintain an orderly execution process within the application. It is crucial that the target object is not destroyed while actions are executing or queued. Use the Callback routine to receive notification of each action's completion. If an object is freed while actions are still queued, the remaining callbacks will be invoked with an ERR::DoesNotExist error and a NULL object pointer.

The 'Error' parameter in the callback reflects the error code returned by the action after it has been called. Note that if AsyncAction() fails, the callback will never be executed because the attempt will have been aborted.

This function is at its most effective when used to perform lengthy processes such as the loading and parsing of data.

NOTE: Tiri scripts must use the async.action|method() interfaces for asynchronous activity instead of this function.

Error Codes

AsyncCancel()

Drain the pending queue for listed objects without executing the remaining actions.

Call AsyncCancel() to cancel all pending asynchronous actions for the listed objects. Each object's currently active async thread (if any) is interrupted via WakeThread() with Stop set to true, and the remaining action queue is drained without execution.

Callbacks for queued actions will receive ERR::DoesNotExist to indicate cancellation.

Error Codes

AsyncPending()

Return the number of queued and in-flight async actions for an object.

Call AsyncPending() to query the total number of asynchronous actions that are either currently executing or waiting in the queue for a given object. The returned count includes the in-flight action (if any) plus all queued actions that have not yet been dispatched.

A return value of zero indicates that no async activity is associated with the object.

Result

The number of pending async actions (in-flight + queued), or zero if none.

AsyncWait()

Block until all queued async actions for the listed objects have completed.

Call AsyncWait() to suspend the current thread until every asynchronous action that is executing or queued against the listed objects has finished. Messages continue to be processed while waiting, so async completion callbacks fire normally.

Only one AsyncWait() call may be active at any time. If a second call is made while the first is still blocking, ERR::InUse is returned.

Error Codes

BroadcastEvent()

Broadcast an event to all event listeners in the system.

Use BroadcastEvent() to broadcast an event to all listeners for that event in the system. An event structure is required that must start with a 64-bit EventID acquired from GetEventID(), followed by any required data that is relevant to that event. Here are some examples:

typedef struct { EVENTID EventID; char Name[1]; } evVolumeCreated;
typedef struct { EVENTID EventID; OBJECTID TaskID; } evTaskCreated;
typedef struct { EVENTID EventID; OBJECTID TaskID; OBJECTID ProcessID; } evTaskRemoved;

Error Codes

CheckAction()

Checks objects to see whether or not they support certain actions.

This function returns ERR::True if an object's class supports a given action ID. For example:

if (CheckAction(pic, AC::Query) IS ERR::True) {
   // The Query action is supported.
}

Error Codes

CheckResourceExists()

Verifies the existence of a resource.

CheckResourceExists() verifies whether a resource with the specified identifier still exists in the system's object or resource registry. This function is useful for defensive programming when working with resources such as memory or objects that may have been freed by other code paths. Objects that are terminating or awaiting deferred collection are reported as unavailable.

Error Codes

ClassDatabase()

Returns an array of all classes known to the system.

Call ClassDatabase() to obtain an array of all classes known to the system.

Error Codes

CompareFilePaths()

Checks if two file paths refer to the same physical file.

This function will test two file paths, checking if they refer to the same file in a storage device. It uses a string comparison on the resolved path names, then attempts a second test based on an in-depth analysis of file attributes if the string comparison fails. In the event of a match, ERR::Okay is returned. All other error codes indicate a mis-match or internal failure.

The targeted paths do not have to refer to an existing file or folder in order to match (i.e. match on string comparison succeeds).

Error Codes

CopyFile()

Makes copies of folders and files.

This function is used to copy files and folders to new locations. When copying folders it will do so recursively, so as to copy all sub-folders and files within the location.

It is important that you are aware that different types of string formatting can give different results. The following examples illustrate:

Copying kotuku:makefile to kotuku:documents results in a file called kotuku:documents.

Copying kotuku:makefile to kotuku:documents/ results in a file called kotuku:documents/makefile.

Copying kotuku:images/ to kotuku:documents/ results in a folder at kotuku:documents/images and includes a copy of all folders and files found within the images folder.

Copying kotuku:images/ to kotuku:documents results in a folder at kotuku:documents (if the documents folder already exists, it receives additional content from the images folder).

This function will overwrite any destination file(s) that already exist.

The Source parameter should always clarify the type of location that is being copied. For example if copying a folder, a forward slash must terminate the string or it will be assumed that a file is the source.

The Callback parameter can be set with a function that matches this prototype:

INT Callback(FileFeedback *)

For each file that is processed during the copy operation, a &FileFeedback structure is passed that describes the source file and its target. The callback must return a constant value that can potentially affect file processing. Valid values are FFR::Okay (copy the file), FFR::Skip (do not copy the file) and FFR::Abort (abort the process completely and return ERR::Cancelled as an error code).

Error Codes

CreateFolder()

Makes new folders.

This function creates new folders. You are required to specify the full path of the new folder. Standard permission flags can be passed to determine the new permissions to set against the newly created Dir(s). If no permission flags are passed, only the current user will have access to the new folder (assuming that the file system supports security settings on the given media). This function will create multiple folders if the complete path does not exist at the time of the call.

On Unix systems you can define the owner and group ID's for the new folder by calling the SetDefaultPermissions() function prior to CreateFolder().

Error Codes

CreateLink()

Creates symbolic links on supported file systems.

Use the CreateLink() function to create symbolic links on supported file systems. The link connects a new file created at From to an existing file referenced at To. The To link is allowed to be relative to the From location - for instance, you can link documents:myfiles/newlink.txt to ../readme.txt or folder/readme.txt. The .. path component must be used when making references to parent folders.

The permission flags for the link are inherited from the file that you are linking to. If the file location referenced at From already exists as a file or folder, the function will fail with an ERR::FileExists error code.

This function does not automatically create folders in circumstances where new folders are required to complete the From link. You will need to call CreateFolder() to ensure that the necessary paths exist beforehand. If the file referenced at To does not exist, the link will be created without error, but any attempts to open the link will fail until the target file or folder exists.

Error Codes

CurrentContext()

Returns a pointer to the object that has the current context.

This function returns a pointer to the object that has the current context. Context is primarily used to manage resource allocations. Manipulating the context is sometimes necessary to ensure that a resource is tracked to the correct object.

To get the context of the caller (the client), use ParentContext().

Result

Returns an object pointer (of which the process has exclusive access to). Cannot return NULL except in the initial start-up and late shut-down sequence of the Core.

CurrentTask()

Returns the active Task object.

This function returns the Task object of the active process.

If there is a legitimate circumstance where there is no current task (e.g. if this function is called during Core initialisation) then the "system task" may be returned, which has ownership of Core resources.

Result

Returns a pointer to the current Task object or NULL if failure.

DeleteFile()

Deletes files and folders.

This function will delete a file or folder when given a valid file location. The current user must have delete access to the given file. When deleting folders, all content will be scanned and deleted recursively. Individual deletion failures are ignored, although an error will be returned if the top-level folder still contains content on its deletion.

This function does not allow for the approximation of file names. To approximate a file location, open it as a File object or use ResolvePath() first.

The Callback parameter can be set with a function that matches the prototype INT Callback(*FileFeedback).

Prior to the deletion of any file, a FileFeedback structure is passed that describes the file's location. The callback must return a constant value that can potentially affect file processing. Valid values are FFR::Okay (delete the file), FFR::Skip (do not delete the file) and FFR::Abort (abort the process completely and return ERR::Cancelled as an error code).

Error Codes

DeleteVolume()

Deletes volumes from the system.

This function deletes volume names from the system. Once a volume is deleted, any further references to it will result in errors unless the volume is recreated.

Error Codes

FieldName()

Resolves a field ID to its registered name.

Resolves a field identifier to its name by checking the internal dictionary. The field must have previously been referenced by a class blueprint in order for its name to be registered.

If FieldID is not registered, the value is returned as a printable hex string.

Result

The name of the field is returned.

FindClass()

Returns the internal MetaClass for a given class ID.

This function will find a specific class by ID and return its MetaClass. If the class is not already loaded, the internal dictionary is checked to discover a module binary registered with that ID. If this succeeds, the module is loaded into memory and the correct MetaClass will be returned.

In any event of failure, NULL is returned.

If the ID of a named class is not known, call ResolveClassName() first and pass the resulting ID to this function.

NOTE: To retrieve a list of all derived classes associated with a base-class, read the SubClasses field of the MetaClass.

Result

Returns a pointer to the MetaClass structure that has been found as a result of the search, or NULL if no matching class was found.

FindField()

Finds field descriptors for any class, by ID.

The FindField() function checks if an object supports a specified field by scanning its class descriptor for a FieldID. If a matching field is declared, its descriptor is returned. For example:

if (auto field = FindField(Display, strhash("width"), nullptr)) {
   log.msg("The field name is \"%s\".", field->Name);
}

The resulting Field structure is immutable.

Note: To lookup the field definition of a MetaClass, use the MetaClass⇒FindField() method.

Result

Returns a pointer to the Field descriptor, otherwise NULL if not found.

FindObject()

Searches for objects by name.

The FindObject() function searches for all objects that match a given name and can filter by class.

The following example illustrates typical usage, and finds the most recent object created with a given name:

OBJECTID id;
FindObject("SystemPointer", CLASSID::POINTER, &id);

If FindObject() cannot find any matching objects then it will return an error code.

Error Codes

FreeObject()

Terminates an object by its unique identifier.

FreeObject() starts the destruction process for the object identified by ObjectID. If the object is locked or strongly pinned, destruction is deferred until the final lock or pin is released. Once termination has started, new access through AccessObject() is rejected.

Error Codes

FreeResource()

Safely deallocates resources allocated by AllocResource() and similar functions.

FreeResource() provides safe deallocation of resources with comprehensive validation and cleanup. The function accepts resource identifiers for optimal safety, though C++ headers also provide pointer-based variants for convenience.

Object identifiers are detected in the object registry and dispatched to FreeObject(). All other identifiers are resolved through the non-object resource registry and its associated ResourceManager.

The deallocation process includes lock-aware deallocation that respects access counting, resource manager integration for managed memory blocks, and automatic cleanup of ownership tracking structures.

If a resource is pinned at the time of the call, it is marked for delayed collection. The final UnpinResource() performs the deferred destruction and returns the resource manager's result.

Error Codes

GenCRC32()

Generates 32-bit IEEE 802.3 CRC checksum values.

This function is used internally for the generation of 32-bit CRC checksums compatible with IEEE 802.3. It is made available to clients to generate CRC values over any length of buffer space. This function may be called repeatedly by feeding it CRC values in a cycle, making it ideal for processing streamed data.

Note that string hashes in Kotuku use CRC-32C, which is incompatible with this function.

Result

Returns the computed 32 bit CRC value for the given data.

GetActionMsg()

Returns a message structure if called from an action that was executed by the message system.

This function is for use by action and method support routines only. It will return a Message structure if the action currently under execution has been called directly from the ProcessMessages() function. In all other cases a NULL pointer is returned.

Only works when called from the main thread, which acts as the message dispatcher.

Result

A Message structure is returned if the function is called in valid circumstances, otherwise NULL.

GetClassID()

Returns the class ID of an ID-referenced object.

Call this function with any valid object ID to learn the identifier for its base class. This is the quickest way to retrieve the class of an object without having to gain exclusive access to the object first.

Note that if the object's pointer is already known, the quickest way to learn of its class is to call the classID() C++ method.

Result

Returns the base class ID of the object or zero if failure.

GetErrorMsg()

Translates error codes into human readable strings.

The GetErrorMsg() function converts error codes into human readable strings. If the Error is invalid, a string of "Unknown error code" is returned.

Result

A human readable string for the error code is returned. By default error codes are returned in English, however if a translation table exists for the user's own language, the string will be translated.

GetEventID()

Generates unique event ID's suitable for event broadcasting.

Use GetEventID() to generate a 64-bit event identifier. This identifier can be used for broadcasting and subscribing to events. Events are described in three parts - Group, SubGroup and the Event name, or in string format group.subgroup.event.

The Group is strictly limited to one of the following definitions:

The SubGroup and Event parameters are string-based and there are no restrictions on naming. If a SubGroup or Event name is NULL, this will act as a wildcard for subscribing to multiple events. For example, subscribing to the network group with SubGroup and Event set to NULL will allow for a subscription to all network events that are broadcast. A Group setting of zero is not allowed.

Result

The event ID is returned as a 64-bit integer.

GetObjectPtr()

Returns a direct pointer for any object ID.

This function translates an object ID to its respective address pointer.

Result

The address of the object is returned, or NULL if the ID does not relate to an object.

GetOwnerID()

Returns the unique ID of an object's owner.

This function returns an identifier for the owner of any valid object. This is the fastest way to retrieve the owner of an object if only the ID is known.

If the object address is already known, use the ownerID() C++ class method instead of this function.

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 provided ID is invalid, this function will return 0.

GetResource()

Retrieves miscellaneous resource identifiers.

The GetResource() function is used to retrieve miscellaneous resource and state information from the system core. Refer to the Resource identifier for the full list of available resource codes and their meaning.

C++ developers should use the GetResourcePtr() macro if a resource identifier is known to return a pointer.

Result

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

GetSystemState()

Returns miscellaneous data values from the Core.

The GetSystemState() function is used to retrieve miscellaneous resource and environment values, such as resource paths, the Core's version number and the name of the host platform.

The state values in the structure are static and will not change during runtime.

Result

A read-only SystemState structure is returned.

GetThreadID()

Returns the UID of the current thread.

Returns a unique ID for the active thread. The ID has no relationship with the host operating system and is not re-used.

Result

A unique ID for the active thread is returned.

IdentifyFile()

Analyse a file and identify a class that can process it.

This function examines the relationship between file data and Kōtuku classes. For instance, a JPEG file would be identified as a datatype of the Image class. An MP3 file would be identified as a datatype of the Sound class.

The method involves analysing the Path's file extension and comparing it to the supported extensions of all available classes. If a class supports the file extension, the ID of that class will be returned. If the file extension is not listed in the class dictionary or if it is listed more than once, the first 80 bytes of the file's data will be loaded and checked against classes that can match against file header information. If a match is found, the ID of the matching class will be returned.

The ERR::Search code is returned if a suitable class does not match the targeted file.

Error Codes

InitObject()

Initialises an object so that it is ready for use.

This function initialises objects so that they can be used for their intended purpose. Initialisation is compulsory, and a client may not call any actions or methods on an object until it has been initialised. Exceptions to this rule only apply to the GetKey() and SetKey() actions.

If the initialisation of an object fails due to a support problem (for example, if a PNG Image object attempts to load a JPEG file), the initialiser will search for a derived class that can handle the data. If a derived class that can support the object's configuration is available, the object's interface will be shared between both the base-class and the derived class.

If an object does not support the data or its configuration, an error code of ERR::NoSupport will be returned. Other appropriate error codes can be returned if initialisation fails.

Error Codes

ListChildren()

Returns a list of all children belonging to an object.

The ListChildren() function returns a list of all children belonging to an object. The client must provide an empty vector of ChildEntry structures to host the results, which include unique object ID's and their class identifiers.

Note that any child objects marked with the LOCAL flag will be excluded because they are private members of the targeted object.

Error Codes

LoadFile()

Loads files into a local cache for fast file processing.

The LoadFile() function loads complete files into memory and caches the content for use by other areas of the system or application.

If the requested file has already been cached, the CacheFile structure is returned immediately. Note that if the file was previously cached but then modified, this will be treated as a cache miss and the file will be loaded into a new buffer.

File content will be loaded into a readable memory buffer that is referenced by the Data field of the CacheFile structure. A hidden null byte is appended at the end of the buffer to assist the processing of text files. Other pieces of information about the file can be derived from the CacheFile meta data.

Calls to LoadFile() must be matched with a call to UnloadFile() to decrement the cache counter. When the counter returns to zero, the file can be unloaded from the cache during the next resource collection phase.

Error Codes

LockObject()

Lock an object to prevent contention between threads.

Use LockObject() to gain exclusive access to an object at thread-level. This function provides identical behaviour to that of AccessObject(), but with a slight speed advantage as the object ID does not need to be resolved to an address. Calls to LockObject() will nest, and must be matched with a call to ReleaseObject() to unlock the object.

Be aware that while this function is faster than AccessObject(), it is unsafe if other threads could terminate the object without a suitable barrier in place.

If it is guaranteed that an object is not being shared between threads, object locking is unnecessary.

Error Codes

MoveFile()

Moves folders and files to new locations.

This function is used to move files and folders to new locations. It can also be used for renaming purposes and is able to move data from one type of media to another. When moving folders, any contents within the folder will also be moved across to the new location.

It is important that you are aware that different types of string formatting can give different results. The following examples illustrate:

Source               Destination          Result
kotuku:makefile     kotuku:documents    kotuku:documents
kotuku:makefile     kotuku:documents/   kotuku:documents/makefile
kotuku:images/      kotuku:documents/   kotuku:documents/images
kotuku:images/      kotuku:documents    kotuku:documents (Existing documents folder destroyed)

This function will overwrite the destination location if it already exists.

The Source argument should always clarify the type of location that is being copied - e.g. if you are copying a folder, you must specify a forward slash at the end of the string or the function will assume that you are moving a file.

The Callback parameter can be set with a function that matches this prototype:

INT Callback(*FileFeedback)

For each file that is processed during the move operation, a FileFeedback structure is passed that describes the source file and its target. The callback must return a constant value that can potentially affect file processing. Valid values are FFR::Okay (move the file), FFR::Skip (do not move the file) and FFR::Abort (abort the process completely and return ERR::Cancelled as an error code).

Error Codes

NewObject()

Creates new objects.

The NewObject() function is used to create new objects and register them for use within the Core. After creating a new object, the client can proceed to set the object's field values and initialise it with Init so that it can be used as intended.

The new object will be modeled according to the class blueprint indicated by ClassID. Pre-defined class ID's are defined in their documentation and the kotuku/system/register.h include file. ID's for unregistered classes can be computed using the ResolveClassName() function.

A pointer to the new object will be returned in the Object parameter. By default, object allocations are context sensitive and will be collected when their owner is terminated. It is possible to track an object to a different owner by using the SetOwner() function.

To destroy an object, call FreeResource().

Error Codes

NotifySubscribers()

Send a notification event to action subscribers.

This function can be used by classes that need fine-tuned control over notification events, as managed by the SubscribeAction() function. Normally the Core will automatically notify subscribers after an action is executed. Using NotifySubscribers(), the client can instead manually notify subscribers during the execution of the action.

Another useful aspect is that the client can control the parameter values that are passed on to the subscribers.

NOTE: The use of NotifySubscribers() does not prevent the core from sending out an action notification as it normally would, which will cause duplication. To prevent this, the client must logical-or the return code of the action function with ERR::Notified, e.g. ERR::Okay|ERR::Notified.

In the following example the Surface class uses NotifySubscribers() to convert a Move event to a Redimension event. The parameter values are customised to support this, and the function returns ERR::Notified to prevent the core from sending out a Move notification.

ERR SURFACE_Move(extSurface *Self, struct acMove *Args)
{
   if (not Args) return ERR::NullArgs|ERR::Notified;

   ...

   struct acRedimension redimension = { Self->X, Self->Y, 0, Self->Width, Self->Height, 0 };
   NotifySubscribers(Self, AC::Redimension, &redimension, ERR::Okay);
   return ERR::Okay|ERR::Notified;
}

OpenDir()

Opens a folder for content scanning.

The OpenDir() function is used to open a folder for scanning via the ScanDir() function. If the provided Path can be accessed, a DirInfo structure will be returned in the Info parameter, which will need to be passed to ScanDir(). Once the scanning process is complete, call the FreeResource() function.

When opening a folder, it is necessary to indicate the type of files that are of interest. If no flags are defined, the scanner will return file and folder names only. Only a subset of the available RDF flags may be used, specifically SIZE, DATE, PERMISSIONS, FILE, FOLDER, QUALIFY, TAGS.

Error Codes

ParentContext()

Returns the context of the client.

This function is used to return the context of the caller (the client), as opposed to CurrentContext(), which returns the operating context. This feature is commonly used by methods that need to acquire a reference to the client for resource management reasons.

Note that this function can return NULL if called when running at process-level, although this would never be the case when called from an action or method.

Result

An object reference is returned, or NULL if there is no parent context.

PinResource()

Protects a resource from termination until a matching unpin.

PinResource() acquires a lifetime pin for a tracked non-object resource. Multiple callers may pin the same resource, but pinning does not serialise access to its contents or make mutation thread-safe. A successful pin prevents FreeResource() and the resource manager from releasing the resource until every acquired pin has been released with UnpinResource().

Error Codes

PreciseTime()

Returns the current system time, in microseconds.

This function returns the current 'system time' in microseconds (1 millionth of a second). The value is monotonic if the host platform allows it (typically expressed as the amount of time that has elapsed since the system was switched on). The benefit of monotonic time is that it is unaffected by changes to the system clock, such as daylight savings adjustments or manual changes by the user.

Result

Returns the system time in microseconds. Could return zero in the extremely unlikely event of an error.

ProcessMessages()

Processes system messages that are queued in the task's message buffer.

The ProcessMessages() function is used to process the task's message queue. Messages are dispatched to message handlers in the order in which they arrived and the queue is emptied so that space is available for more messages.

Responding to incoming messages is a vital process - the queue is the standard means of communication between your task and 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. If an area of your program is likely to loop continuously for a measurable period of time without returning, consider calling ProcessMessages() at a rate of 50 times per second to ensure that incoming messages are processed.

User messages that are on the queue are passed to message handlers. If no message handler exists to interpret the message, then it is removed from the queue without being processed. Message handlers are added with the AddMsgHandler() function. If a message handler returns the error code ERR::Terminate, then ProcessMessages() will stop processing the queue and returns immediately with ERR::Okay.

If a message with a MSGID::QUIT ID is found on the queue, then the function returns immediately with the error code ERR::Terminate. The program must respond to the terminate request by exiting immediately.

Error Codes

QueueAction()

Delay the execution of an action by adding the call to the message queue.

Use QueueAction() to execute an action by way of the local message queue. This means that the supplied Action and Args will be serialised into a message for the queue. This function then returns immediately.

The action will be executed on the next cycle of ProcessMessages() in line with the FIFO order of queued messages.

Error Codes

ReadFileToBuffer()

Reads a file into a buffer.

This function provides a simple method for reading file content into a Buffer. In some cases this procedure may be optimised for the host platform, which makes it the fastest way to read file content in simple cases.

File path approximation is supported if the Path is prefixed with a ~ character (e.g. ~images:photo could be matched to photo.jpg in the same folder).

Error Codes

ReadInfoTag()

Read a named tag from a FileInfo structure.

ReadInfoTag() will read the value of a named tag in a FileInfo structure. The tag must have been added with AddInfoTag() or ERR::NotFound will be returned.

Error Codes

RegisterFD()

Registers a file descriptor for monitoring when the task is asleep.

This function will register a file descriptor that will be monitored for activity when the task is sleeping. When activity occurs on the descriptor, the callback referenced in Routine will be called. The callback should read all information from the descriptor, as the process will not be able to sleep if data is back-logged.

The file descriptor should be configured as non-blocking before registration. Blocking descriptors may cause the program to hang if not handled carefully.

File descriptors support read and write states simultaneously, and a callback routine can be applied to either state. Set the RFD::READ flag to apply the Routine to the read callback and RFD::WRITE for the write callback. If neither flag is specified, RFD::READ is assumed. A file descriptor may have up to one subscription per flag, for example a read callback can be registered, followed by a write callback in a second call. Individual callbacks can be removed by combining the read/write flags with RFD::REMOVE.

The capabilities of this function and FD handling in general is developed to suit the host platform. On POSIX compliant systems, standard file descriptors are used. In Microsoft Windows, object handles are used and blocking restrictions are not imposed.

Call the DeregisterFD() macro to simplify unsubscribing once the file descriptor is no longer needed or is destroyed.

Error Codes

ReleaseObject()

Release a locked object.

Release a lock previously obtained from AccessObject() or LockObject(). Locks will nest, so a release is required for every lock that has been granted.

ResolveClassID()

Resolve a valid CLASSID to its name.

This function will resolve a valid class ID to its equivalent name. The name is resolved by checking the class database, so the class must be registered in the database for this function to return successfully.

Registration is achieved by ensuring that the class is compiled into the build.

Result

Returns the name of the class, or NULL if the ID is not recognised. Standard naming conventions apply, so it can be expected that the string is capitalised and without spaces, e.g. NetSocket.

ResolveClassName()

Resolves any class name to a CLASSID UID.

This function will resolve a class Name to its CLASSID UID and verifies that the class is installed. Class names are case insensitive.

Result

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

ResolveGroupID()

Converts a group ID to its corresponding name.

This function converts group ID's obtained from the file system into their corresponding names. If the Group ID is invalid then NULL will be returned.

Result

The group name is returned, or NULL if the ID cannot be resolved.

ResolvePath()

Converts volume-based paths into absolute paths applicable to the host platform.

This function will convert a file path to its resolved form, according to the host system. For example, a Linux system might resolve drive1:documents/readme.txt to /documents/readme.txt. A Windows system might resolve the path to c:\documents\readme.txt.

The resulting path is guaranteed to be absolute, meaning the use of sequences such as .., // and ./ will be eliminated.

If the path can be resolved to more than one file, ResolvePath() will attempt to discover the correct path by checking the validity of each possible location. For instance, if resolving a path of user:document.txt and the user: volume refers to both system:users/joebloggs/ and system:users/default/, the routine will check both directories for the existence of the document.txt file to determine the correct location. This approach can be problematic if the intent is to create a new file, in which case RSF::NO_FILE_CHECK will circumvent it.

When checking the file location, ResolvePath() requires an exact match to the provided file name. If the file name can be approximated (i.e. the file extension can be ignored) then use the RSF::APPROXIMATE flag.

To resolve the location of executable programs on Unix systems, use the RSF::PATH flag. This uses the PATH environment variable to resolve the file name specified in the Path parameter.

The resolved path will be copied to the string provided in the Result parameter. This will overwrite any existing content in the string.

If the path resolves to a virtual drive, it may not be possible to confirm whether the target file exists if the virtual driver does not support this check. This is common when working with network drives.

Error Codes

ResolveUserID()

Converts a user ID to its corresponding name.

This function converts user ID's obtained from the file system into their corresponding names. If the User ID is invalid then NULL will be returned.

Result

The user name is returned, or NULL if the ID cannot be resolved.

ScanDir()

Scans the content of a folder, by item.

The ScanDir() function is used to scan for files and folders in a folder that you have opened using the OpenDir() function. The ScanDir() function is intended to be used in a simple loop, returning a single item for each function call that you make. The following code sample illustrates typical usage:

DirInfo *info;
if (not OpenDir(path, RDF::FILE|RDF::FOLDER, &info)) {
   while (not ScanDir(info)) {
      log.msg("File: %s", info->Name);
   }
   FreeResource(info);
}

For each item that you scan, you will be able to read the Info structure for information on that item. The DirInfo structure contains a FileInfo pointer that consists of the following fields:

The RDF flags that may be returned in the Flags field are VOLUME, FOLDER, FILE, LINK.

Error Codes

ScanMessages()

Scans a message queue for multiple occurrences of a message type.

Use the ScanMessages() function to scan the local message queue for information without affecting the state of the queue. To use this function effectively, make repeated calls to ScanMessages() to analyse the queue until it returns an error code other than ERR::Okay.

The following example illustrates a scan for MSGID::QUIT messages:

while (!ScanMessages(&handle, MSGID::QUIT, {})) {
   ...
}

Messages will often (but not always) carry data that is relevant to the message type. To retrieve this data a buffer must be supplied. If the Buffer is too small, the message data will be trimmed to fit without any further indication.

Error Codes

SendMessage()

Add a message to the local message queue.

The SendMessage() function will add a message to the end of the local message queue. Messages must be associated with a Type identifier and this can help the receiver process any accompanying Data. Some common message types are pre-defined, such as MSGID::QUIT. Custom messages should use a unique type ID obtained from AllocateID().

Error Codes

SetDefaultPermissions()

Forces the user and group permissions to be applied to new files and folders.

By default, user, group and permission information for new files is inherited either from the system defaults or from the file source in copy operations. Use this function to override this behaviour with new default values. All threads of the process will be affected.

To revert behaviour to the default settings, set the User and/or Group values to -1 and the Permissions value to zero.

SetLogCallback()

Register a callback for log messages.

This function registers Callback to observe log messages while logging is active. The callback must use the LOG_CALLBACK signature:

void Callback(CSTRING Header, CSTRING Message, INT Depth, INT MsgLevel, INT LogLevel)

The Header argument identifies the origin of the message. When the caller did not supply a header, Core derives one from the current action, method or application context. The Message argument contains the formatted log text. The header and message pointers are valid only for the duration of the callback call, so a callback must copy either string if it needs to retain it. Depth is the current branch depth, MsgLevel is the severity or detail level assigned to the message, and LogLevel is the effective active log level after baseline adjustment.

The DepthLimit and LogLimit parameters are used to reduce log noise. DepthLimit suppresses callbacks when the current branch depth is greater than the limit, and LogLimit suppresses callbacks when the message level is greater than the limit. Use a suitably large limit to receive all messages for that filter. Messages emitted from inside a log callback are not forwarded recursively to log callbacks on the same thread.

Passing NULL for Callback has no effect. Registering the same callback address again updates its DepthLimit and LogLimit values. Passing zero for both limits unregisters a matching callback if it exists. The number of unique callbacks that can be registered is limited; when all callback slots are in use, additional registrations are ignored.

SetName()

Sets the name of an object.

This function sets the name of an Object. This enhances log messages and allows the object to be found in searches. Note that the length of the Name will be limited to the MAX_NAME_LEN value in the core header file. Names exceeding the allowed length are trimmed to fit.

Object names are limited to alpha-numeric characters and the underscore symbol. Invalid characters are replaced with an underscore.

Error Codes

SetOwner()

Changes object ownership dynamically.

This function changes the ownership of an existing object. Ownership is an attribute that affects an object's placement within the object 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's class will receive notification via the NewChild action. If the owner rejects the object by sending back an error, SetOwner() will fail immediately.
2. The object's class will then receive notification via the 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 ownership management.

Error Codes

SetResource()

Updates a writable Core resource value.

SetResource() updates Core state selected by a RES identifier. The following identifiers are writable:

• LOG_LEVEL sets the logging detail from 0 (disabled) to 9 (maximum detail). Values outside this range are ignored.
• LOG_DEPTH sets the logging branch depth for the current thread. This controls indentation of subsequent log output.
• PRIVILEGED_USER enables elevated Unix privileges when Value is non-zero and releases one level of privilege when it is zero. Elevation is available only when the process was launched with suitable privileges. Calls may be nested; privileges are released after the corresponding number of disable requests. On non-Unix platforms this identifier has no effect.
• WINDOWS_ICON sets the Microsoft Windows resource icon ID for the process.
• CONSOLE_FD and JNI_ENV update internal host integration values.

Other RES identifiers are read-only or unsupported by this function.

For PRIVILEGED_USER, the result is an ERR value indicating whether the request succeeded. All other supported resources return 0. Unsupported identifiers also return 0 after writing a warning to the log.

Result

Result code is dependent on the targeted resource.

SetResourcePath()

Redefines the location of a system resource path.

The SetResourcePath() function changes the default locations of the Core's resource paths.

To read a resource path, use the GetSystemState() function.

Error Codes

SetVolume()

Create or modify a filesystem volume.

SetVolume() is used to create or modify a volume that is associated with one or more paths. If the named volume already exists, it possible to append more paths or replace them entirely. Volume changes that are made with this function will only apply to the current process, and are lost after the program closes.

Flags that may be passed are as follows:

Error Codes

SubscribeAction()

Monitor action calls made against an object.

The SubscribeAction() function allows a client to receive a callback each time that an action is executed on an object. This strategy is referred to as "action monitoring" and is often used for responding to UI events and the termination of objects.

Subscriptions are context sensitive, so the Callback will execute in the space attributed to to the caller.

The following example illustrates how to listen to a Surface object's Redimension action and respond to resize events:

SubscribeAction(surface, AC::Redimension, C_FUNCTION(notify_resize, meta_ptr));

The template below illustrates how the Callback function should be constructed:

void notify_resize(OBJECTPTR Object, ACTIONID Action, ERR Result, APTR Parameters, APTR CallbackMeta)
{
   auto Self = (objClassType *)CurrentContext();

   // Code here...
   if ((!Result) and (Parameters)) {
      auto resize = (struct acRedimension *)Parameters;
   }
}

The Object is the original subscription target, as-is the Action ID. The Result is the error code that was generated at the end of the action call. If this is not set to ERR::Okay, assume that the action did not have an effect on state. The Parameters are the original arguments provided by the client - be aware that these can legitimately be NULL even if an action specifies a required parameter structure. Notice that because subscriptions are context sensitive, CurrentContext() can be used to get a reference to the object that initiated the subscription.

To terminate an action subscription, use the UnsubscribeAction() function. Matching each subscription with an unsubscription remains good practice because it releases the subscription record immediately. If a subscriber is freed without unsubscribing, the record degrades safely: the subscriber's object header is weakly pinned for the lifetime of the record, dispatch recognises the freed subscriber and skips the callback, and the stale record is swept once the notification pass completes. Until that sweep occurs, the subscriber's header remains allocated in zombie form.

Error Codes

SubscribeEvent()

Subscribe to a system event.

Use the SubscribeEvent() function to listen for system events. An event ID (obtainable from GetEventID()) must be provided, as well as a reference to a function that will be called each time that the event is broadcast.

An event handle will be returned in the Handle parameter to identify the subscription. This must be retained to later unsubscribe from the event with the UnsubscribeEvent() function.

The prototype for the Callback function is Function(APTR Event, LONG Size, APTR CallbackMeta), where Event is the event structure that matches to the subscribed EventID.

Error Codes

SubscribeTimer()

Subscribes an object or function to the timer service.

This function creates a new timer subscription that will be called at regular intervals for the calling object.

A callback function must be provided that follows this prototype: ERR Function(OBJECTPTR Subscriber, INT64 Elapsed, INT64 CurrentTime)

The Elapsed parameter is the total number of microseconds that have elapsed since the last call. The CurrentTime parameter is set to the PreciseTime() value just prior to the Callback being called. The callback function can return ERR::Terminate at any time to cancel the subscription. All other error codes are ignored. Tiri callbacks should use raise ERR_Terminate to perform the equivalent of this behaviour.

To change the interval, call UpdateTimer() with the new value. To release a timer subscription, call UpdateTimer() with the resulting Subscription handle and an Interval of zero.

Timer management is provisioned by the ProcessMessages() function. Failure to regularly process incoming messages will lead to unreliable timer cycles. It should be noted that the smaller the Interval that has been used, the more imperative regular message checking becomes. Prolonged processing inside a timer routine can also impact on other timer subscriptions that are waiting to be processed.

Error Codes

TrackResource()

Assign a resource manager to an address, or update an existing one.

TrackResource() registers a resource identifier with the memory manager so that later calls to FreeResource() can dispatch cleanup through the supplied ResourceManager. If the resource identifier is already registered, the existing record is updated with the non-zero values provided by the caller.

The supplied address and manager are retained as references only. They must remain valid for as long as the resource is tracked, or until the record is replaced or removed. When an OwnerID names an object, the resource is added directly to that object's resource list so it can be removed during object cleanup. Use RESOURCEID_INHERIT to preserve the existing owner when updating a resource, or to inherit the current context when registering a new resource.

A unique ResourceID can be obtained from AllocateID() by using IDTYPE::RESOURCE.

Error Codes

UnloadFile()

Unloads files from the file cache.

This function unloads cached files that have been previously loaded with the LoadFile() function.

UnpinResource()

Releases a lifetime pin from a resource.

UnpinResource() releases one pin previously acquired with PinResource(). If FreeResource() requested collection while the resource was pinned, the caller releasing the final pin performs the deferred manager call and receives its result. A failed deferred collection restores the resource to a live, retryable state.

Error Codes

UnsubscribeAction()

Terminates action subscriptions.

The UnsubscribeAction() function will terminate subscriptions made by SubscribeAction(). The removal of subscriptions is context sensitive, so the context of the original SubscribeAction() call must be matched by UnsubscribeAction().

To terminate multiple subscriptions in a single call, set the Action parameter to zero.

Unsubscribing releases the subscription record (and the weak pin it holds on the subscriber) immediately. A subscriber that is freed without unsubscribing is tolerated - its remaining records are swept lazily the next time each subscribed action is dispatched - but explicit unsubscription remains the recommended practice.

Error Codes

UnsubscribeEvent()

Removes an event subscription.

Use UnsubscribeEvent() to remove an existing event subscription. A valid handle returned from the SubscribeEvent() function must be provided.

UpdateMessage()

Updates the data of any message that is queued.

The UpdateMessage() function provides a facility for updating the content of existing messages on the local queue. The client must provide the ID of the message to update and the new message Type and/or Data to set against the message. Non-empty Data replaces the complete existing payload, while an empty buffer leaves that payload unchanged.

Error Codes

UpdateTimer()

Modify or remove a subscription created by SubscribeTimer().

This function complements SubscribeTimer(). It can change the interval for an existing timer subscription, or remove it if the Interval is set to zero.

Error Codes

WaitForObjects()

Process incoming messages while waiting on objects to complete their activities.

WaitForObjects() acts as a front-end to ProcessMessages(), with an ability to wait for a list of objects that are expected to signal an end to their activities. An object can be signalled via the Signal() action, or via termination. By default, this function will only return once ALL of the objects are signalled or a time-out occurs. Use the PMF::ANY_SIGNAL flag to return once ANY of the objects are signalled.

It is guaranteed that the message queue will be consumed by ProcessMessages() at least once before this function returns.

Note that if an object has been signalled prior to entry to this function, its signal flag will be cleared and the object will not be monitored.

If this function is called recursively, the state of the earlier call will be preserved so that it will not be affected by subsequent calls.

Error Codes

WaitTime()

Waits for a specified amount of seconds.

This function waits for a period of time as specified by the Seconds parameter. While waiting, your process will continue to process incoming messages in order to prevent the process' message queue from developing a back-log.

WaitTime() can return earlier than the indicated timeout if a message handler returns ERR::Terminate, or if a MSGID::QUIT message is sent to the task's message queue.

For non-main threads, the sleep can be interrupted by another thread calling WakeThread().

NOTE: If the thread is in a stopping state, e.g. from WakeThread(), this function will return immediately.

Error Codes

WakeThread()

Interrupt a sleeping thread.

Call WakeThread() to interrupt a thread that is blocked in WaitTime() or similar, where supported. The target thread will return from as soon as it is able to acquire its internal lock. If the target thread is not currently sleeping, a pending interrupt is recorded so that its next sleep cycle will return immediately.

If Stop is set to true then the target thread will be put into a stopping state. This will cause all future sleep attempts in the target thread to be cancelled.

Error Codes

AC Type

Action identifiers

CCF Type

Class categories

CONTYPE Type

Console types

EVG Type

Event categories

FBK Type

Flags for file feedback.

IDTYPE Type

Types for AllocateID()

JET Type

JET constants are documented in GetInputEvent()

JTYPE Type

JTYPE flags are used to categorise input types

LDF Type

Flags for LoadFile()

LOC Type

AnalysePath() values

MEM Type

Memory flags

MSF Type

Message flags.

MSGID Type

Reserved message ID's that are handled internally.

NF Type

Flags that can be passed to NewObject(). If a flag needs to be stored with the object, it must be specified in the lower word.

OPF Type

PERMIT Type

Permission flags

PMF Type

Flags for ProcessMessages

RDF Type

Flags for the OpenDir() function.

RES Type

RFD Type

Flags for RegisterFD()

RP Type

Path types for SetResourcePath()

RSF Type

Flags for ResolvePath()

TOI Type

VOLUME Type

Options for SetVolume()

ActionArray Structure

ActionTable Structure

Structure for ActionList

ChildEntry Structure

Structure for ListChildren() function

ClassRecord Structure

Meta information for a class, as recorded in the class database.

ClipRectangle Structure

Generic structure for rectangular clipping.

ColourFormat Structure

DateTime Structure

Generic structure for date-time management

DirInfo Structure

Used by OpenDir() only

Edges Structure

Generic structure for declaring edge coordinates.

FRGB Structure

32-bit floating point RGB colour components.

Field Structure

Used to describe the public fields of a class.

FieldArray Structure

Used to construct class blueprints for the MetaClass.

FieldDef Structure

Used to define constants for field references.

FileFeedback Structure

FileInfo Structure

Metadata for describing a file.

FunctionField Structure

Used by ActionTable and Function structures to declare lists of parameters.

HSV Structure

Colour structure for Hue, Saturation and Value/Light components.

InputEvent Structure

Message Structure

Message header.

ObjectSignal Structure

Required in calls to WaitForObjects().

OpenInfo Structure

Client options for passing to Kotuku on startup

OpenTag Structure

Tags for OpenInfo.Options

RGB16 Structure

16-bit RGB colour value.

RGB32 Structure

32-bit RGB colour value.

RGB8 Structure

8-bit RGB colour value.

RGBPalette Structure

ResourceRecord Structure

Unified resource management record

SystemState Structure

Returned by the GetSystemState() function.

Unit Structure

dcAudio Structure

Data feed structure for Audio

dcDeviceInput Structure

dcKeyEntry Structure

Data feed structure for Keypress

dcRequest Structure

Data feed item request