XRRESOURCE(3X)

NAME
XrResource - the resource manager

SYNOPSIS
#include <X/Xlib.h>
#include <Xr/Xrlib.h>

XrResource (message, data)
INT32 message;
INT8 * data;

DESCRIPTION
The resource manager is used to add, find, or remove resource objects from an internally managed list. A resource object is identified by its functional type and a user-supplied resource number within that type.

Several of messages use the following structure for passing or returning data.
typedef struct
{
   UINT16 resourceType;
   INT32  resourceId;
   INT8 resourceState;
   INT32 resourceFile;
   INT8 * resourceObject;
} xrResourceInfo;

MSG_ADD
    This message adds to the resource manager the resource identified by the data parameter, which points to an xrResourceInfo structure. If the resourceObject field contains a valid pointer, the resourceFile field will be set to XrMEMORY to indicate the resource is from application memory.

    If the resource type and id fields in data match a resource already within the resource list, the resource in the list will be replaced with the new resource. If the location of the old resource is from application memory the resourceObject field within data will be set to point at the object being replaced. This allows an application to maintain control of an object being replaced in the resource list.

MSG_REMOVE
    This message removes from the resource list the object identified by the data parameter, which points to a filled out instance of a xrResourceInfo structure. Only the resourceType and resourceId fields need to be set by the application. When the resource is located in the resource managers lists, the resourceFile field is checked and if it is set to XrMEMORY, the resourceObject field in data will be set to point to the object. If the object is not found in the resource list this message will fail.

MSG_FIND
    This message locates the requested resource within the resource list. data is a pointer to an xrResourceInfo structure. The resourceType and resourceId fields of the structure identify the resource to be found. When the resource is located, the rest of the fields of the structure will be filled out.

MSG_SETSTATE
    This messages is used to set the state of a resource contained within the resource manager. For this message, data is a pointer to an xrResourceInfo structure which has the resourceType, resourceId, and resourceState fields filled out. This message will search for the resource, and when it is found, set its resourceState to the new state.

The following two messages provide for the creation or destruction of application defined resource types.

MSG_NEWTYPE
    This message allows an application to create a new resource type. data is a pointer to the following structure.
    typedef struct
    {
       UINT16  resourceType;
       INT32  (*resourceHandler)();
    } xrResourceTypeInfo;

MSG_FREETYPE
    This message destroys and removes a resource type from the resource type list. data contains the resource type identifier. This message will fail if the identifier is not in the range of 1 - 63999 or if the resource type is not defined or if the there are any resources still attached to the resource type.

RETURN VALUE
XrResource() returns TRUE when successful, FALSE otherwise.

ERROR CONDITIONS
If XrError() returns FALSE the xrErrno global will be set to one of the following values.

xrErrno will be set to XrINVALIDMSG for any messages besides the messages listed above.

xrErrno will be set to XrINVALIDID anytime a resource id is invalid or cannot be found.

xrErrno will be set to XrINVALIDTYPE anytime a resource type is invalid.

xrErrno will be set to XrINVALIDSTATE anytime a resource is to be modified and a state flag setting prevents it.

xrErrno will be set to XrINVALIDPARM whenever the data parameter contains invalid information.

xrErrno will be set to XrOUTOFMEM if MSG_ADD cannot allocate the needed space for a resource.