SoftPhone API of GoHigh

SoftPhone API 使用参考

目录
1. 概述 2
1.1. 术语 2
2. 接口 2
2.1. 设置SoftPhoneInit 2
2.2. 设置DTMF的发送方法 2
2.3. Sip Register间隔 3
2.4. 发送应用数据 3
2.5. 发起呼叫 3
2.6. 接受呼叫 3
2.7. 发送DTMF 4
2.8. 停止呼叫 4
2.9. 发送语音文件给对方 4
2.10. 停止发送语音文件 4
3. 事件 5
3.1. 应用数据事件 5
3.2. 状态汇报 5
3.3. 接收语音事件 5
3.4. 发送语音事件 6
3.5. 呼叫结束事件 6



1. 概述

 
本文是描述softphone sdk 的API interface, 供使用 soft phone sdk开发soft phone的人员参考。
本文的softphone sdk 产品是一个没有界面的，提供了语音和sip信令，以及穿越NAT功能的SDK产品。Softphone sdk是一个用于二次开发的软件电话产品：不具备客户化的界面，因此可以将本软件电话嵌入到其他软件中。但是，它解决了除界面以外的所有软件电话的问题，提供给再次开发人员简单的，方便的接口；开发人员无需知道呼叫协议，语音相关处理，可以在很短的时间内完成所需要的软件电话。

1.1. 术语
soft phone/软件电话――是指在PC机上，利用PC机上的媒体资源（声卡、耳麦）以及网络资源（Internet），实现一个打电话的软件。
SDK ―― 软件开发工具包
SIP ―― Session Initiation Protocol，一种呼叫协议

2. 接口

2.1. 设置SoftPhoneInit
函数原型：BOOL SetServerAddr(const char *addr, int port)
功能：设置呼叫服务器地址和端口。
参数：addr：呼叫服务器地址；port：呼叫服务器port
备注：一般来说，在使用SDK的一开始，就需要设置软电话的初始化，也就是说要调用此项接口。

2.2. 设置DTMF的发送方法
函数原型：BOOL SetDTMFMethod (int method, int payload = 96)
功能：设置DTMF的发送方法。
参数：method：0为Inbind，1 为2833；payload：如果时2833的方法则应该填写playload，默认为96。
备注：一般来说，当前在Sip协议中DTMF的发送有两种方法，一种实带内方式；这种方法简单，而且兼容性好，但是，由于在软交换中大量采用了高压缩率的语音编解码，导致这种方式不是很准确，所以有了第二中方式，RFC2833，这种方式同样简单易行，而且由于实在RTP中数字化传输，不会有错码，准确性很高，也是目前软教换中采用最普遍的方法；本SDK支持这两种方法；您可以通过调用本方法设置您所需要的DTMF发送方法。

2.3. Sip Register间隔
函数原型：BOOL SetHBInterval(int interval)
功能：设置给Server发送HB的时间间隔；以保证与Server之间的通信不中断。
参数： interval：HB的时间间隔(以秒为单位)
备注：这是sip协议的一个特性，在sip注册中，网关必须在一定时间段内给Server发送注册消息，否则Server会认为这个终端已经不在线；一般说来这个消息还有另一个用途，如果您的软件电话在NAT中使用，想要Server能够成功的给您发起呼叫，您就必须让您的GW、防火墙能够将Server发送过来的sip信令给您的软件电话，可能您需要定时发送消息给Server才可以。

 
2.4. 发送应用数据
函数原型：BOOL SndAppData（char *pData）
功能：发送应用数据
参数：pData
本注：如果您的软件电话和您的Server之间想要需要除了sip呼叫信令之外的通信，您可以通过调用本方法发送您的数据；SDK会将您的数据最为sip info发送给Server。相应的Server发送给软件电话的数据，SDK将通过OnRcvAppData事件通知您。

2.5. 发起呼叫
函数原型：BOOL CallStart(char *callee)
功能：发起呼叫
参数：callee：被叫号码
备注：发起新的呼叫，callee 是您想呼叫的被叫的电话号码；SDK会发起新的呼叫给Server。

2.6. 接受呼叫
函数原型：BOOL Answer（）
功能：接受呼叫
参数：无
备注：如果您收到OnStatusChange事件，并且status的值为RINGING，表示这个软件电话上已经有来电，您需要响铃；并且这个时候，您就可以选择是不是接通这个呼叫了；如果您想接受，调用Answer这个方法就可以了。

