Functions

Events

BroadcastEvent | GetEventID | SubscribeEvent | UnsubscribeEvent

Fields

FieldName | FindField | GetField | GetFieldArray | GetFieldVariable | SetArray | SetField

Files

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

Memory

AccessMemory | AllocMemory | CheckMemoryExists | FreeResource | MemoryIDInfo | MemoryPtrInfo | ReallocMemory | ReleaseMemory

Messages

AddMsgHandler | GetMessage | ProcessMessages | ScanMessages | SendMessage | UpdateMessage | WaitForObjects

Objects

AccessObject | Action | ActionList | AsyncAction | CheckAction | CheckObjectExists | CurrentContext | FindClass | FindObject | GetActionMsg | GetClassID | GetObjectPtr | GetOwnerID | InitObject | ListChildren | LockObject | NewObject | NotifySubscribers | ParentContext | QueueAction | ReleaseObject | ResolveClassID | ResolveClassName | SetContext | SetName | SetOwner | SubscribeAction | UnsubscribeAction

System

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

Structures

ActionArray | ActionTable | ChildEntry | ClipRectangle | ColourFormat | CompressedItem | CompressionFeedback | DateTime | DirInfo | Edges | FRGB | Field | FieldArray | FieldDef | FileFeedback | FileInfo | Function | FunctionField | HSV | InputEvent | MemInfo | Message | ObjectSignal | RGB16 | RGB32 | RGB8 | RGBPalette | SystemState | Unit | dcAudio | dcDeviceInput | dcKeyEntry | dcRequest

Classes

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

Constants

AC | ALIGN | CCF | CF | CLF | CLIPMODE | CMF | CNF | CON | DATA | DEVICE | DMF | DRL | EDGE | EVG | FBK | FD | FDB | FDL | FDT | FFR | FL | FOF | IDTYPE | JET | JTYPE | KEY | KQ | LAYOUT | LDF | LOC | MAX | MEM | MFF | MHF | MOF | MOVE | MSF | MSGID | MTF | NETMSG | NF | OPF | PERMIT | PMF | PTC | RDF | RES | RFD | RP | RSF | SCF | SEEK | STR | STT | THF | TOI | TSF | TSTATE | VAS | VLF | VOLUME

AccessMemory()

Grants access to memory blocks by identifier.

Call AccessMemory() to resolve a memory ID to its address and acquire a lock so that it is inaccessible to other threads.

Memory blocks should never be locked for extended periods of time. Ensure that all locks are matched with a call to ReleaseMemory() within the same code block.

Error Codes

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:

{
   pf::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 Parasol 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, Picture, NULL);

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(Picture);

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 a pointer to 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.

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_LONG  },
   { NULL, 0 }
};

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

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

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(), you can provide an optional Custom pointer that will have meaning to the handler. 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 Custom, LONG MsgID, LONG MsgType, APTR Message, LONG 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 Fluid, this is best achieved by writing check(errorcode) 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.

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.

Result

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

AllocMemory()

Allocates a new memory block on the heap.

The AllocMemory() function will allocate a new block of memory on the program's heap. The client will need to define the minimum byte Size, optional Flags and a variable to store the resulting Address and/or ID of the memory block. For example:

APTR address;
if (!AllocMemory(1000, MEM::DATA, &address, NULL)) {
   ...
   FreeResource(address);
}

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

Notice that memory allocation can be returned as an address pointer and/or as a unique memory ID. Typically a private address with no ID reference is sufficient.

If the client retrieves both the ID and Address pointer, an internal call will be made to AccessMemory() to lock the memory block. This means that before freeing the memory block the client must call ReleaseMemory() to unlock it. Blocks that are persistently locked will remain in memory until the process 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, achieved by setting the MEM::NO_CLEAR flag.

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. ~pictures: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()

Execute an action in parallel, via a separate thread.

This function follows the same principles of execution as the Action() function, with the difference of executing the action in parallel via a dynamically allocated thread. 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)

It is crucial that the target object is not destroyed while the thread is executing. Use the Callback routine to receive notification of the thread's completion and then free the object if desired. The callback will be processed when the main thread makes a call to ProcessMessages(), so as to maintain an orderly execution process within the application.

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 thread attempt will have been aborted.

Please note that there is some overhead involved when safely initialising and executing a new thread. This function is at its most effective when used to perform lengthy processes such as the loading and parsing of data.

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 or method ID. For example:

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

Error Codes

CheckMemoryExists()

Checks if a memory block still exists.

Use CheckMemoryExists() to confirm if a specific memory block still exists by referencing its ID.

Error Codes

CheckObjectExists()

Checks if a particular object is still available in the system.

