INtime SDK Help
CreateGlobalRtMailbox
INtime SDK v7.1 > About INtime > INtime Kernel > Global objects > CreateGlobalRtMailbox

Creates a mailbox on a remote node indicated by the LOCATION parameter.

#include <rt.h> 

RTHANDLE CreateGlobalRtMailbox(  
    LOCATION hLoc, 
    WORD Flags
);

Parameters

hLoc
The location where the object is to be created.
Flags
Specifies flags that control the creation of the mailbox. Possible values are described below. Values may be combined where appropriate.
OBJECT_MAILBOX This flag indicates that the mailbox is to be created to pass RT object handles. It is mutually exclusive with the DATA_MAILBOX flag. The depth of the mailbox may be specified by the MAILBOX_DEPTH(n) macro.
DATA_MAILBOX This flag indicates that the mailbox is to be created to pass up to 128-byte messages. In this case the depth of the mailbox is initially 3 messages.
FIFO_QUEUING This flag indicates that threads will be queued in First-In-First-Out order on this object.
PRIORITY_QUEUING This flag indicates that threads will be queued in priority order on this object.
MAILBOX_DEPTH(n) This macro determines the number of objects which can be queued in an object mailbox. It is ignored for data mailboxes. The value n must be at least 8, at most 64, and a multiple of 4.
REFCOUNT This flag indicates that this object should be created as a reference-counted object.

Remarks

Creates a mailbox on the node indicated by the LOCATION parameter, of a type according to the Flags parameter, and returns a reference to that mailbox. An additional bit (REFCOUNT) is defined for the Flags parameter to indicate that the mailbox should be created with a reference counter. If the mailbox is not created with a reference counter, it is considered to be owned by the calling process, even though it is resident on the remote node. Thus if the local process is deleted the remote node's Global Objects Manager process is responsible for deleting the remote mailbox object. In the case of a reference-counted mailbox the object is only deleted after its reference count decrements to zero.

Return Values

A valid reference object handle
Success.
BAD_RTHANDLE
Failure. The function sets GetLastRtError to one of these values:
E_RESOURCE_LIMIT Insufficient resources are available to signal the remote node.
E_SLOT The maximum number of objects on the local node or the remote node has been exceeded.
E_MEM Insufficient physical memory is available to create the reference object or the remote object.
E_INVALID_ADDRESS (0x00E2) The address provided for hLoc is not a valid address.

Requirements

Versions Defined in Include Link to
INtime 4.0 intime/rt/include/rt.h rt.h rt.lib
See Also