QQ API設計說明書目錄一、引言??? 31.1 編寫目的??? 31.2 更新時間??? 3二、總體設計??? 3三、注冊的系統消息??? 33.1 WM_QQAPI_REGISTER??? 33.2 WM_QQAPI_REGISTER_RESP??? 43.3 WM_QQAPI_AVAILABLE??? 4四、從設備到QQ的自定義事件??? 54.1 EVENT_QQAPI_SET_AUDIODEVICE??? 54.2 EVENT_QQAPI_GET_USERINFO??? 54.3 EVENT_QQAPI_PRESS_KEY??? 54.4 EVENT_QQAPI_CALL??? 64.5 EVENT_QQAPI_MUTE??? 64.6 EVENT_QQAPI_UNREGISTER??? 7五、從QQ到設備的自定義事件??? 75.1 EVENT_QQAPI_USERINFO??? 75.2 EVENT_QQAPI_STATUS_CHANGE??? 75.3 EVENT_QQAPI_SHUTDOWN??? 8六、雙向的自定義事件??? 86.1 EVENT_QQAPI_CALL_STATUS??? 8七、錯誤碼定義??? 107.1 從QQ到設備――EVENT_QQAPI_ERROR??? 10八、參數類型碼表??? 11 一、引言1.1 編寫目的本文檔提供了QQ API接口說明，以供第三方應用程序使用，用于QQ和硬件設備（例如USB Phone）的交互。1.2 更新時間最后修訂日期：2005-05-24版本號：v1.0二、總體設計QQ應用程序和第三方應用程序以收發消息的方式進行通訊。雙方未成功注冊之前，采用RegisterWindowMessage（Windows API）注冊的系統消息進行交互，注冊成功后，雙方分別獲取對方的窗口句柄，接下來的交互通過收發WM_COPYDATA（Windows消息）消息完成。WM_COPYDATA的wParam參數為發送方的窗口句柄，lParam為指向COPYDATASTRUCT結構的指針，COPYDATASTRUCT定義如下：typedef struct tagCOPYDATASTRUCT{????? ULONG_PTR??? dwData;????? DWORD???????? cbData;????? PVOID???????? lpData;}COPYDATASTRUCT, *PCOPYDATASTRUCT;dwData：事件碼，標示傳送的消息事件碼lpData：消息參數，采用多個相連的“類型（1字節）＋長度（4字節）＋值”的格式。所有的參數類型碼表見8 參數類型碼表cbData：消息參數總長度，單位字節三、注冊的系統消息第三方程序使用Windows SDK――RegisterWindowMessage，進行下列系統消息的注冊。例如：RegisterWindowMessage(“WM_QQAPI_REGISTER”);3.1 WM_QQAPI_REGISTER消息名：注冊消息方向：設備?QQwParam：發送方的窗口句柄lParam：QQ API版本號，目前為100，表示1.00。第三方應用程序啟動并檢測到可用的設備后，向所有Windows窗口廣播這個消息，帶上自己的窗口句柄作為消息參數，如下：SendMessage( HWND_BROADCAST, WM_QQAPI_REGISTER, 發送端窗口句柄, 0);當QQ收到這個消息時，彈出“外設控制”窗口等待用戶選擇，如下： 3.2 WM_QQAPI_REGISTER_RESP消息名：注冊回復消息方向：QQ?設備wParam：值如下：WAITING（1）：等待用戶選擇OK（2）：用戶選擇“允許使用”REJECT（3）：用戶選擇“禁止使用”lParam：當wParam為OK（2）時，lParam為QQ應用程序的窗口句柄。當用戶選擇“禁止使用”之后，如果第三方應用程序再次發送WM_QQAPI_REGISTER消息，QQ不再彈出“QQ安全警告”框，直接返回REJECT的WM_QQAPI_REGISTER_RESP消息，直到QQ程序重新啟動為止。3.3 WM_QQAPI_AVAILABLE消息名：QQ API可用消息方向：QQ?設備wParam：發送方的窗口句柄，即QQ程序的窗口句柄lParam：QQ API版本號，目前為1當QQ啟動后，向所有Windows窗口廣播這個消息：SendMessage( HWND_BROADCAST, WM_QQAPI_AVAILABLE, QQ窗口句柄, 0);當第三方應用程序收到這個消息時，再發起WM_QQAPI_REGISTER消息進行注冊。這種情況出現在，當第三方應用程序先啟動，而QQ程序后啟動的情況下。四、從設備到QQ的自定義事件4.1 EVENT_QQAPI_SET_AUDIODEVICE事件說明：設置QQ使用的音頻設備參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：10lpData：如下表cbData：消息參數總長度參數類型碼??? 長度??? 值說明5??? 設備名長度??? 音頻設備名，類型：以Null結尾的字符串6??? 4字節??? 音頻設備的設備ID號，類型：DWORD第三方應用程序可通過音頻設備名字字符串或者通過設備ID號，來發送設置音頻設備事件。4.2 EVENT_QQAPI_GET_USERINFO事件說明：獲取QQ用戶信息參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：11lpData：NULLcbData：0QQ返回的用戶信息，見5.1 EVENT_QQAPI_USERINFO。4.3 EVENT_QQAPI_PRESS_KEY事件說明：發送按鍵消息，當用戶在設備上按下任何鍵時，發送此事件給QQ參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：12lpData：如下表cbData：消息參數總長度參數類型碼??? 長度??? 值說明7??? 1字節??? 鍵值，詳見“鍵值映射表” 鍵值映射表：鍵名??? 鍵值0??? 0x801??? 0x812??? 0x823??? 0x834??? 0x845??? 0x856??? 0x867??? 0x878??? 0x889??? 0x89Down??? 0x8DUp??? 0x8EClear??? 0x8FOK (呼叫鍵)??? 0x91Cancel (掛斷鍵)??? 0x92STAR (*)??? 0x93SHARP (#)??? 0x94Mute (靜音鍵)??? 0x95RINGTONG (切換鈴聲鍵)??? 0x964.4 EVENT_QQAPI_CALL事件說明：直接呼叫一個好友用戶參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：13lpData：如下表cbData：消息參數總長度通過QQ號呼叫：參數類型碼??? 長度??? 值說明1??? QQ號長度??? QQ號，類型：以Null結尾的字符串通過昵稱呼叫：參數類型碼??? 長度??? 值說明2??? 昵稱長度??? 昵稱，類型：以Null結尾的字符串通過速播號呼叫：參數類型碼??? 長度??? 值說明3??? 速播號長度??? 速播號，類型：以Null結尾的字符串通過PSTN號碼呼叫：參數類型碼??? 長度??? 值說明4??? PSTN號碼長度??? PSTN號碼，類型：以Null結尾的字符串4.5 EVENT_QQAPI_MUTE事件說明：靜音設置，根據參數決定是打開靜音或者關閉靜音參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：14lpData：如下表cbData：消息參數總長度參數類型碼??? 長度??? 值說明12??? 1字節??? 靜音狀態標志。1：靜音打開；0：靜音關閉4.6 EVENT_QQAPI_UNREGISTER事件說明：反注冊參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：15lpData：NULLcbData：0當第三方應用程序退出時，向QQ發送此事件消息，QQ將音頻設備切換回系統原有設備。五、從QQ到設備的自定義事件5.1 EVENT_QQAPI_USERINFO事件說明：返回本地QQ用戶信息。對應于4.2 EVENT_QQAPI_GET_USERINFO參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：16lpData：如下表cbData：消息參數總長度參數類型碼??? 長度??? 值說明1??? QQ號長度??? QQ號，類型：以Null結尾的字符串2??? 昵稱長度??? 昵稱，類型：以Null結尾的字符串5.2 EVENT_QQAPI_STATUS_CHANGE事件說明：QQ上的各種狀態變化通知參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：17lpData：如下表cbData：消息參數總長度狀態變化類型說明：（1）??? DIALNUM說明：撥號時的號碼變化。參數子項依次為：參數類型碼??? 長度??? 值說明11??? 1字節??? DIALNUM，狀態變換類型碼：11??? QQ號長度??? QQ號，類型：以Null結尾的字符串當用戶撥號，QQ在收號時，如果號碼發生變換，例如用戶在鍵盤上按一個號碼，或用戶在PC上按一個號碼，或用戶按清除鍵Clear，那么，QQ向第三方程序發送此事件通知。第三方程序可通過此事件通知來進行撥號過程中LCD的顯示操作。5.3 EVENT_QQAPI_SHUTDOWN事件說明：關閉QQ應用程序參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：18lpData：NULLcbData：0當QQ應用程序退出時，向第三方程序發送此事件消息。六、雙向的自定義事件6.1 EVENT_QQAPI_CALL_STATUS事件說明：呼叫狀態通知參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：19lpData：如下表cbData：消息參數總長度呼叫狀態類型說明：（1）CONNECTING方向：從QQ到設備說明：呼出，正在等待對方應答。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? CONNECTING，呼叫狀態類型碼：19??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD10??? 1字節??? 通話人數，類型：char1??? QQ號長度??? QQ號，類型：以Null結尾的字符串2??? 昵稱長度??? 昵稱，類型：以Null結尾的字符串其中，呼叫句柄為QQ分配的唯一呼叫標識符；通話人數為同時呼出的QQ個數；接下來緊跟的2個參數子項為被呼叫的QQ好友信息，如果被呼叫的QQ好友有多個，則有多個QQ好友信息。回鈴音由QQ控制播放。（2）RING方向：從QQ到設備說明：呼入，振鈴。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? RING，呼叫狀態類型碼：29??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD1??? QQ號長度??? QQ號，類型：以Null結尾的字符串2??? 昵稱長度??? 昵稱，類型：以Null結尾的字符串4（可選）??? PSTN號碼長度??? PSTN號碼，類型：以Null結尾的字符串其中，呼叫句柄為QQ分配的唯一呼叫標識符；接下來的2個參數子項為呼入QQ好友信息；最后一個參數項為可選項，呼出的PSTN號碼，該號碼直接由呼叫方指定，本地QQ完成呼叫轉移，轉到PSTN號碼上。如果RINGING帶了“呼出的PSTN號碼”，則本地不振鈴，直接轉移呼出；如果RINGING沒帶“呼出的PSTN號碼”，則本地振鈴。（3）BUSY（針對轉接盒設備）方向：雙向說明：占線。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? BUSY，呼叫狀態類型碼：39??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD從QQ到設備：呼出，等待對方應答，且當對方的設備被PSTN占用時，則QQ向本地設備發送占線狀態。從設備到QQ：呼入，本地振鈴，且當本地設備被PSTN占用時，則本地設備向QQ發送占線狀態。（4）ACCEPT方向：從QQ到設備說明：呼入或呼出，某方接受，雙方進入通話狀態。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? ACCEPT，呼叫狀態類型碼：49??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD （5）REJECT方向：從QQ到設備說明：呼入或呼出，某方拒絕。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? REJECT，呼叫狀態類型碼：59??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD （6）FINISH方向：從QQ到設備說明：呼入或呼出，通話結束，無論哪方發起。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? FINISH，呼叫狀態類型碼：69??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD （7）FAIL方向：從QQ到設備說明：呼出失敗。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? FAIL，呼叫狀態類型碼：79??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD失敗原因可能是，呼叫的用戶不是QQ好友。（8）HOLD（針對轉接盒設備）方向：從設備到QQ說明：暫停通話，通話被切換到PSTN。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? HOLD，呼叫狀態類型碼：89??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD （9）RESUME（針對轉接盒設備）方向：從設備到QQ說明：恢復通話，通話被切換到回QQ。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? RESUME，呼叫狀態類型碼：99??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD （10）MUTE方向：從QQ到設備說明：靜音狀態通知。參數子項依次為：參數類型碼??? 長度??? 值說明8??? 1字節??? MUTE，呼叫狀態類型碼：109??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD12??? 1字節??? 靜音狀態標志。1：靜音打開；0：靜音關閉七、錯誤碼定義7.1 從QQ到設備――EVENT_QQAPI_ERROR事件說明：從QQ到設備的錯誤通知參數說明：WM_COPYDATA中的參數COPYDATASTRUCT結構說明詳見2dwData（事件碼）：20lpData：如下表cbData：消息參數總長度參數類型碼??? 長度??? 值說明12??? 1字節??? 錯誤類型，類型：char錯誤碼定義：八、參數類型碼表參數類型碼??? 長度??? 值說明1??? QQ號長度??? QQ號，類型：以Null結尾的字符串2??? 昵稱長度??? 昵稱，類型：以Null結尾的字符串3??? 速播號長度??? 速播號，類型：以Null結尾的字符串4??? PSTN號碼長度??? PSTN號碼，類型：以Null結尾的字符串5??? 設備名長度??? 音頻設備名，類型：以Null結尾的字符串6??? 4字節??? 音頻設備的設備ID號，類型：DWORD7??? 1字節??? 鍵值，詳見4.3的“鍵值映射表”8??? 1字節??? 呼叫狀態的類型，類型：char，主要有：（1）CONNECTING，呼叫狀態類型碼：1（2）RING，呼叫狀態類型碼：2（3）BUSY，呼叫狀態類型碼：3（4）ACCEPT，呼叫狀態類型碼：4（5）REJECT，呼叫狀態類型碼：5（6）FINISH，呼叫狀態類型碼：6（7）FAIL，呼叫狀態類型碼：7（8）HOLD，呼叫狀態類型碼：8（9）RESUME，呼叫狀態類型碼：9（10）MUTE，呼叫狀態類型碼：109??? 4字節??? 呼叫句柄（CallHandle），類型：DWORD10??? 1字節??? 通話人數，類型：char注：通話人數會影響后續的參數子項，例如當通話人數為2，后面會跟兩份的QQ用戶信息。11??? 1字節??? 狀態變換的類型，類型：char，主要有：（1）DIALNUM，狀態變換類型碼：112??? 1字節??? 靜音狀態標志。1：靜音打開；0：靜音關閉13??? 1字節??? 錯誤類型，類型：char文章引用自：