QQAPI設計說明書

1、qqapi 設計說明書 目錄 一、引言.3 1.1 編寫目的.3 1.2 更新時間.3 二、總體設計.3 三、注冊的系統(tǒng)消息.3 3.1wm_qqapi_register .3 3.2wm_qqapi_register_resp .4 3.3wm_qqapi_available .4 四、從設備到qq 的自定義事件.5 4.1event_qqapi_set_audiodevice .5 4.2event_qqapi_get_userinfo .5 4.3event_qqapi_press_key .5 4.4event_qqapi_call .6 4.5event_qqapi_mute .6

2、4.6event_qqapi_unregister .7 五、從qq 到設備的自定義事件.7 5.1event_qqapi_userinfo .7 5.2event_qqapi_status_change .7 5.3event_qqapi_shutdown .8 六、雙向的自定義事件.8 6.1event_qqapi_call_status .8 七、錯誤碼定義.10 7.1 從 qq 到設備 event_qqapi_error .10 八、參數(shù)類型碼表.11 一、 引言 1.1 編寫目的 本文檔提供了qqapi 接口說明，以供第三方應用 程序使用，用 于 qq 和硬件設備（例如usbpho

3、ne）的交互。 1.2 更新時間 最后修訂日期：2005-05-24 版本號：v1.0 二、總體設計 qq 應用程序和第三方應用程序以收發(fā)消息的方式進行通訊。 雙方未成功注冊之前，采用 registerwindowmessage（ windowsapi）注冊的系統(tǒng)消息進行交互， 注冊成功后，雙方分別獲取對方的窗口句柄，接下來的交互通過收發(fā) wm_copydata（ windows 消息）消息完成。 wm_copydata 的 wparam 參數(shù)為發(fā)送方的窗口句柄，lparam 為指向copydatastruct 結構的指針，copydatastruct 定義如下： typedefstructt

4、agcopydatastruct ulong_ptr dwdata; dwordcbdata; pvoidlpdata; copydatastruct,*pcopydatastruct; dwdata：事件碼，標示傳送的消息事件碼 lpdata：消息參數(shù)， 采用多個相連的“類型（ 1 字節(jié)）長度 （ 4 字節(jié)）值”的格式。所有的參數(shù)類型碼表見8 參數(shù)類型碼 表 cbdata：消息參數(shù)總長度，單位字節(jié) 三、注冊的系統(tǒng)消息 第三方程序使用windowssdkregisterwindowmessage，進 行下列系統(tǒng)消息的注冊。例如： registerwindowmessage(“wm_qqapi_

5、register”); 3.1wm_qqapi_register 消息名：注冊消息 方向：設備qq wparam：發(fā)送方的窗口句柄 lparam： qqapi 版本號，目前為100，表示1.00。 第三方應用程序啟動并檢測到可用的設備后，向所有 windows 窗口廣播這個消息，帶上自己的窗口句柄作為消息參數(shù)，如下： sendmessage(hwnd_broadcast,wm_qqapi_register,發(fā)送端窗 口句柄 ,0); 當 qq 收到這個消息時，彈出“外設控制”窗口 等待用戶選擇， 如下： 3.2wm_qqapi_register_resp 消息名：注冊回復消息 方向： qq設備

6、 wparam：值如下： waiting（ 1）：等待用戶選擇 ok（ 2）：用戶選擇“允許使用” reject（ 3）：用戶選擇“禁止使用” lparam：當wparam 為 ok（ 2）時， lparam 為 qq 應用程序的窗 口句柄。 當用戶選擇“禁止使用”之后，如果第三方應用程序再次發(fā)送 wm_qqapi_register 消息， qq 不再彈出“qq 安全警告”框，直接 返回reject 的 wm_qqapi_register_resp 消息，直到qq 程序重 新啟動為止。 3.3wm_qqapi_available 消息名：qqapi 可用消息 方向： qq設備 wparam：發(fā)

7、送方的窗口句柄，即qq 程序的窗口句柄 lparam： qqapi 版本號，目前為1 當 qq 啟動后，向所有windows 窗口廣播這個消息： sendmessage(hwnd_broadcast,wm_qqapi_available,qq 窗口 句柄 ,0); 當?shù)谌綉贸绦蚴盏竭@個消息時，再發(fā)起 wm_qqapi_register 消息進行注冊。這種情況出現(xiàn)在，當?shù)谌綉?程序先啟動，而qq 程序后啟動的情況下。 四、從設備到qq 的自定義事件 4.1event_qqapi_set_audiodevice 事件說明：設置qq 使用的音頻設備 參數(shù)說明：wm_copydata 中的參數(shù)

