Upon success, the function returns a handle to the newly created mailbox object. On failure, it returns NULL_HANDLE. Call the osGetLastError function to retrieve extended error information.

Mailboxes are functionally similar to queues, providing a mechanism for First-In, First-Out (FIFO) data exchange between tasks. The primary distinction between a mailbox and a standard queue is that mailboxes do not impose a fixed limit on message size or the number of messages; capacity is constrained only by the available system memory.

When creating a mailbox, an optional name may be assigned. This allows other tasks to obtain a handle to the mailbox using the osOpenMailbox function. When a mailbox is no longer required, it should be closed using osCloseHandle. The mailbox is formally deleted only after all tasks that opened it have closed their respective handles. Further details are available in the system objects management section.

If all osOpen* functions are disabled in the configuration, the system will ignore object names, and the name management code will be excluded from the build. This optimization reduces the final code size. For more information regarding naming and object access, refer to the system objects management section.

If OS_MBOX_PEEK_FUNC is set to 1, access to the mailbox must be synchronized during data copy operations. Synchronization can be implemented in three ways: via a mutex, an auto-reset event, or by disabling interrupts. Interrupt disabling should only be used when transferring very small data fragments. The synchronization method is selected at creation time via the OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT, or OS_IPC_PROTECT_INT_CTRL flags. Mutex or event-based synchronization is only available if the corresponding constants OS_MBOX_PROTECT_MUTEX or OS_MBOX_PROTECT_EVENT are set to 1. If osTerminateTask is utilized on tasks performing mailbox operations, mutex-based synchronization is recommended.

By default, performing a read operation on an empty mailbox will result in an immediate error. However, a task can be configured to block until data becomes available or a timeout occurs. This behavior is enabled by using the OS_IPC_WAIT_IF_EMPTY flag during creation, provided that OS_MBOX_ALLOW_WAIT_IF_EMPTY is set to 1.

When the blocking feature is enabled, data can be transferred directly from the sender task to the receiver task without being buffered in the mailbox. To enable this direct transfer optimization, use the OS_IPC_DIRECT_READ_WRITE flag. This feature requires OS_MBOX_ALLOW_DIRECT_RW to be set to 1.

For more information on mailboxes, refer to the mailbox objects section.

This function is available only when the OS_USE_MAILBOX constant is set to 1.