API函数的理解.docVIP

（API其实就是操作系统留给应用程序的一个调用接口，应用程序通过调用操作系统的 API 而使操作系统去执行应用程序的命令（动作）。API是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。一个API就是一个 “规范”，它规定了两个软件之间的“交流”和数据交换方式。 3.2 osal_msg_allocate ( ) 概述： 当一个任务调用这个函数时，将为消息分配缓冲区，函数会将消息加入缓冲区，并调用osal_msg_send()将消息发送到另一个任务。 原型： byte *osal_msg_allocate( uint16 len ) 参数： len ：消息的长度 返回值： 指向消息缓冲区的指针，当分配失败时返回NULL 3.3 osal_msg_deallocate( ) 概述： 用于收回缓冲区 原型：byte osal_msg_deallocate( byte *msg_ptr ) 参数： Msg_ptr : 指向将要收回的缓冲区的指针 返回值：RETURN VALUE DESCRIPTION ZSUCCESS 回收成功 INVALID_MSG_POINTER 错误的指针 MSG_BUFFER_NOT_AVAIL 缓冲区在队列中 3.4 osal_msg_send( ) 概述： 任务调用这个函数以实现发送指令或数据给另一个任务或处理单元。目标任务的标识必须是一个有效的系统任务，当调用osal_create_task ( )启动一个任务时，将会分配任务标识。 osal_msg_send()也将在目标任务的事件列表中设置SYS_EVENT_MSG 原型： byte osal_msg_send( byte destination_task, byte *msg_ptr ) 参数： destination_task ：目标任务的标识 msg_ptr ：指向消息缓冲区的指针 返回值： ZSUCCESS 消息发送成功 INVALID_MSG_POINTER 无效指针 INVALID_TASK 目标任务无效 3.5 osal_msg_receive( ) 概述： 任务调用这个函数来接收消息。消息处理完毕后，发送消息的任务必须调用osal_msg_deallocate()收回缓冲区。 原型： byte *osal_msg_receive( byte task_id ) 参数： task_id ：消息发送者的任务标识 返回值： 指向消息所存放的缓冲区指针，如果没有收到消息将返回NULL。 4.任务同步API 4.1概述 这个API使能一个任务等待一个事件的发生和返回控制而不是一直等待。在这个API中的函数可以用来为任务设置事件，立刻通知任务有事件被设置。 4.2 osal_set_event( ) 概述： 函数用来设置一个任务的事件标志 原型： byte osal_set_event( byte task_id, UINT16 event_flag ) 参数： task_id ：任务标识 event_flag　：２个字节，每个位特指一个事件。只有一个系统事件，其他事件在接收任务中定义。 返回值： ZSUCCESS 成功设置 INVALID_TASK 无效任务 ５.定时器管理ＡＰＩ ５.１概述 这个ＡＰＩ允许内部任务（Z-Stack）以及应用层任务使用定时器。函数提供了启动和停止定时器的功能，定时器最小增量为1MS。 5.2 osal_start_timer( ) 概述： 启动定时器函数。当定时器到点时，the given event bit will be set。事件将在任务中设置，要指明具体任务，调用osal_start_timerEx() 原型: byte osal_start_timer(UINT16 event_id, UINT16 timeout_value); 参数： event_id : 用户定义的event bit. 当定时器到点时，事件将通知任务。 timeout_value ：定时值（ms） 返回值： ZSUCCESS Timer 成功开启 NO_TIMER_AVAILABLE 无法开启 5.3 osal_start_timerEx( ) 概述： 功能与osal_start_timer()相近，这个函数允许调用者为另一个任务启动定时器 原型：byte osal_start_timerEx( byte taskID, UINT16 event_id, UINT16 timeout_value); 参数： 略 返回值： ZSUCCESS Timer 成功开启 NO_TIMER_AVAILABLE 无法开启 5.4 osal_stop_ti