8、copydatastruct 結構說明 詳見2 dwdata（事件碼）：10 lpdata：如下表 cbdata：消息參數(shù)總長度 參數(shù)類 型碼 長度值說明 5 設備名 長度 音頻設備名，類型：以 null 結尾的字符串 6 4 字節(jié)音頻設備的設備id 號，類 型： dword 第三方應用程序可通過音頻設備名字字符串或者通過設備 id 號，來發(fā)送設置音頻設備事件。 4.2event_qqapi_get_userinfo 事件說明：獲取qq 用戶信息 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：11 lpdata： null c

9、bdata： 0 qq 返回的用戶信息，見5.1event_qqapi_userinfo。 4.3event_qqapi_press_key 事件說明：發(fā)送按鍵消息，當用戶在設備上按下任何鍵時，發(fā)送此事 件給qq 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：12 lpdata：如下表 cbdata：消息參數(shù)總長度 參數(shù)類 型碼 長度值說明 7 1 字節(jié)鍵值，詳見“鍵值映射表” 鍵值映射表： 鍵名鍵值 00 x80 10 x81 20 x82 30 x83 40 x84 50 x85 60 x86 70 x87 80 x88

10、90 x89 down0 x8d up0 x8e clear0 x8f ok(呼叫鍵 ) 0 x91 cancel(掛斷鍵 ) 0 x92 star(*)0 x93 sharp(#)0 x94 mute(靜音鍵 ) 0 x95 ringtong(切換 鈴聲鍵 ) 0 x96 4.4event_qqapi_call 事件說明：直接呼叫一個好友用戶 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：13 lpdata：如下表 cbdata：消息參數(shù)總長度 通過qq 號呼叫： 參數(shù)類 型碼 長度值說明 1 qq 號長 度 qq 號，類型

11、：以null 結 尾的字符串 通過昵稱呼叫： 參數(shù)類 型碼 長度值說明 2 昵稱長 度 昵稱，類型：以null 結尾 的字符串 通過速播號呼叫： 參數(shù)類 型碼 長度值說明 3 速播號 長度 速播號，類型：以null 結 尾的字符串 通過pstn 號碼呼叫： 參數(shù)類 型碼 長度值說明 4 pstn 號pstn 號碼，類型：以 碼長度null 結尾的字符串 4.5event_qqapi_mute 事件說明：靜音設置，根據(jù)參數(shù)決定是打開靜音或者關閉靜音 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：14 lpdata：如下表 cbd

12、ata：消息參數(shù)總長度 參數(shù)類 型碼 長度值說明 12 1 字節(jié)靜音狀態(tài)標志。1：靜音打開； 0：靜音關閉 4.6event_qqapi_unregister 事件說明：反注冊 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：15 lpdata： null cbdata： 0 當?shù)谌綉贸绦蛲顺鰰r，向qq 發(fā)送此事件消息，qq 將音 頻設備切換回系統(tǒng)原有設備。 五、從qq 到設備的自定義事件 5.1event_qqapi_userinfo 事件說明：返回本地qq 用戶信息。對應于 4.2event_qqapi_get_user

13、info 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：16 lpdata：如下表 cbdata：消息參數(shù)總長度 參數(shù)類 型碼 長度值說明 1 qq 號長 度 qq 號，類型：以null 結尾 的字符串 2 昵稱長 度 昵稱，類型：以null 結尾 的字符串 5.2event_qqapi_status_change 事件說明：qq 上的各種狀態(tài)變化通知 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：17 lpdata：如下表 cbdata：消息參數(shù)總長度 狀態(tài)

14、變化類型說明： （ 1） dialnum 說明：撥號時的號碼變化。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 11 1 字節(jié)dialnum，狀態(tài)變換類型碼：1 1 qq 號長 度 qq 號，類型：以null 結尾 的字符串 當用戶撥號，qq 在收號時，如果號碼發(fā)生變換，例如用戶在鍵盤 上按一個號碼，或用戶在pc 上按一個號碼，或用戶按清除鍵 clear，那么，qq 向第三方程序發(fā)送此事件通知。第三方程序可通過此 事件通知來進行撥號過程中l(wèi)cd 的顯示操作。 5.3event_qqapi_shutdown 事件說明：關閉qq 應用程序 參數(shù)說明：wm_copydata 中的參數(shù)copydatas

