METHOD DETAILS
This document specifies the Status and Error code numbers and also describes the events and functions supported by VaxSIPUserAgent SDK Components:
CODE NUMBERS:
- Error Codes
EVENTS:
- OnFailToUnRegister()
- OnSuccessToUnRegister()
- OnFailToRegister()
- OnSuccessToRegister()
- OnFailToConnect()
- OnSuccessToConnect()
- OnConnecting()
- OnIncomingCall()
- OnIncomingCallRingingStart()
- OnIncomingCallRingingStop()
- OnDisconnectCall()
- OnProvisionalResponse()
- OnRedirectionResponse()
- OnRequestFailureResponse()
- OnServerFailureResponse()
- OnGeneralFailureResponse()
METHODS:
- Initialize()
- UnInitialize()
- SetLicenceKey()
- GetVaxObjectError()
- Connect()
- Disconnect()
- AcceptCall()
- RejectCall()
- RegisterToProxy()
- UnRegisterToProxy()
- DeselectAllVoiceCodec()
- SelectAllVoiceCodec()
- SelectVoiceCodec()
- DeselectVoiceCodec()
- GetMyIP()
- DigitDTMF()
- MuteMic()
- MuteSpk()
- EnableMicBoost()
- DisableMicBoost()
- IsMicBoostEnable()
- GetMicVolume()
- SetMicVolume()
- GetSpkVolume()
- SetSpkVolume()
- EnableEchoNoiseCancellation()
- DisableEchoNoiseCancellation()
- StartRecording()
- StopRecording()
- ResetRecording()
- SaveRecordingToWaveFile()
- PlayWaveOpen()
- PlayWaveSkipTo()
- PlayWaveTotalTime()
- PlayWavePause()
- PlayWaveStart()
- PlayWaveStop()
- PlayWavePosition()
- EnableDonotDisturb()
- DisableDonotDisturb()
ERROR CODES DETAIL:
ERROR CODES | DESCRIPTION
10 | VAXOBJECT is not initialized properly, To initialize, the VaxVoIP Object Initialize method should be called.
11 | Cannot open local communication port, port is invalid or is already in use.
12 | Invalid License Key.
13 | Fail to initialize VaxVoIP task window.
14 | Cann't access Input/Mic device or device is already in use.
15 | Cann't access Output/Speaker device or device is already in use.
16 | Fail to initialize voice compression manager.
17 | Recording media initialization error.
18 | Cann't open the wave file.
19 | Fail to open voice recording channel.
20 | Fail to access the Mic/Input device Volume OR Sound device does not support Mic volume feature.
21 | Fail to access the Speaker/Output device Volume OR Sound device does not support Speaker volume feature.
22 | Error to open wave file to play.
23 | Provided SIP URI is not valid.
24 | Codec is not supported.
25 | Error to create SDP (Session Description Protocol) request.
26 | Error to create CONNECTION request.
27 | Error to create REGISTER request.
28 | Error to create UN-REGISTER request.
29 | Error to create DISCONNECT request.
EVENTS:
OnFailToUnRegister
It notifies that unregister request to proxy server has failed.
OnSuccessToUnRegister
Client has successfully unregistered from the proxy server.
OnFailToRegister
Register request to proxy server has failed.
OnSuccessToRegister
Component has successfully registered with the proxy server.
OnFailToConnect
Call is not connected.
OnSuccessToConnect
Call is successfully connected.
OnConnecting
Trying to make call.
OnIncomingCall
Notification for incoming call.
OnIncomingCallRingingStart
Incoming call is ringing. Any phone bell wave file can be played in this event.
OnIncomingCallRingingStop
Incoming call ringing stopped. Stop playing phone bell wave file.
OnDisconnectCall
Notifies that other party has hung up the phone.
OnProvisionalResponse
Notifies that Provisional response is received from the SIP Proxy Server. SIP provisional responses lies in the range of 1xx (100 to 199). please see the SIP RFC 3261 for more details.
OnRedirectionResponse
Notifies that redirection response is received from the SIP Proxy Server. SIP redirection responses lies in the range of 3xx (300 to 399). please see the SIP RFC 3261 for more details.
OnRequestFailureResponse
Notifies that request failure response is received from the SIP Proxy Server. SIP request failure responses lies in the range of 4xx (400 to 499). please see the SIP RFC 3261 for more details.
OnServerFailureResponse
Notifies that server failure response is received from the SIP Proxy Server. SIP server failure responses lies in the range of 5xx (500 to 599). please see the SIP RFC 3261 for more details.
OnGeneralFailureResponse
Notifies that global failure response is received from the SIP Proxy Server. SIP general failure responses lies in the range of 6xx (600 to 699). please see the SIP RFC 3261 for more details.
METHODS:
Initialize()
This method is called to initialize the VaxVoIP control. After initializing, user will be able to make or receive phone calls.
Parameter s:
- Listening Port No (default SIP port 5060)
- InputDeviceId (-1 = auto select)
- OutputDeviceId (-1 = auto select)
- From SIP URI (Please see the sample source code)
- SIPOutBoundProxy (SIP outbound proxy IP or FQDN provided by IP-Telephony service provider)
- SIPProxy (SIP Proxy IP or FQDN provided by IP-Telephony service provider.)
- LoginId (Provided by the IP-Telephony service provider.)
- LoginPwd (Provided by the IP-Telephony service provider.)
Return Value:
Non-zero on success, otherwise 0, and a appropriate error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
Value -1 can be provided, if your computer has single sound device OR you want VaxVoIP control to select the first/default sound device capable of recording and playing.
If you want to run multiple instances of your client software and your computer has multiple sound devices then WinMM (Windows Multimedia API) can be used to determine the device-Ids.
From URI can be constructed in the format: PROXY-LOGIN<sip:PROXY-LOGIN@MY-IP>
GetMyIP() exported method can be used in order to get your machine IP. Please see the Sample
Source Code or SIP RFC 3261 for more details.
In some cases, ITSP (Internet Telephony service provider) support outbound proxy. Outbound proxy is the only way to let the NAT/firewall user make and receive phone calls.
If the NAT/firewall router does not support SIP pass-through, you need to consult your ITSP if they support SIP outbound proxy. Since different NAT router vendor implement NAT differently.
Typically ITSP may provide SIP outbound proxy to resolve NAT pass-through issues.
UnInitialize()
To uninitialize the VaxVoIP control, this method can be used.
SetLicenceKey()
Call this method, to set the License key.
Parameter:
- License Key Provided by VaxVoIP
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
You must pay the License fee in order to get the License Key. After getting the License key, you will set it using this method and it will remove the evaluation message box & expiry.
GetVaxObjectError()
Call this method, to get the error for the last operation that failed.
Return Value:
- Error Code Number
Connect()
This method is called to make outbound call at any phone number.
Parameters:
- To SIP URI
- RTP IP (IP address to receive voice stream)
- RTP Port (Port to receive voice stream)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
This method tries to tries to make calls. SIP To URI for to make call can be constructed in
following SIP URI format: sip:PhoneNumber@SIP- Proxy-IP or FQDN
Please see the SIP RFC 3261 or Sample source code for more details.
Disconnect()
To hang up the call.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
AcceptCall()
This method is called to accept the incoming call.
Parameters:
- RTP IP (IP address to receive voice stream)
- RTP Port (Port to receive voice stream)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
RejectCall()
To cancel the incoming call.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
RegisterToProxy()
To register with the SIP proxy server.
Parameters:
- Registration Interval (See the SIP registration process or SIP RFC 3261 for more details.)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
UnRegisterToProxy()
To un-register from the SIP proxy server.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
DeselectAllVoiceCodec()
Call to this method, deselects all voice codecs.
Supported codecs are: GSM 6.10, iLBC, G711 A-Law, G711 U-Law.
SelectAllVoiceCodec()
To select all voice codecs.
SelectVoiceCodec()
To select a voice codec.
Parameters:
- Codec No
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
VaxVoIP SIP SDK support the following voice codecs:
1. GSM 6.10 (Codec No = 0)
2. iLBC (Codec No = 1)
3. G711 A-Law (Codec No = 2)
4. G711 U-Law (Codec No = 3)
Any codec can be selected by providing its Codec No in this method.
DeselectVoiceCodec()
To deselect a voice codec.
Parameters:
- Codec No
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
VaxVoIP SIP SDK support the following voice codecs:
1. GSM 6.10 (Codec No = 0)
2. iLBC (Codec No = 1)
3. G711 A-Law (Codec No = 2)
4. G711 U-Law (Codec No = 3)
Any codec can be de-selected by providing its Codec No in this method.
GetMyIP()
Method is used to get the IP address assigned to the computer. Please see the sample source code for more details.
DigitDTMF()
Method to send DTMF Digit to the remote end. This method can also be used to play DTMF tones.
Parameters:
- DTMF Digit (1, 2, 3, 4, 5, ..... 0, *, #)
- Duration to play the tone (normaly 250 ms is enough)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
MuteSpk()
To mute the speaker, this method can be called. Muting the speaker does not affect the Master Mute Control.
Parameter:
- Boolean Value 0 or 1
Return Value:
Non-Zero on success, otherwise 0
MuteMic()
To mute the microphone, this method can be called. Muting the Microphone does not affect the Master Mute Control. It simply blocks the outbound voice streaming data.
Parameter:
- Boolean Value 0 or 1
Return Value:
Non-Zero on success, otherwise 0
GetSpkVolume()
Call to this method returns the speaker volume value between Range [0 to 255], where
0 = Min Volume
255 = Max Volume
Return Value:
Speaker Volume value on success, otherwise –1 and a specific error code can be retrieved by calling GetVaxObjectError() method.
SetSpkVolume()
To set the Output volume, this method can be called. the value range should between 0 to 255.
Parameter:
- Volume Value between [0 – 255] Range
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
GetMicVolume()
Call the method to get the Microphone Volume. Volume value is returned, in the range of [0 to 255], where
0 = Min Volume
255 = Max Volume
Return Value:
Microphone Volume value on success, otherwise –1 and a specific error code can be retrieved by calling GetVaxObjectError() method.
SetMicVolume()
Call the method to set the Microphone Volume, the value range should between 0 to 255, where
0 = Min Volume
255 = Max Volume
Parameter:
- Volume Value between [0 – 255] Range
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
EnableMicBoost()
Call the method to increase the Microphone sensitivity.
DisableMicBoost()
To disable the Mic Boost.
IsMicBoostEnable()
Call the method to get Mic Boost is enabled or disabled.
EnableEchoNoiseCancellation()
Method can be used to enable the noise & echo cancellation. Default value = Enable.
AEC (acoustic echo cancellation) works by modeling the output from the speakers and removing it from the signal captured by the microphone. AEC helps to ensure that no echo is heard at the other end.
Noise cancellation, that allows significant suppression of any background noise and provides high quality of output speech.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
DisableEchoNoiseCancellation()
Method to disable the noise & echo cancellation feature.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
StartRecording()
This method is used to start the conversation recording.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
VaxVoIP component creates recording tmp file for buffering purposes or to store the digital data. When this method is called, VaxVoIP component starts storing data into the tmp file.
StopRecording()
This method is used to stop the conversation recording.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
Call to this method stops storing data into recording tmp file.
ResetRecording()
This method can be call to reset/clear the recording buffer.
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
Call to this method, clears saved digital data from the recording tmp file.
SaveRecordingToWaveFile()
To save the recording tmp file voice data into wave (.wav) file.
Parameter:
- File name (.wav)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
Call to this method, saves tmp voice data into wave (.wav) file.
PlayWaveOpen()
To set a wave file to play. Only GSM6.10 based compressed wave file are supported.
Microsoft Sound Recorder application can be used to record GSM6.10 based compressed wave file.
Parameter:
- File name (.wav)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
PlayWaveStart()
Call to this method, starts playing the wave file.
1. Open the wave file with PlayWaveOpen() method.
2. Start playing with PlayWaveStart() method.
PlayWaveSkipTo()
To change the playing cursor position to the new position.
Parameter:
- New Position (in seconds)
Return Value:
Non-zero on success, otherwise 0, and a specific error code can be retrieved by calling GetVaxObjectError() method.
Remarks:
Call to this method, changes the playing cursor position and VaxVoIP SIP object starts playing from the new position.
PlayWavePosition()
To get the current position of playing cursor.
PlayWaveTotalTime()
To get the total play time of a wave file.
PlayWavePause()
To pause playing at the current position.
PlayWaveStop()
To stop playing and change the playing cursor position to the beginning.
EnableDonotDisturb()
To enable the don't disturb status. Please see the sample source code for more details.
DisableDonotDisturb()
To disable the don't disturb status. Please see the sample source code for more details.