1. 信息管理API
信息管理為任務間的信息交換或者外部處理事件（例如：中斷服務程序或一個控制循環內的函數調用）提供一種管理機制。包括允許任務分配或不分配信息緩存、發送命令信息到其他任務、接受應答信息等API函數。
（1)osal_msg_allocate ( )
功能描述：
為信息分配緩存空間、任務調用或函數被調用的時候，該空間被信息填充或調用發送信息函數osal_msg_send()發送緩存空間的信息到其他任務。
原型：
byte *osal_msg_allocate( uint16 len )
參數：
len ：消息的長度
返回值：
指向消息緩沖區的指針，當分配失敗時返回NULL
注意：不能與函數osal_mem_alloc()混淆，osal_mem_alloc()函數被用于為在任務間發送信息分配緩沖區，用該函數也可以分配一個存儲區。
（2）osal_msg_deallocate( )
功能描述：
用于收回緩沖區
原型：
byte osal_msg_deallocate( byte *msg_ptr )
參數：
Msg_ptr : 指向將要收回的緩沖區的指針
返回值：
ZSUCCESS 回收成功
INVALID_MSG_POINTER 錯誤的指針
MSG_BUFFER_NOT_AVAIL 緩沖區在隊列中
（3） 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 ： 指向消息緩沖區的指針，必須是osal_msg_allocate ( )函數分配的有效的數據緩存
返回值：
返回一個字節，指示操作的結果.
ZSUCCESS 消息發送成功
INVALID_MSG_POINTER 無效指針
INVALID_TASK 目標任務無效
(4) osal_msg_receive( )
功能描述：
任務調用這個函數來接收消息。消息處理完畢后，發送消息的任務必須調用osal_msg_deallocate()收回緩沖區。一個任務接收一個命令信息是，調用該函數
原型：
byte *osal_msg_receive( byte task_id )
參數：
task_id ：消息發送者的任務標識
返回值：
指向消息所存放的緩沖區指針，如果沒有收到消息將返回NULL。
2 同步任務API
這個API使能一個任務等待一個事件的發生和返回控制而不是一直等待。在這個API中的函數可以用來為任務設置事件，立刻通知任務有事件被設置。
osal_set_event( )
功能描述：
函數用來設置一個任務的事件標志
原型：
byte osal_set_event( byte task_id, UINT16 event_flag )
參數：
task_id ：任務標識
event_flag ：是２個字節的位圖，每個位特指一個事件。只有一個系統事件（SYS_EVENT_MSG），其他事件在接收任務中定義。
返回值：
ZSUCCESS 成功設置
INVALID_TASK 無效任務
3.. 時間管理API
這個ＡＰＩ允許內部任務（Z-Stack）以及應用層任務使用定時器。函數提供了啟動和停止定時器的功能，定時器最小增量為1MS。
（1） osal_start_timer( )
功能描述：
啟動一個定時器，當定時器終止時，指定的事件標志位被設置。通過在任務中調用osal_start_timer函數設置時間標志位。如果指明任務ID，則可以用osal_start_timerEx()函數替代osal_start_timer().
原型:
byte osal_start_timer(UINT16 event_id, UINT16 timeout_value);
參數：
event_id : 用戶定義的事件標志位event bit. 當定時器到點時，事件將通知任務。
timeout_value ：定時值（ms）
返回值：
ZSUCCESS Timer 成功開啟
NO_TIMER_AVAILABLE 無法開啟
（2） osal_start_timerEx( )
功能描述：
功能與osal_start_timer()相近，只不過參數多了一個任務ID，這個函數允許調用者為另一個任務啟動定時器
原型：
byte osal_start_timerEx( byte taskID, UINT16 event_id, UINT16
timeout_value);
參數：
參數1：taskID 當定時器終止時，得到該事件的任務ID
參數2：event_id,是用戶定義的事件位，當定時器終止時，正在調用的任務將被通報
參數3：定時器事件被設置之前時間的計數
返回值：
ZSUCCESS Timer 成功開啟
NO_TIMER_AVAILABLE 無法開啟
（3）osal_stop_timer( )
功能描述：
停止正在運行的定時器，停止外部事件調用osal_stop_timerEx()，可以停止不同任務的定時器。
原型：
byte osal_stop_timer( UINT16 event_id );
參數：
event_id ：將要結束的目標事件（該事件是啟動定時器的事件）定時器的標識符
返回值：
ZSUCCESS Timer 成功停止
INVALID_EVENT_ID 無效事件
（4）osal_stop_timerEx( )
功能描述：
結束外部事件的定時器，指明了任務的ID
原型：
byte osal_stop_timerEx( byte task_id, UINT16 event_id );
參數：
參數1：停止定時器所在的任務ID
參數2：被停止定時器的標識符
返回值
ZSUCCESS Timer 成功停止
INVALID_EVENT_ID 無效事件
（5）osal_GetSystemClock( )
功能描述：
讀取系統時間
原型：
uint32 osal_GetSystemClock( void );
參數：
無
返回值：
系統時間（ms）
4 中斷管理API
這些API實現任務與外部中斷的接口，函數允許一個任務關聯每一個具體的中斷程序程序，可以開關中斷。在中斷服務程序內，其他任務可以設置事件。
（１） osal_int_enable( )
功能描述：
函數用于使能中斷。一旦允許中斷發生將引起中斷分配的服務程序運行。
原型：
byte osal_int_enable( byte interrupt_id )
參數：
interrupt_id ：被允許的中斷的標識符。
返回值：
ZSUCCESS Interrupt 成功使能
INVALID_INTERRUPT_ID 無效中斷
（2）osal_int_disable( )
功能描述：
關閉中斷
原型：
byte osal_int_disable( byte interrupt_id )
參數：
被禁止中斷的標識符
返回值：
ZSUCCESS Interrupt 成功關閉
INVALID_INTERRUPT_ID 無效中斷
5 任務管理API
該API用在添加和管理OSAL中的任務。每一個任務由任務初始化函數和時間處理函數組成。
（1）osal_init_system()
功能描述：
該函數初始化OSAL系統。該函數必須在啟動任何一個OSAL函數之前被調用
原型：
byte osal_init_system( void )
參數:
無
返回值：
ZSUCCESS 成功
（2）osal_start_system()
功能描述：
這個函數是系統任務的主循環函數，在循環里面將遍歷所有的任務事件，為觸發事件的任務調用任務事件處理函數。如果一個特定任務有事件發送，那么該函數就將調用該任務的事件處理函數。當事件處理完之后，將返回主循環。繼續查找其他的任務事件。如果沒有事件，函數將把處理器轉到睡眠模式。
原型：
void osal_start_system( void )
參數：
無
返回值：
無
（3）osal_self( )
功能描述：
這個函數 返回正在被調用任務的任務標識符。如果在一個中斷服務子程序中調用該函數將返回一個錯誤結果。
函數原型
byte osal_self( void )
參數描述
無
返回值：
返回值為當前活動的任務的任務標識符
（4）osalTaskAdd( )
功能描述：
這個函數添加一個任務到任務系統中，一個任務由兩個函數組成 – 初始化與信息處理。信息處
理函數在事件時發生，而后處理其中之一，并返回其余到主循環中。
函數原型
//任務初始化函數原型
typedef void(*pTaskInitFn) (unsigned char task_id);
//事件句柄函數原型
typedef unsigned short (*pTaskEventHandlerFn)(unsigned char task_id,unsigned short event);
//添加任務函數原型
void osalTaskAdd(const pTaskInitFn pfnInit,const pTaskEventHandlerFn,pfnEventProcessor,
const byte taskPriority);
參數描述
pfnInit – 指向任務初始化函數的指針
pfnEventProcessor – 指向任務事件處理器函數的指針
taskPriority – 任務的優先級。值為 0 ~ 255 之間
優先級 值
OSAL_TASK_PRIORITY_LOW 50
OSAL_TASK_PRIORITY_MED 130
OSAL_TASK_PRIORITY_HIGH 230
6 內存管理API
該 API 呈現一個簡單的內存分配系統。這些函數允許動態內存分配。
（1）osal_mem_alloc( )
功能描述：
這個函數是一個簡單內存分配函數，如果成功則返回一個緩沖區的指針。
函數原型
oid *osal_mem_alloc(uint16 size);
參數描述
ize – 緩沖區的大小
返回值
一個 void 指針指向新分配的緩沖區，如果沒有足夠的內存來分配，則返回一個 NULL 指針。
（3） osal_mem_free
功能描述：
這個函數釋放已分配的內存來重新使用。只有當內存已使用 osal_mem_alloc( )分配過才可以工作。
函數原型
oid osal_mem_free(void *ptr);
參數描述
ptr - 指向將被釋放的緩沖區的指針，這個緩沖區之前必須被 osal_mem_alloc( )分配過使用。
返回值
無。
7. 電源管理 API
這里的函數描述了OSAL的電源管理系統，當OSAL安全的關閉接收器宇外部硬件并使處理器進入休眠模式時，該系統提供想應用/任務通報該事件的方法
（1） osal_pwrmgr_task_state( )
功能描述：
該函數被每個任務調用，聲明該任務是否需要節能，任務被創建時，默認是節能模式。如果任務總是需要節能，那么就不需要調用該函數。
函數原型
byte osal_pwrmgr_task_state(byte task_id,pwrmgr_state_t state);
參數描述
state – 改變一任務電源狀態。
類型 描述
PWRMGR_CONSERVE 打開節能模式，所有任務都須一致，為任務初始化的缺省模式。
PWRMGR_HOLD 關閉節能模式
返回值
返回值顯示操作的結果。
返回值 描述
ZSUCCESS 成功
INVALID_TASK 無效任務
(2) osal_pwrmgr_device()
功能描述：
該函數在上電或電源需求變更時調用（例如電源支持協調器）。這一函數設置了大體的設備電源管理的開/關狀態。該函數應當從中央控制實體（如ZDO)被調用。
原型：
void osal_pwrmgr_state( byte pwrmgr_device );
參數：
pwrmgr_device ：更改或設置節電模式
PWRMGR_ALWAYS_ON 無節電
PWRMGR_BATTERY 開節電
返回值：
無
8．非易失性（NV）存儲管理
這部分講述 OSAL NV非易失性（NV）存儲系統。系統提供了一種方式來為應用永久存放信息到設備內存中。
他也可以用于某些堆棧條目的固定存儲，這些 NV函數被設計用來讀取/寫入用戶定義的由任何數據類型組成的(如結構與數組)項目。用戶可以通過設定一適當的偏移量與長度讀取或寫入一個完整的項目或項目中的一個單元。 該API為NV存儲介質獨有，與存儲體本身沒有關系。可以被flash或eeprom使用。
每個 NV 項目都有一個惟一的標識符，每個應用都有特定的 ID值范圍(其余 ID值為保留，或為棧、平臺所用)。如果你的應用創建了自己的 NV項目，則必須從應用值范圍內選一個 ID。如下
0x0000 Reserved
0x0001 – 0x0020 OSAL
0x0021 – 0x0040 NWK
0x0041 – 0x0060 APS
0x0061 – 0x0080 Security
0x0081 – 0x00A0 ZDO
0x00A1 – 0x0200 Reserved
0x0201 – 0x0FFF Application
0x1000 -0xFFFF Reserved
在使用API時有一些重要的注意點：
1)這些是模塊化函數調用，一個操作需要花費幾毫秒來完成，特別是 NV寫操作。另外，中斷
需求禁止幾毫秒。最好是在與其他時間性操作上沒有沖突的時刻來執行這些函數。例如，一
個較佳的寫 NV 項目時刻是接收器關閉的時候。
2) 不要經常性寫 NV，它需要花費時間與能源，并且大多數的閃存都有一個最大擦除次數限制。
3) 如果一個或多個 NV 項目變更，特別是 Z-stack的版本升級，它必須擦除且重新初始化 NV
內存。否則，讀與寫已變更的 NV項目操作將失敗或產生錯誤的結果。
(1) osal_nv_item_init( )
功能描述：
初始化 NV中的一條項目。這個函數檢測 NV項目的存在，如果不存在，則它用
數據創建與初始化一個 NV 項目，如果有的話。 在調用 osal_nv_read( )或osal_nv_write( )前，每一個項目必須先調用該函數。
函數原型
yte osal_nv_item_init(uint16 id,uint16 len,void *buf);
參數描述
id – 用戶定義項目標識符
len – 項目長度(字節)
buf – 項目初始化數據指針，如果沒有初始化數據，則設為 NULL.
返回值
返回值顯示操作的結果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 成功但項目不存在
(2) osal_nv_read( )
功能描述：
讀取 NV數據，這個函數被用來讀取整個 NV項目或一個項目中項目，讀取的數據被復制到*buf 中。
函數原型
yte osal_nv_read( uint16 id, uint16 offset, uint16 len, void *buf);
參數描述
d – 用戶定義項目標識符
ffset – 項目的內存偏移量(字節)
en – 項目長度(字節)
buf – 數據讀取到該緩沖區
返回值
返回值顯示操作的結果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 項目沒有初始化
NV_OPER_FAILED 操作失敗
（2） nv_osal_write( )
功能描述：
寫入數據到 NV中，這個函數被用來寫入整個 NV項目或一個項目中的單元(通過一個偏移量來索
引該項目)。
函數原型
byte osal_nv_write( uint16 id,uint16 offset,uint16 len,void *buf);
參數描述
id – 用戶定義項目標識符
offset – 項目的內存偏移量(字節)
len – 項目長度(字節)
*buf – 要寫入的數據
返回值
返回值顯示操作的結果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 項目沒有初始化
NV_OPER_FAILED 操作失敗
（3） osal_offsetof( )
功能描述：
該宏在一個結構中按字節計算一個單元的內存偏移量，它被 NV API 函數用來計算偏移量。
函數原型
sal_offsetof(type,member)
參數描述
ype – 結構類型
member – 結構成員
|
