Creates a new mailbox and returns a handle for it. The mailbox type is determined by wMailboxFlags.

RTHANDLE CreateRtMailbox(
    WORD wMailboxFlags    // Mailbox creation flags
);

Parameters

wMailboxFlags

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 60, and a multiple of 4.

Remarks

When you set up a mailbox to pass objects (not data) you can also set up a high-performance queue. This queue is a block of memory that stores objects waiting to be sent or received. It is permanently assigned to the mailbox, and the unused portion of the queue is unavailable for other uses. If the queue overflows, the Nucleus temporarily allocates another 200-object queue.

To get the best tradeoff between memory and performance, choose a size for your high-performance queue that is large enough for normal operations, and let the overflow queue handle unusual circumstances.

When you create a mailbox to pass data, you do not specify the size of the message queue. The OS automatically sets up a queue of 400 bytes.

Return Values

A handle for the mailbox object just created

Success

BAD_RTHANDLE

To determine the status, call GetLastRtError

Status

E_OK 0x0000

No exceptional conditions occurred.

E_MEM 0x0002

Creating a mailbox requires more available memory to the calling thread's process than currently exists.

E_LIMIT 0x0004

The calling thread's process reached its object limit.

E_SLOT 0x000C

You cannot create more RT objects because the GDT's slots are full.

Requirements

See Also

Mailbox system calls