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

This function opens an existing mailbox object by its assigned name.

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, allowing other tasks to obtain a handle to the mailbox using the osOpenMailbox function. When a mailbox handle 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.

For further details on mailbox functionality, refer to the mailbox objects section.

This function is available only when both the OS_USE_MAILBOX and OS_OPEN_MBOX_FUNC constants are set to 1. If the function is not required, set OS_OPEN_MBOX_FUNC to 0 to reduce the compiled code size.