原创 uC/OS-II中的消息邮箱

最近在学习UCOS-II，为了自已方便，我把UCOS-II内核程序都做了一个注释，虽然不够完整，但对学习也是有一定帮助的，我把它放在这里，希望对大家有所帮助吧。所有的注释我会陆续放在这里的。敬请关注。
消息邮箱是uC/OS-II中的另一种通信机制，可以使一个任务或者中断服务子程序向另一个任务发送一个指针型的变量。通常该指针指向一个包含了“消息”的特定数据结构。
　　应用程序可以使用多少个邮箱，其最大数目是由OS_CFG.H文件中的配置常数OS_MAX_EVENTS设定。
任务或者中断服务子程序都可以调用函数OSMboxPost()，OSMboxPostOpt() ，而只有任务可以调用OSMboxDel()
OSMboxPend()， OSMboxQuery()。
void   *OSMboxAccept (OS_EVENT *pevent)
　　无等待的从邮箱中得到一则消息。
OS_EVENT   *OSMboxCreate (void *msg)
　　建立一个邮箱。
　　msg:用来初始化建立的消息邮箱，如果该指针不为空，则建立的消息邮箱将含有消息。
　　返回值：指向分配给所建立的消息邮箱的事件控制块的指针。如果没有可用的事件控制块，则返回空指针。
OS_EVENT   *OSMboxDel (OS_EVENT *pevent, INT8U opt, INT8U *err)
　　删除一个邮箱。当将OS_CFG.H文件中的OS_MBOX_DEL_EN设为1时，该函数才会被编译。使用该函数时要注意，多个任务可能试图操作已经删除的邮箱。在删除邮箱之前，必须首先删除可能操作该邮箱的所有任务。
　　pevent:指向邮箱的指针。该指针是在邮箱建立时返回给用户应用程序的指针。
　　opt:该先项定义邮箱的删除条件，可以选择只能在已经没有任何在等待该邮箱的消息时，才能删除邮箱
         (OS_DEL_NO_PEND)；或者不管有没有任务在等待邮箱的消息，立即删除邮箱（OS_DEL_ALWAYS)，在这种情况   下，所有等待邮箱消息的任务都会立即进入就绪态。
err:指向出错代码的指针。返回的出错代码可以是以下几种情况之一。
　　OS_NO_ERR    调用成功，邮箱已经被删除。
　　OS_ERR_DEL_ISR   试图在中断服务子程序中删除邮箱。
　　OS_ERR_INVALID_OPT 无效的opt参数，用户没有将opt定义为上述两种情况之一。
　　OS_ERR_EVENT_TYPE pevent不是指向邮箱的指针。
　　OS_ERR_PEVENT_NULL 已经没有OS_EVENT数据结构可以使用。
返回值：返回NULL表示邮箱已被删除；返回pevent表示邮箱没有删作，。
void   *OSMboxPend (OS_EVENT *pevent, INT16U timeout, INT8U *err)
　　等待邮箱中的消息。
pevent:指向即将接收消息的消息邮箱的指针。
timeout:允许一个任务在经过了指定数目的时钟节拍后还没有得到需要的消息时恢复运行。如果该值为0表示任务将持续等待消息。
err:指向包含错误码的变量的指针。该函数返回的错误码可能为下述几种情况
　　OS_NO_ERR    消息被正确地接收。
　　OS_TIMEOUT    消息没有在指定的等待时间内送到。
　　OS_ERR_EVENT_TYPE pevent不是指向消息邮箱的指针。
　　OS_ERR_PEND_ISR   从中断调用该函数。
　　OS_ERR_PEVENT_NULL　pevent是空指针。
　　返回值：该函数返回接收的消息并将*err置为OS_NO_ERR.
INT8U   OSMboxPost (OS_EVENT *pevent, void *msg)
　　向邮箱发送一则消息。
     pevent:指向即将接收消息的消息邮箱的指针。
msg:即将实际发送给任务的的消息。消息是一个以指针表示的苛种数据类型的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针，国灰这意味着消息邮箱为空。
返回值：该函数的返回值为下述之一：
　　　OS_NO_ERR    消息成功地放到消息邮箱中。
　　　OS_MBOX_FULL   消息邮箱已经包含了其他消息，已满。
　　　OS_ERR_EVENT_TYPE   pevent不是指向消息邮箱的指针。
　　　OS_ERR_PEVENT_NULL pevent是空指针。
　　　OS_ERR_POST_NULL_PTR   用户试图发出空指针。根据规则，在这里不支持空指针。
INT8U   OSMboxPostOpt (OS_EVENT *pevent, void *msg, INT8U opt)
　　向邮箱发送一则消息。该函数可以向等待邮箱的所有任务发送消息（广播）。
　　pevent:指向即将接收消息的消息邮箱的指针。
　　msg:即将实际发送给任务的消息。消息是一个以指针表示的某种数据类型的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针，因为这意味着消息邮箱为空。
　　opt:定义消息只发给等待邮箱消息的任务中优先级最高的任务（将opt置为OS_POST_OPT_NONE)，或者让所有等待 邮箱消息的任务都得到消息（将opt置为OS_POST_OPT_BROADCAST)。
　　返回值：
　　　err   指向包含错误码的变量指针，返回的错误码可能为下述几种之一：
　　　     OS_NO_ERR    消息成功地放到消息邮箱中。
　　　OS_MBOX_FULL   消息邮箱已经包含了其他消息，已满。
　　　OS_ERR_EVENT_TYPE   pevent不是指向消息邮箱的指针。
　　　OS_ERR_PEVENT_NULL pevent是空指针。
　　　OS_ERR_POST_NULL_PTR   用户试图发出空指针。根据规则，在这里不支持空指针。
INT8U   OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *p_mbox_data)
　　查询一个邮箱的状态。
　　pevent:指向即将接收消息的消息邮箱的指针。
　　pdata:指向OS_MBOX_DATA数据结构的指针，该数据结构包含下述成员。
　　　　　void   *OSMsg；       /*消息邮箱中消息的复制*/
　   　INT8U   OSEventTbl[OS_EVENT_TBL_SIZE];   /*消息邮箱等待队列的复制*/
   　INT8U   OSEventGrp
返回值：该函数返回值为下述之一：
   　OS_NO_ERR     调用成功
   　OS_ERR_EVENT_NULL   pevent是空指针
   　OS_ERR_EVENT_TYPE   pevent不是指向消息邮箱的指针。