=========
MailBoxes
=========

.. image:: Mailbox_Diagram.png
    :width: 600

* Used to send pointers to application specific data structures
  to waiting tasks.
* Initialize with 0.
* One can also use a mailbox to control access to a single resource
  like a binary semaphore.
* Initialize it with a pointer to the resource.

..
    * Cleared code pattern then shared global. The pointer is the semaphore.

OSMboxCreate
============

.. code-block:: c

    OS_EVENT *OSMboxCreate(void *pmsg);

OSMboxDel
=========

.. code-block:: c

    OS_EVENT *OSMboxDel(OS_EVENT *pevent, INT8U opt, INT8U *perr);

OSMboxPend
==========

.. code-block:: c

    void *OSMboxPend(OS_EVENT *pevent, INT16U timeout, INT8U *perr);

OSMboxPendAbort
===============

.. code-block:: c

    INT8U OSMboxPendAbort(OS_EVENT *pevent, INT8U opt, INT8U *perr);

OSMboxAccept
============

.. code-block:: c

    void *OSMboxAccept(OS_EVENT *pevent);

OSMboxPost
==========

.. code-block:: c

    INT8U OSMboxPost(OS_EVENT *pevent, void *pmsg);

OSMboxPostOpt
=============
.. code-block:: c

    INT8U OSMboxPostOpt(OS_EVENT *pevent, void *pmsg, INT8U opt);

* A more powerful version of post.
* Takes an option:

  * NULL for no option. Behaves just like OSMboxPost()
  * OS_POST_OPT_BROADCAST

* With no option only the highest waiting taks gets
  the message and its made ready to run.
* If there are no waiting tasks, then the message
  is set in the ECB and the function returns.
* If a task was made ready the ECB will be cleared
  and the scheduler will be called.
* It is an error to post to the mailbox if it already has data


OSMboxQuery
===========
.. code-block:: c

    INT8U OSMboxQuery(OS_EVENT *pevent, OS_MBOX_DATA *p_mbox_data);