The CheckObjectExists() function verifies the presence of any object created by NewObject().

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 parasol:makefile to parasol:documents results in a file called parasol:documents.

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

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

Copying parasol:pictures/ to parasol:documents results in a folder at parasol:documents (if the documents folder already exists, it receives additional content from the pictures 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:

LONG Callback(struct 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 Unix file systems.

Use the CreateLink() function to create symbolic links on Unix 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 LONG Callback(struct 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. For this to work successfully, the field must have been registered with the internal dictionary. This is handled automatically when a new class is added to the system.

If the FieldID is not registered, the value is returned back as a hex string. The inclusion of this feature guarantees that an empty string will never be returned.

Result

The name of the field is returned.

FindClass()

Returns all class objects for a given class ID.

This function will find a specific class by ID and return its MetaClass. If the class is not in memory, 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 class 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.

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, FID_Width, NULL)) {
   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 is a typical illustration of this function's use. It finds the most recent object created with a given name:

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

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

Error Codes

FreeResource()

Frees resources originating from AllocMemory().

This function will free any resource that originates from AllocMemory(), using its ID for identification. C++ headers also include a variant of this function that allows a direct memory pointer to be used as the identifier (however we do recommend the use of IDs to improve memory safety).

In some circumstances the termination of the block will not take place immediately. If the block is locked then it will be marked for deletion and not be collected until the lock count reaches zero.

Crash protection measures are built-in. If the memory header or tail is missing from the block, it is assumed that code has over-written the memory boundaries. All caught errors are reported to the application log and warrant priority attention.

Error Codes

GenCRC32()

Generates 32-bit CRC checksum values.

This function is used internally for the generation of 32-bit CRC checksums. You may use it for your own purposes to generate CRC values over a length of buffer space. This function may be called repeatedly by feeding it previous CRC values, making it ideal for processing streamed data.

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.

The Message structure reflects the contents of a standard GetMessage() call. Of particular interest may be the Time field, which indicates the time-stamp at which the action message was originally sent to the object.

Result

A Message structure is returned if the function is called in valid circumstances, otherwise NULL. The Message structure's fields are described in the GetMessage() function.

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.

GetField()

Retrieves single field values from objects.

The GetField() function is used to read field values from objects in the safest way possible. As long as the requested field exists, the value can most likely be read. It is only imperative that the requested type is compatible with the field value itself.

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

GetField(Object, FID_X|TLONG, &x);
GetField(Object, FID_Y|TLONG, &y);

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 C++ strihash() function. Reserved field ID's are listed in the parasol/system/fields.h include file.

The type of the Result parameter must be OR'd into the Field parameter. When reading a field you must give consideration to the type of the source, in order to prevent a type mismatch from occurring. All numeric types are compatible with each other and strings can also be converted to numeric types automatically. String and pointer types are interchangeable.

Available field types are as follows:

Error Codes

GetFieldArray()

Retrieves array field values from objects.

Use the GetFieldArray() function to read an array field from an object, including the length of that array. This supplements the GetField() function, which does not support returning the array length.

This function returns the array as-is with no provision for type conversion. If the array is null terminated, it is standard practice not to count the null terminator in the total returned by Elements.

To achieve a minimum level of type safety, the anticipated type of array values can be specified by OR'ing a field type with the field identifier, e.g. TLONG or TSTR. If no type is incorporated then a check will not be performed.

Error Codes

GetFieldVariable()

Retrieves field values by converting them into strings.

The GetFieldVariable() function is used to retrieve the value of a field without any advance knowledge of the field's type or details. It also supports some advanced features such as flag name lookups and the retrieval of values from array indexes. Although this function is simple to use, it is the slowest of the field retrieval instructions as it relies on string-based field names and converts all results into a string buffer that you must provide.

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

If the field name refers to a flag or lookup based field type, it is possible to test if a specific flag has been set. This is achieved by specifying a dot immediately after the field name, then the name of the flag or lookup to test. If the test passes, a value of 1 is returned, otherwise 0.

String conversion for flag and lookup based fields is also supported (by default, integer values are returned for these field types when no other test is applied). This feature is enabled by prefixing the field name with a $ symbol. If multiple fields are set, the resulting flags will be separated with the traditional OR symbol |.

If the field name refers to an array, it is possible to index specific values within that array by specifying a dot after the field name, then the index number to lookup.

To check if a string is defined (rather than retrieving the entire string content which can be time consuming), prefix the Field name with a question mark. A value of 1 will be returned in the Buffer if the string has a minimum length of 1 character, otherwise a value of 0 is returned in the Buffer.

Error Codes

GetMessage()

Reads messages from message queues.

The GetMessage() function is used to read messages that have been stored in the local message queue. 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 trimmed to fit.

Message data is written to the supplied buffer with a Message structure, which is immediately followed up with the actual message data.

Error Codes

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 then the fastest means of retrieval is via the ownerID() C++ class method.

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 NULL.

GetResource()

Retrieves miscellaneous resource identifiers.

The GetResource() function is used to retrieve miscellaneous resource 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.

Result

A read-only SystemState structure is returned.

IdentifyFile()

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

This function examines the relationship between file data and Parasol classes. For instance, a JPEG file would be identified as a datatype of the Picture 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 Picture object attempts to load a JPEG file), the initialiser will search for a sub-class that can handle the data. If a sub-class that can support the object's configuration is available, the object's interface will be shared between both the base-class and the sub-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.

This function will first determine if the requested file has already been cached. If this is true then 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

MemoryIDInfo()

Returns information on memory ID's.

This function returns the attributes of a memory block, including the start address, parent object, memory ID, size and flags. The following example illustrates correct use of this function:

MemInfo info;
if (!MemoryIDInfo(memid, &info)) {
   log.msg("Memory block #%d is %d bytes large.", info.MemoryID, info.Size);
}

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

Error Codes

MemoryPtrInfo()

Returns information on memory addresses.

This function can be used to get details on the attributes of a memory block. It will return information on the start address, parent object, memory ID, size and flags of the memory address that you are querying. The following code segment illustrates correct use of this function:

MemInfo info;
if (!MemoryPtrInfo(ptr, &info)) {
   log.msg("Address %p is %d bytes large.", info.Start, info.Size);
}

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

Please note that referencing by a pointer requires a slow reverse-lookup to be employed in this function's search routine. We recommend that calls to this function are avoided unless circumstances absolutely require it.

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
parasol:makefile     parasol:documents    parasol:documents
parasol:makefile     parasol:documents/   parasol:documents/makefile
parasol:pictures/    parasol:documents/   parasol:documents/pictures
parasol:pictures/    parasol:documents    parasol: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:

LONG Callback(struct 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 parasol/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()

Used to send notification messages to action subscribers.

This function can be used by classes that need total control over notification management. It allows an action to notify its subscribers manually, rather than deferring to the system default of notifying on return.

Another useful feature is that parameter values can be customised for the recipients.

NOTE: Calling NotifySubscribers() does nothing to prevent the core from sending out an action notification as it normally would, thus causing 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.

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, namely 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.

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 combined 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. ~pictures: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

ReallocMemory()

Reallocates memory blocks.

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 populated 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.

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 do not apply, except to sockets.

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

Error Codes

ReleaseMemory()

Releases a lock from a memory based resource.

Successful calls to AccessMemory() must be paired with a call to ReleaseMemory() so that the memory can be made available to other processes. Releasing the resource decreases the access count, and if applicable a thread that is in the queue for access may then be able to acquire a lock.

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. It is 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 std::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 (!OpenDir(path, RDF::FILE|RDF::FOLDER, &info)) {
   while (!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, NULL, NULL)) {
   ...
}

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 as indicated by the Size, 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

SetArray()

Used to set array fields in objects.

The SetArray() function is used as an alternative to SetField() for the purpose of writing arrays to objects.

The following code segment illustrates how to write an array to an object field:

LONG array[100];
SetArray(Object, FID_Table|TLONG, array, 100);

An indicator of the type of the elements in the Array must be OR'd into the Field parameter. Available field types are listed in SetField(). Note that the type that you choose must be a match to the type expected for elements in the array.

Error Codes

SetContext()

Sets the nominated owner of new resources.

This function defines the object that has control of the current thread. Once called, all further resource allocations are assigned to that object. This is significant for the automatic collection of memory and object resources. For example:

InitObject(display);
auto ctx = SetContext(display);

   NewObject(CLASSID::BITMAP, &bitmap);
   AllocMemory(1000, MEM::DATA, &memory, NULL);

SetContext(ctx);
FreeResource(display->UID);

The above code allocates a Bitmap and a memory block, both of which will be contained by the display. When FreeResource() is called, both the bitmap and memory block will be automatically removed as they have a dependency on the display's existence. Please keep in mind that the following is incorrect:

InitObject(display);
auto ctx = SetContext(display);

   NewObject(CLASSID::BITMAP, &bitmap);
   AllocMemory(1000, MEM::DATA, &memory, NULL);

SetContext(ctx);
FreeResource(display->UID); // The bitmap and memory would be auto-collected
FreeResource(bitmap->UID);  // Reference is no longer valid
FreeResource(memory);  // Reference is no longer valid

As the bitmap and memory block would have been freed as members of the display, their references are invalid when manually terminated in the following instructions.

SetContext() is intended for use by modules and classes. Do not use it in an application unless conditions necessitate its use. The Core automatically manages the context when calling class actions, methods and interactive fields.

Result

Returns a pointer to the previous context. Because contexts nest, the client must call SetContext() a second time with this pointer in order to keep the process stable.

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.

SetField()

Used to set field values of objects.

The SetField() function is used to write field values to objects.

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

SetField(Object, FID_X|TLONG, 100);
SetField(Object, FID_Statement|TSTR, "string");

Fields are referenced as hashed UID's calculated from the C++ strihash() function. The majority of field ID's are predefined in the parasol/system/fields.h include file.

The type of the Value parameter must be OR'd into the Field parameter. If the provided type does not match that of the field, a type conversion will occur. All numeric types are compatible with each other and strings can also be converted to a numeric value automatically. String and pointer types are interchangeable.

Available field types are as follows:

There is no requirement for the client to have a working knowledge of the target object's field configuration in order to write information to it.

To set a field with a fixed-size array, use the SetArray() function.

Error Codes

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. Please note that the length of the Name will be limited to the value indicated in the core header file, under the MAX_NAME_LEN definition. 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:

• 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.
• The object's class will then receive notification via the NewOwner action.
• 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()

Sets miscellaneous resource identifiers.

The SetResource() function is used to manipulate miscellaneous system resources. Currently the following resources are supported:

Result

Returns the previous value of the Resource. If the Resource value is invalid, NULL is returned.

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 == ERR::Okay) 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. Subscriptions are not resource tracked, so it is critical to match the original call with an unsubscription.

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, LARGE Elapsed, LARGE 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. Fluid callbacks should call check(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 SubscriptionID 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

UnloadFile()

Unloads files from the file cache.

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

UnsubscribeAction()

Terminates action subscriptions.

The UnsubscribeAction() function will terminate subscriptions made by SubscribeAction().

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

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.

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 Data is defined, 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.

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.

The WaitForObjects() function acts as a front-end to ProcessMessages(), with the capability of being able to wait for a series of objects that must signal an end to their activities. An object can be signalled via the Signal() action. Termination of a monitored object is also treated as a signal. The function will return once ALL of the objects are signalled or a time-out occurs.

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.

Error Codes

WaitTime()

Waits for a specified amount of seconds and/or microseconds.

This function waits for a period of time as specified by the Seconds and MicroSeconds parameters. 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.

AC Type

Action identifiers.

ALIGN Type

Universal values for alignment of graphics and text

CCF Type

Class categories

CF Type

Compression stream formats

CLF Type

Flags for the MetaClass.

CLIPMODE Type

Clipboard modes

CMF Type

Compression flags

CNF Type

Flags for the Config class.

CON Type

Gamepad controller buttons.

DATA Type

Data codes

DEVICE Type

DMF Type

DRL Type

Compass directions.

EDGE Type

Edge flags

EVG Type

Event categories.

FBK Type

Flags for file feedback.

FD Type

Field descriptors.

FDB Type

Feedback event indicators.

FDL Type

Options for the File Delete() method.

FDT Type

Flags for the SetDate() file method.

FFR Type

Return codes available to the feedback routine

FL Type

File flags

FOF Type

Flags that can be passed to FindObject()

IDTYPE Type

Types for AllocateID()

JET Type

JET constants are documented in GetInputEvent()

JTYPE Type

JTYPE flags are used to categorise input types.

KEY Type

Raw key codes

KQ Type

Special qualifier flags

LAYOUT Type

Universal values for alignment of graphic layouts in documents.

LDF Type

Flags for LoadFile()

LOC Type

AnalysePath() values

MAX Type

MEM Type

Memory types used by AllocMemory(). The lower 16 bits are stored with allocated blocks, the upper 16 bits are function-relative only.

MFF Type

Flags for the File Watch() method.

MHF Type

Internal options for requesting function tables from modules.

MOF Type

Module flags

MOVE Type

Generic flags for controlling movement.

MSF Type

Message flags.

MSGID Type

Reserved message ID's that are handled internally.

MTF Type

MoveToPoint flags

NETMSG Type

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

PTC Type

Predefined cursor styles

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()

SCF Type

Script flags

SEEK Type

Seek positions

STR Type

STT Type

Types for StrDatatype().

THF Type

Thread flags

TOI Type

TSF Type

Task flags

TSTATE Type

Indicates the state of a process.

VAS Type

For use by VirtualVolume()

VLF Type

VlogF flags

VOLUME Type

Options for SetVolume()

ActionArray Structure

ActionTable Structure

Structure for ActionList

ChildEntry Structure

Structure for ListChildren() function

ClipRectangle Structure

Generic structure for rectangular clipping.

ColourFormat Structure

CompressedItem Structure

CompressionFeedback 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.