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 .NET programmers.
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 Send_Make(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 Send_Answer(int ch);
ch: Channel index based on 0
1.1.3 Disconnect a call
static void Send_HungUp(int ch);
ch: Channel index based on 0
1.1.4 Hold a call
static void Send_Hold(int ch);
ch: Channel index based on 0
1.1.5 Transfer a call
static void Send_Transfer(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 On_RecvConnected(int ch)
ch: Channel index based on 0
1.2.2 New Call Incoming
void On_RecvOffered(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 On_RecvDialing(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 On_RecvRinging(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 On_RecvIdle(int ch)
ch: Channel index based on 0
1.2.6 Audio Play Done Event
virtual void On_RecvAudioPlayDone(long ChanID, long DoneReason, string 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.2.7 Audio Record Done Event
virtual void On_RecvAudioRecordDone(long ChanID, long DoneReason, string 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.2.8 Channel's audio status
virtual void On_RecvAudioStatus(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.2.8 DTMF Done Event
virtual void On_RecvDTMFDone(int ch, int reason, string 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.2.9 DTMF Key Down Event
virtual void On_RecvDTMFKeyDown(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.2.10 DTMF Key Up Event
virtual void On_RecvDTMFKeyUp(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.2.11 Channel Status Event
virtual void On_RecvStatus(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.2.12 SIP Account Register Event
virtual void On_RecvRegStatus(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.2.13 Channel Error Event
virtual void On_RecvError(long ChanID, long ErrCode);
ChanID: Channel ID, from 0.
ErrCode: Error Code. For a complete error code, plrase refer gterr.h in SDK.
1.3 Audio Control Function
1.3.1 Play audio
static void Send_PlayAudio(int ch, string audioFileName, int iMaxDigit,
string termStr, int iMaxTimer);
ch: Channel index based on 0
audioFileName: The file to play. if it is "", then files in audio list will be played.
iMaxDigit: Max number of DTMF digits when playing. When this number of digits reachs, audio will be stopped, and audio-play-done reason is max-digits. 0 = no limitation
termStr: When character in termStr is arrived, audio will be stopped, and audio-play-done reason is term-str. "" = no term string
iMaxTimer: Max timeout for playing audio or waiting for DTMF digits. 0 = no limitation.
1.3.2 Record Audio
static void Send_RecordAudio(int ch, string audioFileName, int
iMaxDigit, string termStr, int iMaxTimer);
ch: Channel index based on 0
audioFileName: The file to play. if it is "", then files in audio list will be played.
iMaxDigit: Max number of DTMF digits when playing. When this number of digits reachs, audio will be stopped, and audio-play-done reason is max-digits. 0 = no limitation
termStr: When character in termStr is arrived, audio will be stopped, and audio-play-done reason is term-str. "" = no term string
iMaxTimer: Max timeout for playing audio or waiting for DTMF digits. 0 = no limitation.
1.3.3 Stop Audio
static void Send_StopAudio(int ch);
ch: Channel index based on 0
1.3.4 Set Audio Format
//only 8K 8Bit Mulaw is supported right now
void Send_SetAudioFormat(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.3.4 Get Audio Status
static void Send_GetAudioStatus(int ch);
ch: Channel index based on 0
1.3.5 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 Send_StartDXAudio(int ch);
ch: Channel index based on 0
1.3.6 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 Send_StopDXAudio(int ch);
ch: Channel index based on 0
1.3.7 Set volume of speaker and microphone
static void Send_SetDXAudioVolume(int ch, int speaker, int microphone);
ch: Channel index based on 0
speaker: Speaker's volume.
microphone: Microphone's volume.
|
|