15、truct 結構說明 詳見2 dwdata（事件碼）：18 lpdata： null cbdata： 0 當 qq 應用程序退出時，向第三方程序發(fā)送此事件消息。 六、雙向的自定義事件 6.1event_qqapi_call_status 事件說明：呼叫狀態(tài)通知 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：19 lpdata：如下表 cbdata：消息參數(shù)總長度 呼叫狀態(tài)類型說明： （ 1） connecting 方向：從qq 到設備 說明：呼出，正在等待對方應答。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)con

16、necting，呼叫狀態(tài)類型碼： 1 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword 10 1 字節(jié)通話人數(shù)，類型：char 1 qq 號長 度 qq 號，類型：以null 結尾 的字符串 2 昵稱長 度 昵稱，類型：以null 結尾 的字符串 其中，呼叫句柄為qq 分配的唯一呼叫標識符；通話人數(shù)為同時呼 出的qq 個數(shù)；接下來緊跟的2 個參數(shù)子項為被呼叫的qq 好友信 息，如果被呼叫的qq 好友有多個，則有多個qq 好友信息。 回鈴音由qq 控制播放。 （ 2） ring 方向：從qq 到設備 說明：呼入，振鈴。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)ri

17、ng，呼叫狀態(tài)類型碼：2 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword 1 qq 號長 度 qq 號，類型：以null 結尾 的字符串 2 昵稱長 度 昵稱，類型：以null 結尾 的字符串 4（可 選） pstn 號 碼長度 pstn 號碼，類型：以null 結尾的字符串 其中，呼叫句柄為qq 分配的唯一呼叫標識符；接下來的2 個參數(shù)子項為呼入qq 好友信息；最后一個參數(shù)項為可選項，呼出的 pstn 號碼，該號碼直接由呼叫方指定，本地qq 完成呼叫轉移，轉 到 pstn 號碼上。如果ringing 帶了 “呼出的pstn 號碼 ”，則本 地不振鈴，直接轉移呼出；如果ri

18、nging 沒帶 “呼出的pstn 號 碼 ”，則本地振鈴。 （ 3） busy（針對轉接盒設備） 方向：雙向 說明：占線。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)busy，呼叫狀態(tài)類型碼：3 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword 從 qq 到設備：呼出，等待對方應答，且當對方的設備被 pstn 占用時，則qq 向本地設備發(fā)送占線狀態(tài)。 從設備到qq：呼入，本地振鈴，且當本地設備被pstn 占用 時，則本地設備向qq 發(fā)送占線狀態(tài)。 （ 4） accept 方向：從qq 到設備 說明：呼入或呼出，某方接受，雙方進入通話狀態(tài)。參數(shù)子項依次為： 參數(shù)類

19、 型碼 長度值說明 8 1 字節(jié)accept，呼叫狀態(tài)類型碼： 4 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword （ 5） reject 方向：從qq 到設備 說明：呼入或呼出，某方拒絕。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)reject，呼叫狀態(tài)類型碼： 5 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword （ 6） finish 方向：從qq 到設備 說明：呼入或呼出，通話結束，無論哪方發(fā)起。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)finish，呼叫狀態(tài)類型碼： 6 9 4 字節(jié)呼叫句柄（callhandle）， 類

20、型： dword （ 7） fail 方向：從qq 到設備 說明：呼出失敗。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)fail，呼叫狀態(tài)類型碼：7 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword 失敗原因可能是，呼叫的用戶不是qq 好友。 （ 8） hold（針對轉接盒設備） 方向：從設備到qq 說明：暫停通話，通話被切換到pstn。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)hold，呼叫狀態(tài)類型碼：8 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword （ 9） resume（針對轉接盒設備） 方向：從設備到qq 說明：恢復通話

21、，通話被切換到回qq。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)resume，呼叫狀態(tài)類型碼： 9 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword （ 10） mute 方向：從qq 到設備 說明：靜音狀態(tài)通知。參數(shù)子項依次為： 參數(shù)類 型碼 長度值說明 8 1 字節(jié)mute，呼叫狀態(tài)類型碼：10 9 4 字節(jié)呼叫句柄（callhandle）， 類型： dword 12 1 字節(jié)靜音狀態(tài)標志。1：靜音打開； 0：靜音關閉 七、錯誤碼定義 7.1 從 qq 到設備 event_qqapi_error 事件說明：從qq 到設備的錯誤通知 參數(shù)說明：wm_copydata 中的參數(shù)copydatastruct 結構說明 詳見2 dwdata（事件碼）：20 lpdata：如下表 cbdata：消息參數(shù)總長度 參數(shù)類 型碼 長度值說明 1