PCBEST NETWORK SIP Software Development Kit(SDK)
Global Telephony Application Programming Interface (GTAPI)
PCBest Network's Global Telephony Application Programming Interface(GTAPI)is a well designed, highly integrated, and very flexible component for developing various telephony applications,
such as VOIP, IVR, and CTI applications.
This manual gives general information about how to use this API to meet your application need.
This guide is for programmers who use SIP ActiveX Control.
Integration Guide:
Please use regsvr32 to register the GTSIPCtrl.ocx in sdk bin folder.
Step 1: Put the ActiveX into Form, and assume the obj's name is GTSIPAPI1.
Step 2: Add two functions into Form.
void InitSIPServer()
{
GTSIPAPI1.CreateEnv()
GTSIPAPI1.CFGSetValue(...,....) //Set SIP configuration
GTSIPAPI1.StartServer()
}
void FreeSIPServer()
{
GTSIPAPI1.StopServer()
GTSIPAPI1.DestroyEnv()
}
Step 3: In Form load and Unload functions, InitSIPServer and FreeSIPServer are invoked.
Form1_Load()
InitSIPServer
End
Form1_Unload()
FreeSIPServer
End
Step 4: Add a timer to the dialog. Set timer to init event every 100ms.
Timer1_Event
GTSIPAPI1.ProcessGTAPIEvent() //Process All SIP Event
End
Step 5: Overwrite GTSIPAPI1's events. Please go to the following section 1.2 for details of some events.
1. GTAPIASM.GTAPIEnv class.
This is probably mainly class you need to deal with in your development.
Namesapce: GTAPIASM.GTAPIEnv
Member functions:
1.1 Call control command
1.1.1 Make a call
static void SendMake(int ch, string calledNum, string callerNum);
ch: Channel index based on 0
calledNum: The destination number you want to dial. If it is a SIP call, it must be in format "<sip:123@abc.com>".
callerNum: The caller id. It can be NULL.
1.1.2 Answer a incoming call
static void SendAnswer(int ch);
ch: Channel index based on 0
1.1.3 Disconnect a call
static void SendHungUp(int ch);
ch: Channel index based on 0
1.1.4 Hold a call
static void SendHold(int ch);
ch: Channel index based on 0
1.1.5 Transfer a call
static void SendTransfer(int ch, string destAddr);
ch: Channel index based on 0
destAddr: The destination number you want to dial. If it is a SIP call, it must be in format "<sip:123@abc.com>".
1.2 Virtual functions for call status event
1.2.1 Call Conntected Event
void OnCallConnected(int ch)
ch: Channel index based on 0
1.2.2 New Call Incoming
void OnCallOffered(int ch, string sCaller, string sCallee, string sDestAddr, string
sViaAddr, string sFromIP, unsigned short nFromPort)
ch: Channel index based on 0
sCaller: call from.
sCallee: call to.
sDestAddr: Real address it want to reach. (Only for SIP INVITE)
sViaAddr: Via Address.(only for SIP INVITE)
sFromIP: The real ip address of SIP INVITE message from
nFromPort: The real port of p address of SIP INVITE message from
1.2.3 The channel is dialing out(Usually this event arrives after Send_Make.)
void OnCallDialing(int ch, string sCaller, string sCallee)
ch: Channel index based on 0
sCaller: call from.
sCallee: call to.
1.2.4 The remote side is ringing
void OnCallRinging(int ch)
ch: Channel index based on 0
1.2.5 The call is terminated, and the channel is free to do next call or accept new call
virtual void OncallIdle(int ch)
ch: Channel index based on 0
1.2.6 The call is holding
virtual void OncallHolding(int ch, int hold_on)
ch: Channel index based on 0
hold_on: 1 = Holding, 0 = Unholded.
1.3 Virtual functions for audio event
1.3.1 Audio Play Done Event
virtual void OnAudioPlayDone(long ChanID, long DoneReason, BSTR DTMFStr);
ch: Channel index based on 0
DoneReason: 0 = DTMF_TIMEOUT; 1 = DTMF_MAX_DIGITS; 2 = DTMF_DIGIT_DETECTED; 3 = DONE_PLAY_AUDIO; 4 = DONE_RECORD_AUDIO; 5 = DONE_FORCED_STOP
DTMFStr: DTMF string it has received when playing audio
1.3.2 Audio Record Done Event
virtual void OnAudioRecordDone(long ChanID, long DoneReason, BSTR DTMFStr);
ch: Channel index based on 0
DoneReason: 0 = DTMF_TIMEOUT; 1 = DTMF_MAX_DIGITS; 2 = DTMF_DIGIT_DETECTED; 3 = DONE_PLAY_AUDIO; 4 = DONE_RECORD_AUDIO; 5 = DONE_FORCED_STOP
DTMFStr: DTMF string it has received when playing audio
1.3.3 Channel's audio status
virtual void OnAudioStatus(int ch, int resType, int statusCode)
ch: Channel index based on 0
resType: Audio resource typ. 0 = BOTH(Res for recording and playing); 1 = IN(recording); 2 = OUT(playing)
statusCode: 0 = IDLE, 1 = Playing, 2 = Recording, 3 = Stopping, 4 = Unavailable
1.4 Virtual functions for dtmf event
1.4.1 DTMF Done Event
virtual void OnDTMFDone(int ch, int reason, const char* DTMFStr)
ch: Channel index based on 0
reason: 0 = DTMF_TIMEOUT; 1 = DTMF_MAX_DIGITS; 2 = DTMF_DIGIT_DETECTED;
DTMFStr: DTMF string it has received when detecting DTMF
1.4.2 DTMF Key Down Event
virtual void OnDTMFKeyDown(long ChanID, short KeyValue, long ClockTicks)
ChanID: Channel index based on 0
KeyValue: Key pressed. for example; '0', '1',...
ClockTicks: Milliseconds for when the key is pressed. It can be used to calculate the duration of a key is pressed.
1.4.3 DTMF Key Up Event
virtual void OnDTMFKeyUp(long ChanID, short KeyValue, long ClockTicks)
ChanID: Channel index based on 0
KeyValue: Key pressed. for example; '0', '1',...
ClockTicks: Milliseconds for when the key is pressed. It can be used to calculate the duration of a key is pressed.
1.5 Virtual functions for channel status
1.5.1 Channel Status Event
virtual void OnRecvStatus(long ChanID1, long ChanID2, long ChanStatus);
ChanID1: First Channel
ChanID2: Second Channel
ChanStatus: Channel status. 0 = IDLE, 1 = Dialing, 2 = Ringing, 3 = Offered, 4 = Connecting, 5 = Connected, 6 = Disconnecting, 7 = Releasing, 8 = Not available, 9 = Offline
1.5.2 SIP Account Register Event
virtual void OnRecvRegStatus(long SIPAccID, long Status, long RegUnixTime);
SIPAccID: SIP Account ID, from 0.
Status: 1 = Successfully registered on SIP server.
RegUnixTime: Seconds it registered to SIP server.
1.5.3 Channel Error Event
virtual void OnRecvError(long ChanID, long ErrCode);
ChanID: Channel ID, from 0.
ErrCode: Error Code. For a complete error code, plrase refer gterr.h in SDK.
1.6 Audio Control Function
1.6.1 Play audio
static void SendPlayAudio(int ch, string audioFileName, int iMaxDigit,
string termStr, int iMaxTimer);
ch: Channel index based on 0
audioFileName: The file to play.
iMaxDigit: Reserved. Must be 0 now.
termStr: Reserved. Must be 0 now.
iMaxTimer: Reserverd. Must be 0 now.
1.6.2 Record Audio
static void SendRecordAudio(int ch, string audioFileName, int
iMaxDigit, string termStr, int iMaxTimer);
ch: Channel index based on 0
audioFileName: The file to record.
iMaxDigit: Reserved. Must be 0 now.
termStr: Reserved. Must be 0 now.
iMaxTimer: Reserverd. Must be 0 now.
1.6.3 Stop Audio
static void SendStopAudio(int ch);
ch: Channel index based on 0
1.6.4 Set Audio Format
//only 8K 8Bit Mulaw is supported right now
void SendSetAudioFormat(int ch, GT_UINT audioCode, GT_UINT audioSample, GT_UINT audioBit);
ch: Channel index based on 0
audioCode: Reserved. Must be 0.
audioSample: Reserverd. Must be 0.
audioBit: Reserverd. Must be 0.
1.6.5Get Audio Status
static void SendGetAudioStatus(int ch);
ch: Channel index based on 0
1.6.6 Start DirectX Audio
Please use this function after call is connected if you are developing a SIP Client Phone. It will automatically use Windows DirectX Audio as input and output device.
static void SendStartDXAudio(int ch);
ch: Channel index based on 0
1.6.7 Stop DirectX Audio
This function will be called once the call is IDLE. Generally, you don't need to call this function in your IDLE handle function.
static void SendStopDXAudio(int ch);
ch: Channel index based on 0
1.6.7 Reset DirectX Audio
This function will be called to reset DirectX sound device. If you want to change sound device, you need to use this function.
static void SendResetDXAudio(int ch);
ch: Channel index based on 0
For example:
CFG_SetValue("gtsrv.sip.dxsound.device.playback", "2345M"); //set key word of playback device
CFG_SetValue("gtsrv.sip.dxsound.device.capture", "SB879B"); //set key word of recording device
Send_ResetDxAudio(ch);
|
|