2.7. 发送DTMF
函数原型：BOOL SndDTMF（int digits）
功能：发送DTMF给对方。
参数：digits：数字”0～9”和 “# *” 的ASC码。
备注：如果呼叫的过程中，需要输入DTMF拨号，或者extension号码等，您可以调用这个消息发送您界面上的用户输入；其实一般来说这个函数一定是对应于用户界面按键盘的事件。

2.8. 停止呼叫
函数原型：BOOL CallEnd()
功能：停止呼叫
参数：无
备注：结束呼叫，可以根据您的设计以及用户的按键来触发这个方法的调用，比如，您的软件电话只能呼叫3分钟；那么3分钟事件到，您就可以自动调用这个方法了。

2.9. 发送语音文件给对方
函数原型：Void SndFileVoice(char *filename)
功能：发送语音文件中的语音资源，代替麦克风的录音。
参数：filename：语音文件的文件名，这个文件必须是16位，单声道，的线性采样语音文件。
备注：这个方法可以作彩铃，即震零的时候可以发送语音文件给主叫，主叫将听到您发送的预先录制语音文件中的声音；当然在通话的过程中，您也可以发送语音文件让对方听到。

2.10. 停止发送语音文件
函数原型：Void StopSndFileVoice()
功能：停止发送，恢复麦克风录音发送
参数：无
备注：如果您发送了语音文件最为彩铃，但是用户已经摘机，您就需要停止彩铃的发送，这是SDK会自动接通用户麦克风的语音输入。

3. 事件

3.1. 应用数据事件
事件原型：OnRcvAppData（char *pData）
功能：接收到的应用层数据事件。
参数： pData：应用事件指针。
备注：您必须立即读取指针中的数据，否则数据将被覆盖；参见发送应用数据

3.2. 状态汇报
事件原型：OnStatusChange(int status)
功能：状态事件汇报
参数：status表示通话状态的改变到的新的状态
IDLE（＝0）：空闲状态；
TRYING（＝1）：SDK正在为您发起新的呼叫；
RINGING（＝2）：您有新的呼叫在等待您的相应；
CONNECTING（＝3）：指被叫已经Answer呼叫，等到呼叫正在连接；
CONNECTED（＝5）：呼叫已经接通，通话中；
CANCELED（＝4）：主叫状态，取消呼叫的状态
RELEASING（＝6）：释放已经通话呼叫
备注：一般来说，在状态改变的时候，您需要注意您的界面按钮的disable，enable的情况，避免用户的误操作。

3.3. 接收语音事件
事件原型：OnRcvVoice(char *pVoice, int length)
功能：接收语音事件
参数： pVoice：接收到的语音数据指针
length：接收到的语音数据长度
备注：语音数据是指16位，单声道，线性采样的PCM语音数据格式。您可以在收到此事件的时候保存收到的语音数据，其实就是可以录制对方说话的声音，当然您也可以忽略这个事件。
与发送语音事件相对应，这两个事件的语音数据包和起来，就实现了对整个通话的录音，您可以将两方的声音混合后在存贮到文件；也可以将两路语音作为一个16位的双声到的语音文件的左右声道，录制成双声道的语音文件。

3.4. 发送语音事件
事件原型：OnSndVoice(char *pVoice, int length)
功能：发送语音事件
参数： pVoice：你的Phone将要发送的语音数据指针
length：语音数据长度
备注：语音数据是指16位，单声道，线性采样的PCM语音数据格式。您可以在收到此事件的时候保存收到的语音数据，其实就是可以录制本地说话的声音，当然您也可以忽略这个事件。
与接收语音事件相对应，这两个事件的语音数据包和起来，就实现了对整个通话的录音，您可以将两方的声音混合后在存贮到文件；也可以将两路语音作为一个16位的双声到的语音文件的左右声道，录制成双声道的语音文件。

3.5. 呼叫结束事件
事件原型：OnCallEnd（char *caller, char *callee, int start, int duration）
功能：呼叫结束事件，汇报呼叫的CDR
参数：
caller：主叫号码
callee：被叫号码
start：通话开始时间
duration：通话时长
备注：通过这个事件，您可以构建呼叫通话记录。