uC/OS-II 函数之邮箱管理相关函数

转载至:uC/OS-II 函数之邮箱管理相关函数 - Wpeace - 博客园

本文介绍邮箱管理相关的函数：OSMboxCreate()建立一个邮箱,OSMboxDel()删除一个邮箱,OSMboxPend()等待邮箱中的消息,OSMboxPost()向邮箱发送一则消息，OSMboxQuery()查询一个邮箱的状态.

邮箱管理简述

邮箱是µC/OS-II中另一种通讯机制，它可以使一个任务或者中断服务子程序向另一个任务发送一个指针型的变量。该指针指向一个包含了特定“消息”的数据结构。为了在µC/OS-II中使用邮箱，必须将OS_CFG.H中的OS_MBOX_EN常数置为1。
使用邮箱之前，必须先建立该邮箱。该操作可以通过调用OSMboxCreate()函数来完成（见下节），并且要指定指针的初始值。一般情况下，这个初始值是NULL，但也可以初始化一个邮箱，使其在最开始就包含一条消息。如果使用邮箱的目的是用来通知一个事件的发生（发送一条消息），那么就要初始化该邮箱为NULL，因为在开始时，事件还没有发生。如果用户用邮箱来共享某些资源，那么就要初始化该邮箱为一个非NULL的指针。在这种情况下，邮箱被当成一个二值信号量使用。
µC/OS-II提供了6种对邮箱的操作：OSMboxCreate()，OSMboxDel()，OSMboxPend()，OSMboxPost()，OSMboxAccept()和OSMboxQuery()函数。图 F10.6描述了任务、中断服务子程序和邮箱之间的关系，这里用符号“I”表示邮箱。邮箱包含的内容是一个指向一条消息的指针。一个邮箱只能包含一个这样的指针（邮箱为满时），或者一个指向NULL的指针（邮箱为空时）。从图 F10.6可以看出，任务或者中断服务子程序可以调用函数OSMboxPost()，但是只有任务可以调用函数OSMboxPend()和OSMboxQuery()。

OSMboxCreate()建立一个邮箱

1主要作用：基本上和函数OSSemCreate()相似。建立一个邮箱变量；
2函数原型：OS_EVENT *OSMboxCreate (void *msg)
3参数说明：msg 是一个要在任务间传递的变量指针
4返回值说明：OSMboxCreate()函数的返回值是一个指向事件控制块的指针[L10.14(3)]。这个指针在调用函数OSMboxPend()，OSMboxPost()，OSMboxAccept()和OSMboxQuery()时使用。因此，该指针可以看作是对应邮箱的句柄。值得注意的是，如果系统中已经没有事件控制块可用，函数OSMboxCreate()将返回一个NULL指针。
5函数主体在os_mbox.c中

OSMboxDel()删除一个邮箱

1、主要作用：对一个不再使用的消息邮箱要及时删除以释放资源。
2、函数原型：OS_EVENT *OSMboxDel (OS_EVENT pevent, INT8U opt, INT8U err)
3、参数说明：pevent邮箱句柄
opt == OS_DEL_NO_PEND 如果没有等待任务时删除邮箱；
opt == OS_DEL_ALWAYS 无条件删除又向，所有等待该事件的任务急转到就绪状态；
err 是本函数执行状态的返回值，err 的值含义：
ØOS_NO_ERR ---- 函数成功，指定的邮箱被删除；
ØOS_INVALID_OPT ---- 删除方式数据错；
ØOS_ERR_EVENT_TYPE ---- 欲删除的事件类型不是邮箱；
ØOS_ERR_DEL_ISR ---- 不支持ISR中的消息邮箱删除操作；
ØOS_ERR_PEVENT_NULL ---- 指定的事件为空（不存在）；
ØOS_ERR_TASK_WAITING ---- 邮箱中还有等待任务；
4、返回值说明：删除的句柄
5函数主体在os_mbox.c中

OSMboxPend()等待邮箱中的消息

1、主要作用 ：所谓的 “请求消息邮箱” 就是等待一个消息传送到消息邮箱，或取得一个消息数据。
2、函数原型：void *OSMboxPend (OS_EVENT *pevent, INT16U timeout, INT8U err)
3、参数说明：pevent消息邮箱指针；timeout等待时限；err函数执行信息；
4、返回值说明：返回值为空时意味着未得到消息，此时uC/OS-II执行OS_Sched()；可能消息未准备好，或指示的事件出错、超时等，此时函数直接返回，用户应查阅 *err的状态。
当返回值 != Null 时，返回值就是一个预期消息的指针；
5函数主体在os_mbox.c中

OSMboxPost()向邮箱发送一则消息

1、主要作用：可以调用系统函数OSMboxPost( )函数向消息邮箱发送消息；
2、函数原型：INT8U OSMboxPost (OS_EVENT *pevent, void *msg)
3、参数说明：形参 msg 是一个要在任务间传递的变量指针；形参 pevent 是消息邮箱指针；
4、返回值说明：
1、OS_NO_ERR ---- 消息发送成功；
2、 OS_MBOX_FULL ---- 不能向满邮箱再发送消息；
3、OS_ERR_EVENT_TYPE ---- 指定的事件不是消息邮箱类型；
4、OS_ERR_PEVENT_NULL ---- 不能向不存在的消息邮箱发送消息；
5、OS_ERR_POST_NULL_PTR ---- 消息缓冲区不能为空；
5函数主体在os_mbox.c中
向邮箱发送一则消息可以用下面函数，功能更强大，可发送广播消息
INT8U OSMboxPostOpt (OS_EVENT *pevent, void *msg, INT8U opt)

OSMboxQuery()查询一个邮箱的状态

1、主要作用：函数使应用程序可以随时查询一个邮箱的当前状态
2、函数原型：INT8U OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *pdata)
3、参数说明：一个是指向邮箱的指针pevent。该指针是在建立该邮箱时，由OSMboxCreate()函数返回的；另一个是指向用来保存有关邮箱的信息的OS_MBOX_DATA（见uCOS_II.H）数据结构的指针pdata。
４、返回值说明：OS_NO_ERR ：调用成功
OS_ERR_EVENT_TYPE ：pevent 不是指向消息邮箱的指针。
注意/警告:必须先建立消息邮箱，然后使用。

5函数主体在os_mbox.c中