API 设计说明书深圳腾讯计算机系统有限公司目录一、引言 . 311 编写目的 . 312 更新时间 . 3二、总体设计 . 3三、注册的系统消息 . . 33.1 WM_API_REGISTER . 332 WM_API_REGISTER_RESP . 43.3 WM_API_A VAILABLE . 4四、从设备到 的自定义事件 . . 541 EVENT_API_SET_AUDIODEVICE . 542 EVENT_API_GET_USERINFO . 543 EVENT_API_PRESS_KEY . 544 EVENT_API_CALL . 645 EVENT_API_MUTE . 646 EVENT_API_UNREGISTER . 7五、从 到设备的自定义事件 . . 75.1 EVENT_API_USERINFO . 75.2 EVENT_API_STA TUS_CHANGE . 75.3 EVENT_API_SHUTDOWN . 7六、双向的自定义事件. . 86.1 EVENT_API_CALL_STATUS . 8七、错误码定义 . 1071 从 到设备 EVENT_API_ERROR . 10八、参数类型码表 . 10一、引言1.1 编写目的本文档提供了 API 接口说明，以供第三方应用程序使用，用于 和硬件设备（例如USB Phone）的交互 . 1.2 更新时间最后修订日期:2005 05-24 版本号 :v1.0 二、总体设计 应用程序和第三方应用程序以收发消息的方式进行通讯. 双方未成功注册之前,采用 RegisterWindowMessage（Windows API)注册的系统消息进行交互，注册成功后，双方分别获取对方的窗口句柄，接下来的交互通过收发WM_COPYDA TA（Windows 消息）消息完成. WM_COPYDATA的 wParam 参数为发送方的窗口句柄，lParam 为指向 COPYDATASTRUCT结构的指针， COPYDATASTRUCT定义如下：typedef struct tagCOPYDATASTRUCTULONG_PTR dwData；DWORD cbData; PVOID lpData；COPYDATASTRUCT, PCOPYDATASTRUCT; dwData：事件码，标示传送的消息事件码lpData：消息参数，采用多个相连的“ 类型（ 1 字节）长度（ 4 字节）值 ” 的格式 .所有的参数类型码表见 8 参数类型码表cbData：消息参数总长度,单位字节三、注册的系统消息第 三 方 程 序 使 用Windows SDK Regis terWindowMessage ， 进 行 下 列 系 统 消 息 的 注 册 。
例如:RegisterWindowMessage （“WM_API_REGISTER”)；31 WM_API_REGISTER 消息名 :注册消息方向：设备 wParam：发送方的窗口句柄lParam: API 版本号，目前为100，表示 100. 第三方应用程序启动并检测到可用的设备后，向所有Windows 窗口广播这个消息,带上自己的窗口句柄作为消息参数，如下：SendMessage( HWND_BROADCAST， WM_API_REGISTER, 发送端窗口句柄, 0） ；当 收到这个消息时，弹出“ 外设控制 ” 窗口等待用户选择，如下：3.2 WM_API_REGISTER_RESP 消息名：注册回复消息方向： 设备wParam：值如下：WAITING （1） ：等待用户选择OK(2 ） ：用户选择 “ 允许使用 ”REJECT（3） ：用户选择 “ 禁止使用 ”lParam:当 wParam 为 OK （2)时， lParam 为 应用程序的窗口句柄当用户选择 “ 禁止使用 ” 之后，如果第三方应用程序再次发送WM_API_REGISTER消息 , 不再弹出“安全警告 ” 框，直接返回REJECT 的 WM_API_REGISTER_RESP消息，直到 程序重新启动为止 . 3。
3 WM_API_A VAILABLE 消息名： API 可用消息方向 :设备wParam：发送方的窗口句柄，即 程序的窗口句柄lParam： API 版本号，目前为1 当 启动后，向所有Windows 窗口广播这个消息：SendMessage（ HWND_BROADCAST, WM_API_AVAILABLE, 窗口句柄 , 0）; 当第三方应用程序收到这个消息时,再发起 WM_API_REGISTER消息进行注册.这种情况出现在,当第三方应用程序先启动，而 程序后启动的情况下四、从设备到 的自定义事件41 EVENT_API_SET_AUDIODEVICE 事件说明：设置 使用的音频设备参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码） :10 lpData：如下表cbData：消息参数总长度参数类型码长度值说明5 设备名长度音频设备名，类型：以Null 结尾的字符串6 4 字节音频设备的设备ID 号，类型： DWORD 第三方应用程序可通过音频设备名字字符串或者通过设备ID 号，来发送设置音频设备事件2 EVENT_API_GET_USERINFO 事件说明：获取 用户信息参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码）：11 lpData：NULL cbData:0 返回的用户信息，见5.1 EVENT_API_USERINFO. 4。
3 EVENT_API_PRESS_KEY 事件说明：发送按键消息，当用户在设备上按下任何键时,发送此事件给 参数说明 :WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2 dwData( 事件码 )：12 lpData: 如下表cbData：消息参数总长度参数类型码长度值说明7 1 字节键值，详见 “ 键值映射表 ”键值映射表：键名键值0 0 x80 1 0 x81 2 0 x82 3 0 x83 4 0 x84 5 0 x85 6 0 x86 7 0 x87 8 0 x88 9 0 x89 Down 0 x8D Up 0 x8E Clear 0 x8F OK ( 呼叫键）0 x91 Cancel (挂断键 ) 0 x92 STAR （）0 x93 SHARP （#) 0 x94 Mute (静音键 ) 0 x95 RINGTONG ( 切换铃声键 ) 0 x96 44 EVENT_API_CALL 事件说明：直接呼叫一个好友用户参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码）：13 lpData：如下表cbData：消息参数总长度通过 号呼叫 : 参数类型码长度值说明1 号长度 号，类型：以Null 结尾的字符串通过昵称呼叫：参数类型码长度值说明2 昵称长度昵称，类型：以Null 结尾的字符串通过速播号呼叫：参数类型码长度值说明3 速播号长度速播号，类型：以Null 结尾的字符串通过 PSTN 号码呼叫 : 参数类型码长度值说明4 PSTN 号码长度PSTN 号码，类型 :以 Null 结尾的字符串4.5 EVENT_API_MUTE 事件说明：静音设置，根据参数决定是打开静音或者关闭静音参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码 ):14 lpData：如下表cbData：消息参数总长度参数类型码长度值说明12 1 字节静音状态标志。
1:静音打开； 0:静音关闭4.6 EVENT_API_UNREGISTER 事件说明：反注册参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData( 事件码 )：15 lpData：NULL cbData： 0 当第三方应用程序退出时，向 发送此事件消息, 将音频设备切换回系统原有设备五、从 到设备的自定义事件51 EVENT_API_USERINFO 事件说明：返回本地 用户信息对应于42 EVENT_API_GET_USERINFO 参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码 )：16 lpData：如下表cbData：消息参数总长度参数类型码长度值说明1 号长度 号，类型：以Null 结尾的字符串2 昵称长度昵称，类型 :以 Null 结尾的字符串52 EVENT_API_STATUS_CHANGE 事件说明 : 上的各种状态变化通知参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData （事件码 ):17 lpData：如下表cbData：消息参数总长度状态变化类型说明：（1）DIALNUM 说明：拨号时的号码变化。
参数子项依次为：参数类型码长度值说明11 1 字节DIALNUM,状态变换类型码：1 1 号长度 号，类型 :以 Null 结尾的字符串当用户拨号， 在收号时，如果号码发生变换，例如用户在键盘上按一个号码，或用户在PC上按一个号码,或用户按清除键Clear，那么， 向第三方程序发送此事件通知.第三方程序可通过此事件通知来进行拨号过程中LCD 的显示操作3 EVENT_API_SHUTDOWN 事件说明：关闭 应用程序参数说明 :WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2 dwData( 事件码）：18 lpData：NULL cbData： 0 当 应用程序退出时,向第三方程序发送此事件消息六、双向的自定义事件6.1 EVENT_API_CALL_STATUS 事件说明 :呼叫状态通知参数说明： WM_COPYDA TA 中的参数COPYDA TASTRUCT 结构说明详见2 dwData( 事件码）：19 lpData：如下表cbData：消息参数总长度呼叫状态类型说明：（1）CONNECTING 方向：从 到设备说明：呼出，正在等待对方应答参数子项依次为: 参数类型码长度值说明8 1 字节CONNECTING ，呼叫状态类型码：1 9 4 字节呼叫句柄（ CallHandle ） ，类型： DWORD 10 1 字节通话人数，类型：char 1 号长度 号，类型：以Null 结尾的字符串2 昵称长度昵称，类型 :以 Null 结尾的字符串其中，呼叫句柄为 分配的唯一呼叫标识符；通话人数为同时呼出的 个数；接下来紧跟的 2 个参数子项为被呼叫的 好友信息， 如果被呼叫的 好友有多个， 则有多个 好友信息。
回铃音由 控制播放 . （2)RING 方向：从 到设备说明：呼入，振铃参数子项依次为: 参数类型码长度值说明8 1 字节RING ，呼叫状态类型码:2 9 4 字节呼叫句柄 (CallHandle ） ，类型： DWORD 1 号长度 号，类型：以Null 结尾的字符串2 昵称长度昵称，类型 :以 Null 结尾的字符串4(可选）PSTN 号码长度PSTN 号码，类型：以Null 结尾的字符串其中，呼叫句柄为 分配的唯一呼叫标识符；接下来的2 个参数子项为呼入 好友信息；最后。