USB盒控件开发文档.doc

phonic_usb.ocx控件开发接口(一) 简介USB盒控件名字是phonic_usb.ocx，要使用控件必须先注册，包括动态库一起，也可以直接运行setup.bat批处理文件，自动帮你注册到系统目录下。该接口支持下面几种类型的产品，统一用此接口。Fi3001B 1路USB录音盒 (phonic_ubox.dll, phonic_utool.dll)Fi3101A 带耳麦的USB语音盒（1外1内）(phonic_ubox.dll,phonic_utoolI.dll)Fi3002B 2路USB录音盒 (phonic_ubox.dll, phonic_utoolII.dll)Fi3102A 2路USB 外线 (phonic_ubox.dll, phonic_utoolII.dll) 上面括号内表示：除了需要phonic_usb.ocx外，应用程序必须依赖的库的文件。Fi3002B有两个版本，版本号为6.060支持测量电压功能，低于该版本的硬件不支持测量线路电压功能。其简单开发流程：1. 先调用OpenDevice函数；2. 如果USB录音盒设备已插入，会有设备插入事件通知上层程序；3. 电话摘机，振铃，挂机、按键和主叫号码都会有事件通知上层程序；4. 电话录音一般在摘机开始录音，调用RecordFile函数，挂机停止录音；5. 程序退出，最后调用CloseDevice()关闭设备，底层程序才会关闭。(二) 控件事件PlugIn 设备插入PLugIn(long uboxHandle)功 能：设备插入参 数： uboxHandle设备句柄 不同USB盒的句柄并不是连续的，但对于2路的盒子，其线路1和线路2的句柄值是相邻的。PlugOut 设备拨出PlugOut（long uboxHandle） 功 能：设备拨出。参 数：uboxHandle设备句柄 DeviceAlarm 报警DeviceAlarm（long uboxHandle，long param） 功 能：设备报警，软件要重新启动，否则不能录音和放音。参 数：uboxHandle设备句柄 param如下所示： UBOX_ALARM_CAN_FIND_MIC = 1,未能找到ubox 的MIC 设备 UBOX_ALARM_CAN_OPEN_MIC = 2,未能打开ubox 的MIC 设备 UBOX_ALARM_CAN_OPEN_PLAY = 3, 未能打开ubox 的放音设备 UBOX_ALARM_DEVICE_ERROR = 4,设备故障DeviceError 设备错误DeviceError (long uboxHandle)功 能：设备错误。参 数：uboxHandle设备句柄，Ring 振铃Ring（long uboxHandle） 功 能：电话振铃。参 数：uboxHandle设备句柄 对于Fi3101A，可以在振铃调用OpenBuzzerSwitch(uboxHandle,true)方法打开蜂鸣器，通知用户来电，在事件HookOff或者RingCancel下调用OpenBuzzerSwitch(uboxHandle,false)关闭蜂鸣器，。RingStop 停振事件RingStop (long uboxHandle)功 能：通知应用程序通道停振。参 数：uboxHandle设备句柄，说 明： 电话机振铃一般是振1秒，停振4秒的一个周期。RingCancle 振铃取消RingCancel (long uboxHandle)功 能：振铃取消，当末次振铃停止超过6秒，则触发此事件。未接电话可通过该事件判断参 数：uboxHandle设备句柄HookOff 摘机HookOff（long uboxHandle, long param1）功 能：电话摘机。参 数：uboxHandle设备句柄 Param1 = 0,表示电话机摘机 Param1 6，表示反向摘机，指软件摘机 Param1 = 7, 表示正向摘机，指软件摘机Hangup 挂机HangUp（long uboxHandle）功 能：电话挂机。参 数：uboxHandle设备句柄 HangIng 悬空 HangIng(long uboxHandle)功 能：线路悬空，线路接口没有连接好。参 数：uboxHandle设备句柄说 明： 只有Fi3001才有这个功能，如果电话线被拨掉，先触发摘机事件 ，经过20-30秒后再触发悬空事件。LineVoltage 线路电压事件LineVoltage（ long uboxHandle, long voltage）功 能：通知应用程序线路电压。参 数：uboxHandle设备句柄， Voltage ：线路电压值说 明: Fi3001有这个功能,调用ubox_start_read_line_voltage（）后，才会触发本事件，触发间隔是200ms ,只有调用ubox_stop_read_line_voltage（）才会停止触发这个事件。 Fi3002B V6.060版本也支持量电压功能，调用一次ubox_start_read_line_voltage（）产生一次线路电压事件。对于Fi3002B V6.060 ubox_start_read_line_voltage（）返回值也是线路电压，线路电压可以不用从这个事件获取，可以不用调用ubox_stop_read_line_voltage()函数。StreamVoice 流式录音事件StreamVoice(long uboxHandle, short FAR* pVoice，short size)功 能：通知应用程序流式录音数据包送到。参 数：uboxHandle设备句柄， pVoice：指向语音数据， size : 语音数据的大小说 明：要触发该事件必要调用RecordStream(long uboxHandle, short coder)方法调用Short StopRecord(long uboxHandle)停止触发该事件。 录音数据每隔20ms发送数据包，可以用于网络录音和录音监听。CallID事件 来电号码CallID(long uboxHandle, LPCTSTR callerNumber, LPCTSTR callerTime, LPCTSTR callerName)功 能：通知应用程序来电号码。参 数：uboxHandle 设备句柄，callerNumber号码 callerTime 时间 callerName 姓名 DtmfKey事件 用户按键DtmfKey (long uboxHandle, long dtmfCode)功 能：通知应用程序用户按键。参 数：uboxHandle设备句柄，dtmfCode是按键键值，需要类型转换 char dtmf = (char) dtmfCode。PlayEnd 放音结束PlayEnd (long uboxHandle)功 能：通知应用程序通道放音完毕。参 数：uboxHandle设备句柄，PlayError 放音错误PlayError (long uboxHandle)功 能：放音错误。参 数：uboxHandle设备句柄，ToneBusy 忙音事件ToneBusy (long uboxHandle)功 能：检测到忙音，表示判断对方已经挂机了。参 数：uboxHandle设备句柄，CallOutFinish 拨号完成事件CallOutFinish(long uboxHandle)功 能：拨号完成参 数：uboxHandle设备句柄，Polarity 极性检测事件Polarity (long uboxHandle, short lineSign)功 能：通知应用程序通知应用程序检测到极性反转。参 数：uboxHandle设备句柄，lineSign 正极，反极说 明: 极性检测用于外线呼出后对方摘机的判断以及通话过程中对方挂机的判断。极性反转的功能必须向电信部门另外申请。(三) 函数错误返回值UBOX_ERR_SUCCESS = 0, 操作成功UBOX_ERR_SYSTEM = -1, 系统错误，调用操作系统(windows)的方法时出现错误，错误的详细信息可查看日志文件： UBOX_ERR_DEVICE_NOT_FOUND= -2, 没有这个设备，可能设备已经被拔出UBOX_ERR_INVALID_HANDLE= -3, 不合法的UBOX_HANDLEUBOX_ERR_INVALID_PARAMETER= -4, 不合法的输入参数UBOX_ERR_EXCEPTION= -5, 发生异常UBOX_ERR_INVALID_WORK_MODE= -6, 错误的工作模式UBOX_ERR_UBOX_NOT_OPEN= -7, ubox设备尚未打开UBOX_ERR_CANNOT_CREATE_DIR= -10, 未能创建目录，当指定录音时，如果文件名包含目录路径，则ubox将试图建立相应的目录树。UBOX_ERR_CANNOT_CREATE_FILE= -11, 未能创建录音文件UBOX_ERR_INVALID_VOICE_CODER= -12, 不支持的语音编码UBOX_ERR_DEVICE_BUSY= -13, 设备忙，当设备已经在录音的时候再次指示其同类型(文件与文件、STREAM与STREAM)的录音，就会返回此错误码(四) 控件方法long OpenDevice(short workmode) 初始化语音设备功 能：初始化USB设备，设备是否打开成功不是由它决定的，设备打开成功由事件PLugIn通知的。参 数：workmode0，为录音模式就可以了。 Workmode 1诊断模式，用于捕获线路信息，供信号分析之用，支持的语音编码方式CODER_PCMWorkmode 2,配置模式返 回: 0成功，错误参照“函数错误返回值 ”相关方法：CloseDevice() 说明：只有Fi3001B配置模式才有用，下面有几个方法要在配置模式下使用。void CloseDevice() 关闭设备功 能：关闭设备；说 明：关闭设备是一切的结束。short GetProductID(long uboxHandle); 获取产品设备号功 能：获取产品设备号参 数：uboxHandle 设备句柄返 回: 对应的产品设备号： 1 FI3102A2 FI3002B3 FI3001B4 FI3101AFloat GetDeviceVersionNum (long uboxHandle) 获取设备版本号 功 能：在接收到设备插入事件后，才可以获取硬件的版本号参 数： uboxHandle设备句柄返 回：设备版本号，返回值为0.0获取失败 其它值，整数部分是主版本号，小数部分是次版本号Short GetUsernum(long uboxHandle, short FAR* user_num, short len) 读用户号 功 能：读取用户号。参 数：uboxHandle： 设备句柄 user_num： 读取数据的地址 len: 读取数据长度，长度为16返 回: 成功返回用户号的长度，错误返回为非0说 明: 卖给同一个客户的所有的USB盒的用户号是相同的,一般USB盒出厂时,不写用户号,如果需要用户号请联系我公司，CString GerUsernumex(long uboxHandle) 读用户号 功 能：读取用户号。其功能和GetUsernum一样, 是为有些语言不支持指针,方便用户调用.参 数：uboxHandle： 设备句柄说 明: 卖给同一个客户的所有的USB盒的用户号是相同的,一般USB盒出厂时,不写用户号,如果需要用户号请联系我公司，short GetWorkMode () 获取工作模式功 能：获取工作模式；返 回：USB盒的工作模式,有以下模式： UBOX_MODE_RECORD = 0 , 录音模式，通常使用的模式UBOX_MODE_DIAG = 1, 诊断模式，用于捕获线路信息，供信号分析之用，支持的语音编码方式是CODER_PCM UBOX_MODE_CONFIG = 2, 配置模式Short CheckVoiceCoder(short voicecoder) 获取工作模式功 能：检查指定的语音编码是否合法返 回：0 语音编码是合法的，UBOX_ERR_INVALID_VOICE_CODER 语音编码不合法short RecordFile(long uboxHandle, LPCTSTR filename, short coder) 录音到文件功 能：录音到文件参 数：uboxHandle 设备句柄filename 文件名 coder 录音编码率,支持以下编码： coder 0 CODER_ALAWcoder 1 CODER_PCMcoder 3 CODER_G729coder 20 CODER_SPEEX /这是8倍压缩，安装speexw.exe的插件，播放器就可以播放了coder = 38 mp3编码 coder100 CODER_ULAW一般推荐用CODER_ALAW,mp3和CODER_SPEEX编码。 选择mp3编码格式的,文件名后缀为.mp3,其它格式推荐使用.wav后缀返 回: 0成功，错误参照“函数错误返回值 ”Short RecordStream(long uboxHandle,short coder) 流式录音 功 能：流式录音；参 数：uboxHandle设备句柄coder 录音编码率,支持以下编码： coder 0 CODER_ALAWcoder 1 CODER_PCMcoder 3 CODER_G729coder 20 CODER_SPEEX /这是8倍压缩，安装speexw.exe的插件，播放器就可以播放了coder = 38 mp3编码 coder100 CODER_ULAW返 回: 0成功，错误参照“函数错误返回值 ”Short StopRecord(long uboxHandle) 停止录音 功 能：停止录音 包括对文件和流式录音停止参 数：uboxHandle设备句柄返 回: 0成功，错误参照“函数错误返回值 ”Short GetHangThreshold(longuboxHandle) 读取悬空门限值功 能：读取悬空门限值参 数：uboxHandle设备句柄返 回：0 该返回值就是悬空门限值 0失败，说明：产品Fi3001B和 Fi3002B V6.060版本调用这个函数才有意义。Short SetHangThreshold(long uboxHandle, short threshold) 设置悬空门限值 功 能：设置悬空门限值参 数： uboxHandle 设备句柄Threshold 悬空门限值，默认threshold3V。返 回：0成功 0 该返回值就是摘机门限值 0失败，说明：产品Fi3001B和 Fi3002B V6.060版本调用这个函数才有意义。Short SetHookOffThreshold(long uboxHandle, Short threshold)设置摘机门限 功 能：设置摘机门限值。参 数： uboxHnd 设备句柄threshold的值是摘机电压和挂机电压的之和的一半，摘机电压和挂机电压测量调用ubox_start_read_line_voltage，对于Fi3001B摘机状态是通过电压判断的。产品Fi3001B和 Fi3002B V6.060版本 调用这个函数才有意义。说 明: 产品Fi3001B和 Fi3002B V6.060版本是通过压控方式检测电话状态,通常情况下,挂机时直流电压为48V左右,摘机时直流电压会降到6V左右。USB录音盒设置默认摘机门限值为18V, 当线路电压大于18V,软件判断为挂机,小于18V软件判断为摘机。由于电话线的所处的环境不同,线路直流电压值不同,可能摘机后,线路电压依然要大于摘机门限值,这样软件不能正确检测到电话状态,需要重新设置摘机门限值Short StartReadLineVoltage(long uboxHandle) 开始线路电压测量 功 能：开始检测线路电压参 数： uboxHnd 设备句柄返 回: 0成功，错误参照“函数错误返回值 ”说 明: 调用这个函数后，会不停触发LineVoltage事件,报告当前线路电压值。产品Fi3001B和 Fi3002B V6.060版本 调用这个函数才有意义。说 明: Fi3001和 Fi3002B V6.060版本是通过压控方式检测电话状态,通常情况下,挂机时直流电压为48V左右,摘机时直流电压会降到6V左右。USB录音盒设置默认摘机门限值为18V, 当线路电压大于18V,软件判断为挂机,小于18V软件判断为摘机。由于电话线的所处的环境不同,线路直流电压值不同,可能摘机后,线路电压依然要大于摘机门限值,这样软件不能正确检测到电话状态,需要重新设置摘机门限值。Short StopReadLineVoltage (long uboxHandle) 结束线路电压测量 功 能：结束检测线路电压参 数： uboxHandle设备句柄返 回: 0成功，错误参照“函数错误返回值 ”说 明: 调用这个函数后，会停止触发UBOX_EVENT_LINE_VOLTAGE事件 Short SendDtmf(long uboxHandle, LPCTSTR dtmfNum) 拨号 功 能：发送号码（DTMF） 参 数: uboxHandle 设备句柄dtmfNum号码串返 回: 0成功，错误参照“函数错误返回值 ”说 明: 对于Fi3101A，电话机摘机，软件拨号，要调用软摘机函数，然后调用本函数，拨号声音会到耳麦里输出，号码拨完后，底层会自动软挂机，声音会切换到电话机里，如果电话机摘机，声音自动切换到电话机里，底层会自动软挂机，耳机无声音 。Fi3001B和Fi3002B，必须要先手动摘机，才可以拨号。对于有软摘机功能的产品(Fi3101A和Fi3102A)，直接软件拨号，有可能拨号不成功，拨得太快了，交换机需要时间检测摘机，因此处理方法上层程序需要先软摘机后，延时1-2S钟，然后再调用SendDtmf()函数。Short PlayFile(long uboxHandle, LPCTSTR filename) 放音 功 能： 播放语音文件参 数: uboxHandle 设备句柄filename是语音文件。返 回: 0成功，错误参照“函数错误返回值 ”说 明： 放音格式为： A-law,u-law, 8k * 16 位 pcm文件Short StopPlay (long uboxHandle) 停止放音 功 能：停止播放。参 数: uboxHandle 设备句柄返 回: 0成功，错误参照“函数错误返回值 ”Short PlayPause (long uboxHandle) 暂停放音 功 能： 暂停播放，再调用一次，又继续播放，参 数: uboxHandle 设备句柄返 回: 0成功，错误参照“函数错误返回值 ”Short SetMicVolume(long uboxHandle，short volume) 设置MIC音量功 能：设置MIC音量，设置音量为0db就可以了参 数: uboxHnd 设备句柄volume取值范围0 - 19返 回: 0成功，错误参照“函数错误返回值 ”Short SetSpeakerVolume(longuboxHandle，short volume) 设置放音音量功 能：设置放音音量 参 数: uboxHnd 设备句柄Volume 为0-20，系统默认值是10返 回: 0成功，错误参照“函数错误返回值 ”short CloseAgc(long uboxHandle, bool bclose) 关闭/打开AGC 功 能：打开/关闭AGC。参 数: uboxHandle 设备句柄bclose 为true,关闭agc；为false，打开agc,默认情况下是打开agc。返 回: 0成功，错误参照“函数错误返回值 ”Short ReadEeprom (long uboxHandle, short addr, short* pOutdata, short len) 功 能：读取USB录音盒中eeprom内的数据。参 数: uboxHandle 设备句柄Addr 要读取的数据的起始地址，范围为0x00-0x07,pOutdata 存放读取数据的bufferLen 读取长度用 法： 假如uboxHnd1，addr=0x0,unsigned char readdata8，ReadEeprom (1,0x00,&readata0,8),调用成功后，读取的数据在pOutData中返 回: 0成功，错误参照“函数错误返回值 ”说 明：Fi3001B使用该函数必须要在配置模式下才能使用。Short ReadEepromEx(long uboxHandle, short addr, short* pOutdata, short len) 功 能：读取USB录音盒中eeprom内的数据。参 数： uboxHandle： 设备句柄addr： eeprom地址，地址范围为0x00-0x07 pOutdata 读取数据的地址，数据大小范围为【0x00,0xFF】 len: 读取数据长度，最大长度为8个返 回: 0成功，错误参照“函数错误返回值 ”说 明： 对于Fi3001B，调用WriteEeprom写成功后，读取其正确值，必须在软件重新启动后，调用ReadEepromEx才能正确读取上次修改的值。而其它产品调用ReadEepromEx和ReadEeprom功能是一样的。CString ReadEepromex2(long uboxHandle, short addr, short len) 读Eeprom值 功 能：读取USB录音盒中eeprom内的数据。其功能和ReadEepromEx一样, 是为有些语言不支持指针,方便用户调用.参 数：uboxHandle： 设备句柄 Addr: eeprom地址，地址范围为0x00-0x07 len: 读取数据长度，最大长度为8个返 回：成功，返回读取的字符串。 失败，返回“error call”。Short WriteEeprom(long uboxHandle, short addr, short* Indata, short len) 功 能：往USB录音盒中的eeprom写入数据。参 数：uboxHandle： 设备句柄 addr： eeprom地址，地址范围为0x00-0x07 Indata： 写入数据的地址，数据大小范围为【0x00,0xFF】 len: 写入数据长度，最大长度为8个返 回: 0成功，错误参照“函数错误返回值 ”short WriteEepromex(long uboxHandle, short addr, LPCTSTR data, short len) 功 能：往USB录音盒中的eeprom写入数据。其功能和WriteEeprom方法一样,是为有些语言不支持指针,方便用户调用.参 数：uboxHandle： 设备句柄 addr： eeprom地址，地址范围为0x00-0x07 data 写入的数据 len: 写入数据长度，最大长度为8个返 回: 0成功，错误参照“函数错误返回值 ”short SoftHookoff(long uboxHandle); 软件摘机 功 能：软件摘机参 数：uboxHandle： 设备句柄返 回: 0成功，错误参照“函数错误返回值 ”说 明: Fi3101A 和Fi3102A才具有该功能。short SoftHookon(long uboxHandle); 软件挂机 功 能：软件挂机 参 数：long uboxHandle： 设备句柄返 回： 0成功 0失败，说 明： Fi3101A 和Fi3102A才具有该功能。调用了ubox_soft_hook_off，才能挂断电话线路的，在振铃时，为了不接本电话，直接调用ubox_soft_hook_on是无效的，模拟线路没有拒接功能的。short SetBusyToneInfo(long uboxHandle, long FAR* Pbusyinfo, short size)忙音参数设置 功 能：在设备成功打开后，如果忙音收不到，才需要设置该参数 参 数: uboxHnd 设备句柄pBusyinfo 用于设置忙音参数的数据结构。struct tagBusyInfolong busy_dual_frequency; 是否是双音频，默认为0 long busy_frequency0; 忙音频率0，默认450HZ long busy_frequency1; 忙音频率1，默认420HZ long busy_on; 忙音周期的持续时间，默认为35表示350ms long busy_off; 忙音周期的断续时间，默认为35表示350ms long busy_on_off_error; 忙音周期的持续时间和断续时间的误差，默认为5表示50ms long busy_enery_gate; 忙音的能量,默认为12db.long busy_period_count; 忙音判断的周期数,默认为3,表示连续检测到三个周期的忙音才报告有忙音UBOX_EVENT_DEVICE_BUSY_TONE事件.; Size 为 8 .返 回: 0成功，错误参照“函数错误返回值 ”用法举例: long busyinfo8busyinfo0 = 0;busyinfo1 = 450;busyinfo2 = 420;busyinfo3 = 35;busyinfo4 = 35;busyinfo5 = 5;busyinfo6 = 12; busyinfo7 = 2;SetBusyToneInfo(uboxHandle, busyinfo,8)short SetBusyToneEx(long uboxHandle, long dual_frequency, long frequency0, long frequency1, long busy_on_time, long busy_off_time, long on_off_error, long enery_gate, long period_count) 忙音参数设置功 能：如果忙音收不到，才需要设置该参数 。和SetBusyToneInfo 方法相同。参 数：uboxHandle： 设备句柄dual_frequency：是否是双音频，默认为0frequency0： 忙音频率0，默认450HZfrequency1： 忙音频率1，默认420HZbusy_on_time： 忙音周期的持续时间，默认为35表示350msbusy_off_time： 忙音周期的断续时间，默认为35表示350mson_off_error： 忙音周期的持续时间和断续时间的误差，默认为5表示50msenery_gate： 忙音的能量,默认为12db.period_count