User Manual for Android
FAQ
Where can I download the PortSIP VoIP SDK for testing?
You can download the PortSIP VoIP SDK and sample projects from the PortSIP Website.
What Android API version is required?
The PortSIP VoIP SDK requires Android API version 16 or later.
How can I create a new project with the PortSIP VoIP SDK?
Download the Sample Project and SDK: Obtain the sample project and trial SDK from the PortSIP Website and extract them to a desired directory.
Create a New Project: In Android Studio, create a new Android Application project.
Add the SDK Libraries: Copy all files from the
libsdirectory of the extracted SDK to thelibsdirectory of your new application.Import Necessary Classes: Import the required classes from the SDK:
How can I process callback events?
Implement the OnPortSIPEvent Interface: Your class should implement the
OnPortSIPEventinterface to handle callback events.Override Callback Methods: Override the necessary callback methods (e.g.,
onRegistrationState,onCallState) to handle specific events.
How do I initialize the SDK?
Create an Instance: Create an instance of the
PortSipSdkclass.Set the Event Listener: Set the event listener using
setOnPortSIPEvent.Create a Call Manager: Create a call manager using
CreateCallManager.Initialize the SDK: Call the
initializemethod with appropriate parameters.
Is the SDK thread-safe?
Yes, the PortSIP SDK is thread-safe. You can call API functions from multiple threads without worrying about synchronization issues. However, there are exceptions: the onAudioRawCallback, onVideoRawCallback, and onRTPPacketCallback callbacks should not be called directly from other threads.
SDK Callback events
Register events
When successfully registered to server, this event will be triggered.
Parameters
reason | The status text. |
code | The status code. |
sipMessage | The SIP message received. |
When failed to register to SIP server, this event will be triggered.
Parameters
reason | The status text. |
code | The status code. |
sipMessage | The SIP message received. |
Call events
When a call is coming, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller |
caller | The caller. |
calleeDisplayNam e | The display name of callee. |
callee | The callee. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, it means that this call include the audio. |
existsVideo | By setting to true, it means that this call include the video. |
sipMessage | The SIP message received. |
If the outgoing call is being processed, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
Once the caller received the "183 session progress" message, this event would be triggered.
Parameters
sessionId | The session ID of the call. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsEarlyMedia | By setting to true it means the call has early media. |
existsAudio | By setting to true it means this call include the audio. |
existsVideo | By setting to true it means this call include the video. |
sipMessage | The SIP message received. |
If the outgoing call is ringing, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
statusText | The status text. |
statusCode | The status code. |
sipMessage | The SIP message received. |
If the remote party answered the call, this event would be triggered.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller |
caller | The caller. |
calleeDisplayNam e | The display name of callee. |
callee | The callee. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, this call includes the audio. |
existsVideo | By setting to true, this call includes the video. |
sipMessage | The SIP message received. |
This event will be triggered if the outgoing or incoming call fails.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller l |
caller | The caller. l |
calleeDisplayNam e | The display name of callee. l |
callee | The callee. |
reason | The failure reason. |
code | The failure code. |
sipMessage | The SIP message received. |
This event will be triggered when remote party updates the call.
Parameters
sessionId | The session ID of the call. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
screenCodecs | The matched screen codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, this call includes the audio. |
existsVideo | By setting to true, this call includes the video. |
existsScreen | By setting to true, this call includes the screen shared. |
sipMessage | The SIP message received. |
This event will be triggered when UAC sent/UAS received ACK (the call is connected). Some functions (hold, updateCall etc...) can be called only after the call connected, otherwise the functions will return error.
Parameters
sessionId | The session ID of the call. |
If the enableCallForward method is called and a call is incoming, the call will be forwarded automatically and this event will be triggered.
Parameters
forwardTo | The target SIP URI of the call forwarding. |
This event is triggered once remote side ends the call.
Parameters
sessionId | The session ID of the call. |
sipMessage | The SIP message received. |
If a user subscribed and his dialog status monitored, when the monitored user is holding a call or is being rang, this event will be triggered.
Parameters
BLFMonitoredUri | the monitored user's URI |
BLFDialogState | - the status of the call |
BLFDialogId | - the id of the call |
BLFDialogDirecti on | - the direction of the call |
If the remote side places the call on hold, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
If the remote side un-holds the call, this event will be triggered Parameters
sessionId | The session ID of the call. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codec. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codec. |
existsAudio | By setting to true, this call includes the audio. |
existsVideo | By setting to true, this call includes the video. |
Refer events
This event will be triggered once received a REFER message.
Parameters
sessionId | The session ID of the call. |
referId | The ID of the REFER message. Pass it to acceptRefer or rejectRefer |
to | The refer target. |
from | The sender of REFER message. |
referSipMessage | The SIP message of "REFER". Pass it to "acceptRefer" function. |
This callback will be triggered once remote side calls "acceptRefer" to accept the REFER Parameters
sessionId | The session ID of the call. |
This callback will be triggered once remote side calls "rejectRefer" to reject the REFER Parameters
sessionId | The session ID of the call. |
reason | Reject reason. |
code | Reject code. |
When the refer call is being processed, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
When the refer call is ringing, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
When the refer call succeeds, this event will be triggered. The ACTV means Active. For example, A establishes the call with B, A transfers B to C, C accepts the refer call, and A will receive this event.
Parameters
sessionId | The session ID of the call. |
When the refer call fails, this event will be triggered. The ACTV means Active. For example, A establish the call with B, A transfers B to C, C rejects this refer call, and A will receive this event.
Parameters
sessionId | The session ID of the call. |
reason | The error reason. |
code | The error code. |
Signaling events
This event will be triggered when receiving a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
sessionId | The session ID of the call. |
message | The received SIP message. |
This event will be triggered when sent a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
sessionId | The session ID of the call. |
message | The sent SIP message. |
MWI events
If there is the waiting voice message (MWI), this event will be triggered.
Parameters
messageAccount | Voice message account |
urgentNewMessag eCount | Count of new urgent messages. |
urgentOldMessage Count | Count of history urgent message. |
newMessageCount | Count of new messages. |
oldMessageCount | Count of history messages. |
If there is waiting fax message (MWI), this event will be triggered.
Parameters
messageAccount | Fax message account |
urgentNewMessag eCount | Count of new urgent messages. |
urgentOldMessage Count | Count of history urgent messages. |
newMessageCount | Count of new messages. |
oldMessageCount | Count of old messages. |
DTMF events
This event will be triggered when receiving a DTMF tone from remote side.
Parameters
sessionId | Session ID of the call. | ||
tone | |||
code | Description | ||
0 | The DTMF tone 0. | ||
1 | The DTMF tone 1. | ||
2 | The DTMF tone 2. | ||
3 | The DTMF tone 3. | ||
4 | The DTMF tone 4. | ||
5 | The DTMF tone 5. | ||
6 | The DTMF tone 6. | ||
7 | The DTMF tone 7. | ||
8 | The DTMF tone 8. | ||
9 | The DTMF tone 9. | ||
10 | The DTMF tone *. | ||
11 | The DTMF tone #. | ||
12 | The DTMF tone A. | ||
13 | The DTMF tone B. | ||
14 | The DTMF tone C. | ||
15 | The DTMF tone D. | ||
16 | The DTMF tone FLASH. |
INFO/OPTIONS message events
This event will be triggered when receiving the OPTIONS message.
Parameters
optionsMessage | The received whole OPTIONS message in text format. |
This event will be triggered when receiving the INFO message.
Parameters
infoMessage | The whole INFO message received in text format. |
This event will be triggered when receiving a NOTIFY message of the subscription.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
notifyMessage | The received INFO message in text format. |
messageData | The received message body. It's can be either text or binary data. |
messageDataLengt h | The length of "messageData". |
Presence events
This event will be triggered when receiving the SUBSCRIBE request from a contact.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request. |
subject | The subject of the SUBSCRIBE request. |
When the contact is online or changes presence status, this event will be triggered.
Parameters
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request. |
stateText | The presence status text. |
When the contact is offline, this event will be triggered.
Parameters
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request |
This event will be triggered when receiving a MESSAGE message in dialog.
Parameters
sessionId | The session ID of the call. |
mimeType | The message mime type. |
subMimeType | The message sub mime type. |
messageData | The received message body. It can be text or binary data. Use the mimeType and subMimeType to differentiate them. For example, if the mimeType is "text" and subMimeType is "plain", "messageData" is text message body. If the mimeType is "application" and subMimeType is "vnd.3gpp.sms", "messageData" is binary message body. |
messageDataLengt h | The length of "messageData". |
This event will be triggered when receiving a MESSAGE message out of dialog. For example pager message.
Parameters
fromDisplayName | The display name of sender. |
from | The message sender. |
toDisplayName | The display name of receiver. |
to | The receiver. |
mimeType | The message mime type. |
subMimeType | The message sub mime type. |
messageData | The received message body. It can be text or binary data. Use the mimeType and subMimeType to differentiate them. For example, if the mimeType is "text" and subMimeType is "plain", "messageData" is text message body. If the mimeType is "application" and subMimeType is "vnd.3gpp.sms", "messageData" is binary message body. |
messageDataLengt h | The length of "messageData". |
sipMessage | The SIP message received. |
If the message is sent successfully in dialog, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
messageId | The message ID. It's equal to the return value of sendMessage function. |
sipMessage | The SIP message received. |
If the message is failed to be sent out of dialog, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
messageId | The message ID. It's equal to the return value of sendMessage function. |
reason | The failure reason. |
code | Failure code. |
sipMessage | The SIP message received. |
If the message is sent successfully out of dialog, this event will be triggered.
Parameters
messageId | The message ID. It's equal to the return value of SendOutOfDialogMessage function. |
fromDisplayName | The display name of message sender. |
from | The message sender. |
toDisplayName | The display name of message receiver. |
to | The message receiver. |
sipMessage | The SIP message received. |
If the message failed to be sent out of dialog, this event would be triggered.
Parameters
messageId | The message ID. It's equal to the return value of SendOutOfDialogMessage function. |
fromDisplayName | The display name of message sender |
from | The message sender. |
toDisplayName | The display name of message receiver. |
to | The message receiver. |
reason | The failure reason. |
code | The failure code. |
sipMessage | The SIP message received. |
This event will be triggered on sending SUBSCRIBE failure.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
statusCode | The status code. |
This event will be triggered when a SUBSCRIPTION is terminated or expired.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
audio device changed,Play audio and video file finished events
If called startPlayingFileToRemote function with no loop mode, this event will be triggered once the file play finished.
Parameters
sessionId | The session ID of the call. |
fileName | The play file name. |
If called getStatistics function, this event will be triggered once the statistics get finished.
Parameters
sessionId | The session ID of the call. |
statistics | The session call statistics. |
fired When available audio devices changed or audio device currently in use changed.
Parameters
audioDevice | device currently in use |
devices | devices useable. If a wired headset is connected, it should be the only possible option. When no wired headset connected, the devices set may contain speaker, earpiece, Bluetooth devices. can be set by PortSipSdk#setAudioDevice to switch to current device. |
fired when the audio focus has been changed.
Parameters
focusChange | the type of focus change, one of AudioManager::AUDIOFOCUS_GAIN, AudioManager::AUDIOFOCUS_LOSS, AudioManager::AUDIOFOCUS_LOSS_TRANSIENT and AudioManager::AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK. |
RTP callback events
If enableRtpCallback function is called to enable the RTP callback, this event will be triggered once a RTP packet is received or sent.
Parameters
sessionId | The session ID of the call. |
mediaType | RTP packet media type, 0 for audio, 1 for video , 2 for screen. |
enum_direction | RTP packet direction enum_DIRECTION_SEND, enum_DIRECTION_RECV. |
RTPPacket | The received or sent RTP packet. |
packetSize | The size of the RTP packet in bytes. |
Remarks
Donot call any SDK API functions in this event directly. If you want to call the API functions or other code which is time-consuming, you should post a message to another thread and execute SDK API functions or other code in another thread.
This event will be triggered once receiving the audio packets if called enableAudioStreamCallback function.
Parameters
sessionId | The session ID of the call. |
enum_direction | The type passed in enableAudioStreamCallback function. Below types allowed: enum_DIRECTION_SEND, enum_DIRECTION_RECV. |
data | The memory of audio stream. It's in PCM format. |
dataLength | The data size. |
samplingFreqHz | The audio stream sample in HZ. For example, 8000 or 16000. |
Remarks
Don't call any SDK API functions in this event directly. If you want to call the API functions or other code which is time-consuming, you should post a message to another thread and execute SDK API functions or other code in another thread.
See also
PortSipSdk::enableAudioStreamCallback
This event will be triggered once receiving the video packets if enableVideoStreamCallback function is called.
Parameters
sessionId | The session ID of the call. |
enum_direction | The type which is passed in enableVideoStreamCallback function. Below types allowed: enum_DIRECTION_SEND, enum_DIRECTION_RECV. |
width | The width of video image. |
height | The height of video image. |
data | The memory of video stream. It's in YUV420 format, YV12. |
dataLength | The data size. |
See also
PortSipSdk::enableVideoStreamCallback
SDK functions*
Initialize and register functions
Initialize the SDK.
Parameters
enum_transport | Transport for SIP signaling, which can be set as: ENUM_TRANSPORT_UDP, ENUM_TRANSPORT_TCP, ENUM_TRANSPORT_TLS, |
localIP | The local PC IP address (for example: 192.168.1.108). It will be used for sending and receiving SIP messages and RTP packets. ` `If the local IP is provided in IPv6 format, the SDK will use IPv6. ` `If you want the SDK to choose correct network interface (IP) automatically, please use "0.0.0.0" for IPv4, or "::" for IPv6. |
localSIPPort | The listening port for SIP message transmission, for example 5060. |
enum_LogLevel | Set the application log level. The SDK will generate "PortSIP_Log_datatime.log" file if the log is enabled. ENUM_LOG_LEVEL_NONE ENUM_LOG_LEVEL_DEBUG |
ENUM_LOG_LEVEL_ERROR ENUM_LOG_LEVEL_WARNING | |
ENUM_LOG_LEVEL_INFO ENUM_LOG_LEVEL_DEBUG | |
LogPath | The path for storing log file. The path (folder) specified MUST be existent. |
maxLines | Theoretically, unlimited count of lines are supported depending on the device capability. For SIP client, it is recommended to limit it as ranging 1 - 100. |
agent | The User-Agent header to be inserted in to SIP messages. |
audioDeviceLayer | Specifies the audio device layer that should be using: 0 = Use the OS defaulted device. |
1 = Virtual device, usually use this for the device that has no sound device installed. | |
videoDeviceLayer | Specifies the video device layer that should be using: 0 = Use the OS defaulted device. 1 = Use Virtual device, usually use this for the device that has no camera installed. |
TLSCertificatesRo otPath | Specify the TLS certificate path, from which the SDK will load the certificates automatically. Note: On Windows, this path will be ignored, and SDK will read the certificates from Windows certificates stored area instead. |
TLSCipherList | Specify the TLS cipher list. This parameter is usually passed as empty so that the SDK will offer all available ciphers. |
verifyTLSCertificate | Indicate if SDK will verify the TLS certificate or not. By setting to false, the SDK will not verify the validity of TLS certificate. |
dnsServers | Additional Nameservers DNS servers. Value null indicates system DNS Server. Multiple servers will be split by ";", e.g "8.8.8.8;8.8.4.4" |
Returns
If the function succeeds, it returns value 0. If the function fails, it will return a specific error code
Un-initialize the SDK and release resources.
Set the instance Id, the outbound instanceId((RFC5626) ) used in contact headers.
Parameters
instanceId | The SIP instance ID. If this function is not called, the SDK will generate an instance ID automatically. The instance ID MUST be unique on the same device (device ID or IMEI ID is recommended). Recommend to call this function to set the ID on Android devices. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set user account info.
Parameters
userName | Account (username) of the SIP, usually provided by an IP-Telephony service provider. |
displayName | The name displayed. You can set it as your like, such as "James Kend". It's optional. |
authName | Authorization user name (usually equal to the username). |
password | User's password. It's optional. |
userDomain | User domain; this parameter is optional, which allows to transfer an empty string if you are not using the domain. |
SIPServer | SIP proxy server IP or domain, for example xx.xxx.xx.x or sip.xxx.com. |
SIPServerPort | Port of the SIP proxy server, for example 5060. |
STUNServer | Stun server for NAT traversal. It's optional and can be used to transfer empty string to disable STUN. |
STUNServerPort | STUN server port. It will be ignored if the outboundServer is empty. |
outboundServer | Outbound proxy server, for example sip.domain.com. It's optional and allows to transfer an empty string if not using the outbound server. |
outboundServerPort | Outbound proxy server port, it will be ignored if the outboundServer is empty. |
Returns
If this function succeeds, it will return value 0. If it fails, it will return a specific error code.
remove user account info.
Register to SIP proxy server (login to server)
Parameters
expires | Time interval for registration refreshment, in seconds. The maximum of supported value is 3600. It will be inserted into SIP REGISTER message headers. |
retryTimes | The maximum of retry attempts if failed to refresh the registration. By setting to <= 0, the attempt will be disabled and onRegisterFailure callback will be triggered when facing retry failure. |
Returns
If this function succeeds, it will return value 0. If fails, it will return a specific error code.
If the registration to server succeeds, onRegisterSuccess will be triggered; otherwise onRegisterFailure will be triggered.
Refresh the registration manually after successfully registered.
Parameters
expires | Time interval for registration refreshment, in seconds. The maximum of supported value is 3600. It will be inserted into SIP REGISTER message headers. |
Returns
If this function succeeds, it will return value 0. If fails, it will return a specific error code.
If the registration to server succeeds, onRegisterSuccess will be triggered; otherwise onRegisterFailure will be triggered.
Un-register from the SIP proxy server.
Parameters
waitMS | Wait for the server to reply that the un-registration is successful, waitMS is the longest waiting milliseconds, 0 means not waiting. |
Returns
If this function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the display name of user.
Parameters
displayName | That will appear in the From/To Header. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the license key. It must be called before setUser function.
Parameters
key | The SDK license key. Please purchase from PortSIP. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Audio and video codecs functions
Enable an audio codec, and it will be shown in SDP.
Parameters
enum_audiocodec |
ENUM_AUDIOCODEC_ISACSWB, ENUM_AUDIOCODEC_OPUS, ENUM_AUDIOCODEC_DTMF. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable a video codec, and it will be shown in SDP.
Parameters
enum_videocodec | Video codec type. Supported types include enum_VIDEOCODEC_H264, enum_VIDEOCODEC_VP8. enum_VIDEOCODEC_VP9. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Detect if the audio codecs are enabled.
Returns
If no audio codec enabled, it will return value true; otherwise it returns false.
Detect if the video codecs are enabled.
Returns
If no video codec enabled, it will return value true; otherwise it returns false.
Set the RTP payload type for dynamic audio codec.
Parameters
enum_audiocodec | Audio codec type, which is defined in the PortSIPTypes file. |
payloadType | The new RTP payload type that you want to set. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the RTP payload type for dynamic video codec.
Parameters
enum_videocodec | Video codec type. Supported types include: enum_VIDEOCODEC_H264, enum_VIDEOCODEC_VP8. enum_VIDEOCODEC_VP9. |
payloadType | The new RTP payload type that you want to set. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remove all the enabled audio codecs.
Remove all the enabled video codecs.
Set the codec parameter for audio codec.
Parameters
enum_audiocodec | Audio codec type, defined in the PortSIPTypes file. |
sdpParameter | The parameter is in string format. |
- | - |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
See also
PortSipEnumDefine
Remarks
Example:
setAudioCodecParameter(AUDIOCODEC_AMR, "mode-set=0; octet-align=1; robust-sorting=0"![])
Set the codec parameter for video codec.
Parameters
enum_videocodec | Video codec types. Supported types include: enum_VIDEOCODEC_H264, enum_VIDEOCODEC_VP8. enum_VIDEOCODEC_VP9. |
sdpParameter | The parameter is in string format. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Example:
setVideoCodecParameter(PortSipEnumDefine.enum_VIDEOCODEC_H264, profile-level-id=420033; packetization-mode=0");
Additional settings functions
Get the version number of the current SDK.
Returns
String with version description
Enable/Disable rport(RFC3581).
Parameters
enable | enable Set to true to enable the SDK to support rport. By default it is enabled. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable rport(RFC3581).
Parameters
enable | Set to true to enable the SDK to support rport. By default it is enabled. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code. Enable/Disable Early Media.
Parameters
enable | Set to true to enable the SDK support Early Media. By default the Early Media is disabled. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable which allows specifying the preferred protocol when a domain supports
both IPV4 and IPV6 simultaneously.
Parameters
enable | Set to true to enable priority IPv6 Domain. with the default priority being IPV4. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Modifies the default URI user character needs to be escaped.
Parameters
character | The character to be modified, set one character at a time. |
enable | Whether escaping is required, true for allowing escaping, false for disabling escaping. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/Disable PRACK.
Parameters
mode | Modes work as follows: 0 - Never, Disable PRACK,By default the PRACK is disabled. 1 - SupportedEssential, Only send reliable provisionals if sending a body and far end supports. 2 - Supported, Always send reliable provisionals if far end supports. 3 - Required Always send reliable provisionals. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable the 3Gpp tags, including "ims.icsi.mmtel" and "g.3gpp.smsip".
Parameters
enable | Set to true to enable 3Gpp tags for SDK. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable the callback of the SIP messages.
Parameters
enableSending | Set as true to enable to callback the sent SIP messages, or false to disable. Once enabled, the "onSendingSignaling" event will be triggered when the SDK sends a SIP message. |
enableReceived | Set as true to enable to callback the received SIP messages, or false to disable. Once enabled, the "onReceivedSignaling" event will be triggered when the SDK receives a SIP message. |
Set the SRTP policy.
Parameters
enum_srtppolicy | The SRTP policy.allow: enum_SRTPPOLICY_NONE, enum_SRTPPOLICY _FORCE, enum_SRTPPOLICY_PREFER. |
This function allows to set the RTP port range for audio and video streaming.
Parameters
minimumRtpPort | The minimum RTP port. |
maximumRtpPort | The maximum RTP port. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The port range ((max - min) / maxCallLines) should be greater than 4.
Enable call forwarding.
Parameters
forBusyOnly | If this parameter is set to true, the SDK will forward incoming calls when the user is currently busy. If set it to false, SDK will forward all incoming calls. |
forwardTo | The target to which the call will be forwarded. It must be in the format of sip:xxxx@sip.portsip.com. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Disable the call forwarding. The SDK will not forward any incoming call when this function is called.
Returns
If the function succeeds, it will not return value 0. If the function fails, it will return a specific error code.
This function allows to periodically refresh Session Initiation Protocol (SIP) sessions by
sending repeated INVITE requests.
Parameters
timerSeconds | The value of the refresh interval in seconds. A minimum of 90 seconds required. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The repeated INVITE requests, or re-INVITEs, are sent during an active call log to allow user agents (UA) or proxies to determine the status of a SIP session. Without this keep-alive mechanism, proxies that remember incoming and outgoing requests (stateful proxies) may continue to retain call state in vain. If a UA fails to send a BYE message at the end of a session, or if the BYE message is lost due to network problems, a stateful proxy will not know that the session has ended. The re-INVITES ensure that active sessions stay active and completed sessions are terminated.
Disable the session timer.
Enable/disable the "Do not disturb" status.
Parameters
state | If it is set to true, the SDK will reject all incoming calls. |
Enable/disable the "Auto Check MWI" status.
Parameters
state | If it is set to true, the SDK will check Mwi automatically. |
Enable or disable to send RTP keep-alive packet when the call is ongoing.
Parameters
state | When it's set to true, it's allowed to send the keep-alive packet during the conversation; |
keepAlivePayload Type | The payload type of the keep-alive RTP packet. It's usually set to 126. |
deltaTransmitTime MS | The interval for sending keep-alive RTP packet, in millisecond. Recommended value ranges 15000 - 300000. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable to send SIP keep-alive packet.
Parameters
keepAliveTime | This is the time interval for SIP keep-alive, in seconds. When it is set to 0, the SIP keep-alive will be disabled. Recommended value is 30 or 50. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the audio capture sample, which will be present in the SDP of INVITE and 200 OK message as "ptime and "maxptime" attribute.
Parameters
ptime | It should be a multiple of 10 between 10 - 60 (included 10 and 60). |
maxptime | The "maxptime" attribute should be a multiple of 10 between 10 - 60 (included 10 and 60). It can't be less than "ptime". |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the SDK to receive SIP messages that include special mime type.
Parameters
methodName | Method name of the SIP message, such as INVITE, OPTION, INFO, MESSAGE, UPDATE, ACK etc. For more details please refer to RFC3261. |
mimeType | The mime type of SIP message. |
subMimeType | The sub mime type of SIP message. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
In default, PortSIP VoIP SDK supports media types (mime types) included in the below incoming SIP messages:
"message/sipfrag" in NOTIFY message.
"application/simple-message-summary" in NOTIFY message.
"text/plain" in MESSAGE message. "application/dtmf-relay" in INFO message. "application/media_control+xml" in INFO message.
The SDK allows to receive SIP messages that include above mime types. Now if remote side send an INFO SIP message with its "Content-Type" header value "text/plain", SDK will reject this INFO message, because "text/plain" of INFO message is not included in the default type list. How should we enable the SDK to receive SIP INFO messages that include "text/plain" mime type? The answer is addSupportedMimyType:
addSupportedMimeType("INFO", "text", "plain");
If the user wishes to receive the NOTIFY message with "application/media_control+xml", it should be set as below:
addSupportedMimeType("NOTIFY", "application", "media_control+xml");
For more details about the mime type, please visit: http://www.iana.org/assignments/media-types/
Access SIP message header functions
Access the SIP header of SIP message.
Parameters
sipMessage | The SIP message. |
headerName | The header of which user wishes to access the SIP message. |
Returns
String. The SIP header of SIP message.
Add the SIP Message header into the specified outgoing SIP message.
Parameters
sessionId | Add the header to the SIP message with the specified session Id only. By setting to -1, it will be added to all messages. |
methodName | Add the header to the SIP message with specified method name only. For example: "INVITE", "REGISTER", "INFO" etc. If "ALL" specified, it will add all SIP messages. |
msgType | 1 refers to apply to the request message, 2 refers to apply to the response message, 3 refers to apply to both request and response. |
headerName | The header name which will appear in SIP message. |
headerValue | The custom header value. |
Returns
If the function succeeds, it will return the addedSipMessageId , which is greater than 0. If the function fails, it will return a specific error code.
Remove the headers (custom header) added by addSipMessageHeader.
Parameters
addedSipMessageI d | The addedSipMessageId return by addSipMessageHeader. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the added extension headers (custom headers)
Remarks
For example, we have added two custom headers into every outgoing SIP message and want to have them removed.
If this function is called, the added extension headers will no longer appear in outgoing SIP message.
Modify the special SIP header value for every outgoing SIP message.
Parameters
sessionId | The header to the SIP message with the specified session Id. By setting to -1, it will be added to all messages. |
methodName | Modify the header to the SIP message with specified method name only. For example: "INVITE", "REGISTER", "INFO" etc. If "ALL" specified, it will add all SIP messages. |
msgType | 1 refers to apply to the request message, 2 refers to apply to the response message, 3 refers to apply to both request and response. |
headerName | The SIP header name of which the value will be modified. |
headerValue | The heaver value to be modified. |
Returns
If the function succeeds, it will return modifiedSipMessageId, which is greater than 0. If the function fails, it will return a specific error code.
Remarks
Example: modify "Expires" header and "User-Agent" header value for every outgoing SIP message:
modifySipMessageHeader(-1,"ALL",3, "Expires", "1000"); modifySipMessageHeader(-1,"ALL",3, "User-Agent", "MyTest Softphone 1.0");
Remove the headers (custom header) added by modifiedSipMessageId.
Parameters
modifiedSipMessa geId | The modifiedSipMessageId return by modifySipMessageHeader. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the modify headers value. Once cleared, it will no longer modify every outgoing SIP message header values.
Remarks Example: modify two headers value for every outgoing SIP message and then clear it:
Parameters
Audio and video functions
Set the video device that will be used for video call. Parameters
deviceId | Device ID (index) for video device (camera). |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Setting the video Device Orientation.
Parameters
rotation | Device Orientation for video device (camera), e.g 0,90,180,270. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set enable/disable video Hardware codec.
enableHWEncoder | If it is set to true, the SDK will use video hardware encoder when available. By default it is true. |
enableHWDecoder | If it is set to true, the SDK will use video hardware decoder when available. By default it is true. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video capturing resolution.
Parameters
width | Video resolution, width |
height | Video resolution, height |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the audio bitrate. Parameters
sessionId | The session ID of the call. |
enum_audiocodec | Audio codec type allowed: enum_AUDIOCODEC_OPUS |
bitrateKbps | The Audio bitrate in KBPS. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video bitrate.
Parameters
sessionId | The session ID of the call. |
bitrateKbps | The video bitrate in KBPS. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video frame rate. Usually you do not need to call this function to set the frame rate since the SDK uses default frame rate.
Parameters
sessionId | The session ID of the call. |
frameRate | The frame rate value, with its minimum of 5, and maximum value of 30. The greater the value is, the better video quality enabled and more bandwidth required; |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send the video to remote side.
Parameters
sessionId | The session ID of the call. |
send | Set to true to send the video, or false to stop sending. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the window for a session that is used for displaying the received remote video image.
Parameters
sessionId | The session ID of the call. |
renderer | SurfaceView a SurfaceView for displaying the received remote video image. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the window for a session that is used for displaying the received remote screen image.
Parameters
sessionId | The session ID of the call. |
renderer | SurfaceView a SurfaceView for displaying the received remote screen image. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Start/stop displaying the local video image.
Parameters
state | Set to true to display local video image. |
mirror | Set to true to display the mirror image of local video. |
renderer | SurfaceView a SurfaceView for displaying local video image from camera. |
Enable/disable the NACK feature (rfc6642) which helps to improve the video quality.
Parameters
state | Set to true to enable. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set a volume |scaling| to be applied to the outgoing signal of a specific audio channel.
47 Parameters
sessionId | The session ID of the call. |
scaling | Valid scale ranges [0, 1000]. Default is 100. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set a volume |scaling| to be applied to the microphone signal of a specific audio channel.
Parameters
sessionId | The session ID of the call. |
scaling | Valid scale ranges [0, 1000]. Default is 100. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
enable/disable sdk audio manager,when enable sdk will auto manager audio device input/output. if the state is enabled, the onAudioDeviceChanged event will be triggered when available audio devices changed or audio device currently in use changed .
Parameters
state | @true enable sdk audio manager @false disable audio manager |
Get current set of available/selectable audio devices.
Returns
Current set of available/selectable audio devices.
Set the audio device that will used for audio call. For Android and iOS, switch between earphone and Loudspeaker allowed.
Parameters
defaultDevice | Set to true the SDK use loudspeaker for audio call, this just available for mobile platform only. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Call functions
Make a call
Parameters
callee | The callee. It can be a name only or full SIP URI, for example: user001 or sip:user001@sip.iptel.org or sip:user002@sip.yourdomain.com:5068 |
sendSdp | If it is set to false, the outgoing call will not include the SDP in INVITE message. |
videoCall | If it is set to true and at least one video codec was added, the outgoing call will include the video codec into SDP. Otherwise no video codec will be added into outgoing SDP. |
Returns
If the function succeeds, it will return the session ID of the call, which is greater than 0. If the function fails, it will return a specific error code.
Note: the function success just means the outgoing call is processing, you need to detect the call final state in onInviteTrying, onInviteRinging, onInviteFailure callback events.
rejectCall Reject the incoming call.
Parameters
sessionId | The session ID of the call. |
code | Reject code, for example, 486, 480 etc. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
hangUp Hang up the call.
Parameters
sessionId | Session ID of the call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
answerCall Answer the incoming call.
Parameters
sessionId | The session ID of call. |
videoCall | If the incoming call is a video call and the video codec is matched, set to true to answer the video call. If set to false, the answer call does not include video codec answer anyway. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
updateCall Use the re-INVITE to update the established call.
Parameters
sessionId | The session ID of call. |
enableAudio | Set to true to allow the audio in updated call, or false to disable audio in updated call. |
enableVideo | Set to true to allow the video in update call, or false to disable video in updated call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return specific error code.
Remarks
Example usage:
Example 1: A called B with the audio only, and B answered A, there would be an audio conversation between A and B. Now A want to see B through video, A could use these functions to fulfill it.
clearVideoCodec(); addVideoCodec(VIDEOCODEC_H264); updateCall(sessionId, true, true);
Example 2: Remove video stream from the current conversation. updateCall(sessionId, true, false);
To place a call on hold.
Parameters
sessionId | The session ID of call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Take off hold.
Parameters
sessionId | The session ID of call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Mute the specified audio or video session.
Parameters
sessionId | The session ID of the call. |
muteIncomingAudi o | Set it to true to mute incoming audio stream. Once set, remote side audio cannot be heard. |
muteOutgoingAudi o | Set it to true to mute outgoing audio stream. Once set, the remote side cannot hear the audio. |
muteIncomingVide o | Set it to true to mute incoming video stream. Once set, remote side video cannot be seen. |
muteOutgoingVide o | Set it to true to mute outgoing video stream, the remote side cannot see the video. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Forward call to another one when receiving the incoming call.
Parameters
sessionId | The session ID of the call. |
forwardTo | Target of the forward. It can be either "sip:number@sipserver.com" or "number". |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
This function will be used for picking up a call based on the BLF (Busy Lamp Field) status.
Parameters
replaceDialogId | The ID of the call which will be pickup. It comes with onDialogStateUpdated callback. |
videoCall | Indicates pickup video call or audio call |
If the function succeeds, it will return a session ID that is greater than 0 to the new call, otherwise returns a specific error code that is less than 0.
Remarks
The scenario is:
User 101 subscribed the user 100's call status: sendSubscription(mSipLib, "100", "dialog");
When 100 holds a call or 100 is ringing, onDialogStateUpdated callback will be triggered, and 101 will receive this callback. Now 101 can use pickupBLFCall function to pick the call rather than 100 to talk with caller.
Send DTMF tone.
Parameters
sessionId | The session ID of the call. | ||
enum_dtmfMethod | DTMF tone could be sent via two methods: DTMF_RFC2833 or DTMF_INFO. The DTMF_RFC2833 is recommend. | ||
code | The DTMF tone. Values include: | ||
code | Description | ||
0 | The DTMF tone 0. | ||
1 | The DTMF tone 1. | ||
2 | The DTMF tone 2. | ||
3 | The DTMF tone 3. | ||
4 | The DTMF tone 4. | ||
5 | The DTMF tone 5. | ||
6 | The DTMF tone 6. | ||
7 | The DTMF tone 7. | ||
8 | The DTMF tone 8. | ||
9 | The DTMF tone 9. | ||
10 | The DTMF tone *. | ||
11 | The DTMF tone #. | ||
12 | The DTMF tone A. | ||
13 | The DTMF tone B. | ||
14 | The DTMF tone C. | ||
15 | The DTMF tone D. | ||
16 | The DTMF tone FLASH. |
Parameters
dtmfDuration | The DTMF tone samples. Recommended value 160. |
playDtmfTone | Set to true the SDK play local DTMF tone sound during send DTMF. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Refer functions
Transfer the current call to another callee.
Parameters
sessionId | The session ID of the call. |
referTo | Target callee of the transfer. It can be either "sip:number@sipserver.com" or "number". |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
refer(sessionId, "sip:testuser12@sip.portsip.com");
You can refer to the video on Youtube at:
https://www.youtube.com/watch?v=_2w9EGgr3FY, which will demonstrate how to complete the transfer.
Make an attended refer. Parameters
sessionId | The session ID of the call. |
replaceSessionId | Session ID of the replace call. |
referTo | Target callee of the refer. It can be either "sip:number@sipserver.com" or "number". |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Please read the sample project source code to get more details, or you can refer to the video on YouTube at:
https://www.youtube.com/watch?v=_2w9EGgr3FY
Note: Please use Windows Media Player to play the AVI file, which demonstrates how to complete the transfer.
Make an attended refer.
Parameters
sessionId | The session ID of the call. |
replaceSessionId | The session ID of the session to be replaced. |
replaceMethod | The SIP method name to be added in the "Refer-To" header, usually INVITE or BYE. |
target | The target to which the REFER message will be sent. |
referTo | The URI to be added into the "Refer-To" header. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Make an attended refer.
Parameters
replaceSessionId | The session ID of the session which will be replaced. |
replaceMethod | The SIP method name which will be added in the "Refer-To" header, usually INVITE or BYE. |
target | The target to which the REFER message will be sent. |
referTo | The URI which will be added into the "Refer-To" header. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
By accepting the REFER request, a new call will be made if this function is called. The
function is usually called after onReceivedRefer callback event.
Parameters
referId | The ID of REFER request that comes from onReceivedRefer callback event. |
referSignaling | The SIP message of REFER request that comes from onReceivedRefer callback event. |
Returns
If the function succeeds, it will return a session ID greater than 0 to the new call for REFER; otherwise it will return a specific error code less than 0;
Reject the REFER request.
Parameters
referId | The ID of REFER request that comes from onReceivedRefer callback event. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send audio and video stream functions
Enable the SDK send PCM stream data to remote side from another source instead of microphone. This function MUST be called first to send the PCM stream data to another
side.
Parameters
sessionId | The session ID of call. |
state | Set to true to enable the send stream, or false to disable. |
streamSamplesPer Sec | The PCM stream data sample, in seconds. For example 8000 or 16000. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send the audio stream in PCM format from another source instead of audio device
capturing (microphone).
Parameters
sessionId | Session ID of the call conversation. |
data | The PCM audio stream data. It must be 16bit, mono. |
dataLength | The size of data. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Usually we should use it like below:
You can't have too much audio data at one time as we have 100ms audio buffer only. Once you put too much, data will be lost. It is recommended to send 20ms audio data every 20ms.
Enable the SDK to send video stream data to remote side from another source instead of camera.
This function MUST be called first to send the video stream data to another side.
Parameters
sessionId | The session ID of call. |
state | Set to true to enable the send stream, or false to disable. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send the video stream in i420 from another source instead of video device capturing (camera).
Before calling this function, you MUST call the enableSendVideoStreamToRemote function.
Parameters
sessionId | Session ID of the call conversation. |
data | The video stream data. It must be in i420 format. |
dataLength | The size of data. |
width | The width of the video image. |
height | The height of video image. |
Returns
If the function succeeds, it will return value is 0. If the function fails, it will return a specific error code.
RTP packets, Audio stream and video stream callback
Set the RTP callbacks to allow access to the sent and received RTP packets.
Parameters
sessionId | The session ID of the call. |
mediaType | RTP packet media type, 0 for audio, 1 for video , 2 for screen. |
directionMode | RTP packet direction, 0 for sending, 1 for receiving. |
Returns
If the function succeeds, it will return value is 0. If the function fails, it will return a specific error code.
Enable/disable the audio stream callback. The onAudioRawCallback event will be triggered if the callback is enabled.
Parameters
sessionId | The session ID of call. |
enable | Set to true to enable audio stream callback, or false to stop the callback. |
enum_direction | The audio stream callback mode. Supported modes include ENUM_DIRECTION_NONE, ENUM_DIRECTION_SEND, |
ENUM_DIRECTION_RECV ENUM_DIRECTION_SEND_RECV. |
Enable/disable the video stream callback, the onVideoRawCallback event will be triggered if the callback is enabled.
Parameters
sessionId | The session ID of call. |
enum_direction | The video stream callback mode. Supported modes include ENUM_DIRECTION_NONE, ENUM_DIRECTION_SEND, |
ENUM_DIRECTION_RECV, ENUM_DIRECTION_SEND_RECV. |
Record functions
Start recording the call.
Parameters
sessionId | The session ID of call conversation. |
recordFilePath | The file path to save record file. It must be existent. |
recordFileName | The file name of record file. For example audiorecord.wav or videorecord.avi. |
appendTimeStamp | Set to true to append the timestamp to the name of the recording file. |
audioChannels | Set to record file audio channels, 1 - mono 2 - stereo. |
enum_fileFormat | The record file format, allow below values: enum_FILE_FORMAT_WAVE = 1, ///< The record audio file is WAVE format. enum_FILE_FORMAT_AMR =2, ///< The record audio file is in AMR format with all voice data compressed by AMR codec. enum_FILE_FORMAT_MP3 = 3;///< The record audio file is in MP3 format. enum_FILE_FORMAT_MP4 = 4;///< The record video file is in MP4(AAC and H264) format. |
enum_audioRecor dMode | The audio record mode, allow below values: enum_RECORD_MODE_NONE = 0, ///< Not Record. enum_RECORD_MODE_RECV = 1, ///< Only record the received data. enum_RECORD_MODE_SEND, ///< Only record send data. enum_RECORD_MODE_BOTH ///< Record both received and sent data. |
enum_videoRecord Mode | Allow to set video record mode. Support to record received and/or sent video. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop recording.
Parameters
sessionId | The session ID of call conversation. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Play audio and video file and RTMP/RTSP stream functions
Play an local file or RTSP/RTMP stream to remote party.
Parameters
sessionId | Session ID of the call. |
fileUrl | The url or filepath, such as "/mnt/sdcard/test.avi". |
loop | Set to false to stop playing video file when it is ended, or true to play it repeatedly. |
playAudio | 0 - Not play file audio. 1 - Play file audio. 2 - Play file audio mix with Mic. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop play file to remote side.
Parameters
sessionId | Session ID of the call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Play an local file or RTSP/RTMP stream.
Parameters
fileUrl | The url or filepath, such as "/mnt/sdcard/test.avi". |
loop | Set to false to stop playing video file when it is ended, or true to play it repeatedly. |
renderer | SurfaceView a SurfaceView for displaying the play image. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop play file locally.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Used for testing loopback for the audio device.
Parameters
enable | Set to true to start testing audio loopback test; or set to false to stop. |
Conference functions
Create an audio conference. It will fail if the existing conference is not ended yet. Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Create a video conference. It will fail if the existing conference is not ended yet.
Parameters
conferenceVideoW indow | SurfaceView The window used for displaying the conference video. |
videoWidth | Width of conference video resolution |
videoHeight | Height of conference video resolution |
layout | Conference Video layout, default is 0 - Adaptive. 0 - Adaptive(1,3,5,6) 1 - Only Local Video 2 - 2 video,PIP 3 - 2 video, Left and right 4 - 2 video, Up and Down 5 - 3 video 6 - 4 split video 7 - 5 video |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
End the exist conference.
Set the window for a conference that is used for displaying the received remote video
image.
Parameters
conferenceVideoWindow | SurfaceView The window which is used for displaying the conference vide |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Join a session into existing conference. If the call is in hold, it will be un-hold
automatically.
Parameters
sessionId | Session ID of the call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remove a session from an existing conference.
Parameters
sessionId | Session ID of the call. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
RTP and RTCP QOS functions
Set the audio RTCP bandwidth parameters as RFC3556.
Parameters
sessionId | Set the audio RTCP bandwidth parameters as RFC3556. |
BitsRR | The bits for the RR parameter. |
BitsRS | The bits for the RS parameter. |
KBitsAS | The Kbits for the AS parameter. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video RTCP bandwidth parameters as the RFC3556.
Parameters
sessionId | The session ID of call conversation. |
BitsRR | The bits for the RR parameter. |
BitsRS | The bits for the RS parameter. |
KBitsAS | The Kbits for the AS parameter. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the DSCP (differentiated services code point) value of QoS (Quality of Service) for audio channel.
Parameters
state | Set to YES to enable audio QoS and DSCP value will be 46; or NO to disable audio QoS and DSCP value will be 0. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the DSCP(differentiated services code point) value of QoS(Quality of Service) for video channel.
Parameters
state | Set to YES to enable video QoS and DSCP value will be 34; or NO to disable video QoS and DSCP value will be 0. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the MTU size for video RTP packet.
Parameters
mtu | Set MTU value. Allow values range 512 - 65507. Default is 14000. |
Returns
If the function succeeds, the return value is 0. If the function fails, the return value is a specific error code.
RTP statistics functions
Obtain the statistics of channel. the event onStatistics will be triggered.
Parameters
sessionId | The session ID of call conversation. |
Returns
If the function succeeds, it will return value is 0. If the function fails, it will return a specific error code.
Audio effect functions
Enable/disable Voice Activity Detection(VAD).
Parameters
state | Set to true to enable VAD, or false to disable. |
Enable/disable AEC (Acoustic Echo Cancellation).
Parameters
state | Set to true to enable AEC, or false to disable. |
Enable/disable Comfort Noise Generator(CNG).
Parameters
state | Set to true to enable CNG, or false to disable. |
Enable/disable Automatic Gain Control(AGC).
Parameters
state | Set to true to enable AEC, or false to disable. |
Enable/disable Audio Noise Suppression(ANS).
Parameters
state | Set to true to enable ANS, or false to disable. |
Send OPTIONS/INFO/MESSAGE functions
Send OPTIONS message.
Parameters
to | The recipient of OPTIONS message. |
sdp | The SDP of OPTIONS message. It's optional if user does not want to send the SDP with OPTIONS message. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
Send a INFO message to remote side in dialog.
Parameters
sessionId | The session ID of call. |
mimeType | The mime type of INFO message. |
subMimeType | The sub mime type of INFO message. |
infoContents | The contents that will be sent with INFO message. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a MESSAGE message to remote side in dialog.
Parameters
sessionId | The session ID of call. |
mimeType | The mime type of MESSAGE message. |
subMimeType | The sub mime type of MESSAGE message. |
message | The contents that will be sent with MESSAGE message. Binary data allowed. |
messageLength | The message size. |
Returns
If the function succeeds, it will return a message ID that allows to track the message sending state in onSendMessageSuccess and onSendMessageFailure. If the function fails, it will return a specific error code that is less than 0.
Remarks
Example 1: Send a plain text message. Note: to send other languages text, please use the UTF8 to encode the message before sending.
sendMessage(sessionId, "text", "plain", "hello",6);
Example 2: Send a binary message.
sendMessage(sessionId, "application", "vnd.3gpp.sms", binData, binDataSize);
Send a out of dialog MESSAGE message to remote side.
Parameters
to | The message receiver. Likes sip:receiver@portsip.com |
mimeType | The mime type of MESSAGE message. |
subMimeType | The sub mime type of MESSAGE message. |
isSMS | Set to YES to specify "messagetype=SMS" in the To line, or NO to disable. |
message | The contents that will be sent with MESSAGE message. Binary data allowed. |
messageLength | The message size. |
Returns
If the function succeeds, it will return a message ID that allows to track the message sending state in onSendOutOfMessageSuccess and onSendOutOfMessageFailure. If the function fails, it will return a specific error code that is less than 0.
Remarks
Example 1: Send a plain text message. Note: to send other languages text, please use the UTF8 to encode the message before sending.
sendOutOfDialogMessage("sip:user1@sip.portsip.com", "text", "plain", "hello", 6);
Example 2: Send a binary message.
sendOutOfDialogMessage("sip:user1@sip.portsip.com","application", "vnd.3gpp.sms", binData, binDataSize);
Indicate the SDK uses the P2P mode for presence or presence agent mode.
Parameters
mode | 0 - P2P mode; 1 - Presence Agent mode. Default is P2P mode. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Since presence agent mode requires the PBX/Server support the PUBLISH, please ensure you have your server and PortSIP PBX support this feature. For more details please visit: https://www.portsip.com/portsip-pbx
Set the default expiration time to be used when creating a subscription.
Parameters
secs | The default expiration time of subscription. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the default expiration time to be used when creating a publication.
Parameters
secs | The default expiration time of publication. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a SUBSCRIBE message for presence to a contact.
Parameters
contact | The target contact, it must be in the format of sip:contact001@sip.portsip.com. |
subject | This subject text will be inserted into the SUBSCRIBE message. For example: "Hello, I'm Jason". The subject maybe is in UTF8 format. You should use UTF8 to decode it. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Terminate the given presence subscription.
Parameters
subscribeId | The ID of the subscription. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Accept the presence SUBSCRIBE request which received from contact.
Parameters
subscribeId | Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event includes the subscription ID. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Reject a presence SUBSCRIBE request received from contact.
Parameters
subscribeId | Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event inclues the subscription ID. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a NOTIFY message to contact to notify that presence status is online/offline/changed.
Parameters
subscribeId | Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe that includes the Subscription ID will be triggered. |
statusText | The state text of presence status. For example: "I'm here", offline must use "offline" |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a SUBSCRIBE message to subscribe an event.
Parameters
to | The user/extension will be subscribed. |
eventName | The event name to be subscribed. |
Returns
If the function succeeds, it will return the ID of that SUBSCRIBE which is greater than 0. If the function fails, it will return a specific error code which is less than 0.
Remarks
Example 1, below code indicates that user/extension 101 is subscribed to MWI (Message Waiting notifications) for checking his voicemail: int32 mwiSubId = sendSubscription("sip:101@test.com", "message-summary");
Example 2, to monitor a user/extension call status, You can use code: sendSubscription(mSipLib, "100", "dialog"); Extension 100 refers to the user/extension to be monitored. Once being monitored, when extension 100 hold a call or is ringing, the onDialogStateUpdated callback will be triggered.
Terminate the given subscription.
Parameters
subscribeId | The ID of the subscription. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
For example, if you want stop check the MWI, use below code:
terminateSubscription(mwiSubId);
Class Documentation
com.portsip.PortSipEnumDefine
com.portsip.PortSipEnumDefine.AudioDevice Enum Reference
Public Attributes
SPEAKER_PHONE
WIRED_HEADSET
EARPIECE
BLUETOOTH
NONE
Detailed Description
AudioDevice list possible audio devices that we currently support.
Static Public Attributes
static final int enum_AUDIOCODEC_G729 = 18
static final int enum_AUDIOCODEC_PCMA = 8
static final int enum_AUDIOCODEC_PCMU = 0
static final int enum_AUDIOCODEC_GSM = 3
static final int enum_AUDIOCODEC_G722 = 9
static final int enum_AUDIOCODEC_ILBC = 97
static final int enum_AUDIOCODEC_AMR = 98
static final int enum_AUDIOCODEC_AMRWB = 99
static final int enum_AUDIOCODEC_SPEEX = 100
static final int enum_AUDIOCODEC_SPEEXWB =102
static final int enum_AUDIOCODEC_ISACWB = 103
static final int enum_AUDIOCODEC_ISACSWB =104
static final int enum_AUDIOCODEC_OPUS =105
static final int enum_AUDIOCODEC_DTMF = 101
static final int enum_VIDEOCODEC_NONE = -1
static final int enum_VIDEOCODEC_I420 = 133
static final int enum_VIDEOCODEC_H264 = 125
static final int enum_VIDEOCODEC_VP8 = 120
static final int enum_VIDEOCODEC_VP9 = 122
static final int enum_SRTPPOLICY_NONE = 0
static final int enum_SRTPPOLICY_FORCE = 1
static final int enum_SRTPPOLICY_PREFER = 2
static final int enum_TRANSPORT_UDP = 0
static final int enum_TRANSPORT_TLS = 1
static final int enum_TRANSPORT_TCP = 2
static final int enum_LOG_LEVEL_NONE = -1
static final int enum_LOG_LEVEL_ERROR = 1
static final int enum_LOG_LEVEL_WARNING = 2
static final int enum_LOG_LEVEL_INFO = 3
static final int enum_LOG_LEVEL_DEBUG = 4
static final int enum_DTMF_MOTHOD_RFC2833 = 0
static final int enum_DTMF_MOTHOD_INFO = 1
static final int enum_DIRECTION_NONE = 0
static final int enum_DIRECTION_SEND_RECV = 1
static final int enum_DIRECTION_SEND = 2
static final int enum_DIRECTION_RECV = 3
static final int enum_RECORD_MODE_NONE = 0
static final int enum_RECORD_MODE_RECV = 1
static final int enum_RECORD_MODE_SEND = 2
static final int enum_RECORD_MODE_BOTH = 3
static final int enum_FILE_FORMAT_WAVE = 1
The record audio file is in WAVE format.
static final int enum_FILE_FORMAT_AMR = 2
The record audio file is in AMR format - all voice data are compressed by AMR codec. Mono.
static final int enum_FILE_FORMAT_MP3 = 3 The record audio file is in MP3 format.
static final int enum_FILE_FORMAT_MP4 = 4
The record video file is in MP4(AAC and H264) format. ![ref6]
Member Data Documentation
final int com.portsip.PortSipEnumDefine.enum_VIDEOCODEC_NONE = -1[static]
Used in startRecord only
final int com.portsip.PortSipEnumDefine.enum_VIDEOCODEC_I420 = 133[static]
Used in startRecord only
final int com.portsip.PortSipEnumDefine.enum_DIRECTION_SEND_RECV = 1[static]
both received and sent
final int com.portsip.PortSipEnumDefine.enum_DIRECTION_SEND = 2[static]
Only the sent
final int com.portsip.PortSipEnumDefine.enum_DIRECTION_RECV = 3[static]
Only the received
final int com.portsip.PortSipEnumDefine.enum_RECORD_MODE_NONE = 0[static]
Not Recorded.
final int com.portsip.PortSipEnumDefine.enum_RECORD_MODE_RECV = 1[static]
Only record the received data.
final int com.portsip.PortSipEnumDefine.enum_RECORD_MODE_SEND = 2[static]
Only record the sent data.
final int com.portsip.PortSipEnumDefine.enum_RECORD_MODE_BOTH = 3[static]
Static Public Attributes
static final int ECoreErrorNone = 0
static final int INVALID_SESSION_ID = -1
static final int ECoreAlreadyInitialized = -60000
static final int ECoreNotInitialized = -60001
static final int ECoreSDKObjectNull = -60002
static final int ECoreArgumentNull = -60003
static final int ECoreInitializeWinsockFailure = -60004
static final int ECoreUserNameAuthNameEmpty = -60005
static final int ECoreInitiazeStackFailure = -60006
static final int ECorePortOutOfRange = -60007
static final int ECoreAddTcpTransportFailure = -60008
static final int ECoreAddTlsTransportFailure = -60009
static final int ECoreAddUdpTransportFailure = -60010
static final int ECoreNotSupportMediaType = -60011
static final int ECoreNotSupportDTMFValue = -60012
static final int ECoreAlreadyRegistered = -60021
static final int ECoreSIPServerEmpty = -60022
static final int ECoreExpiresValueTooSmall = -60023
static final int ECoreCallIdNotFound = -60024
static final int ECoreNotRegistered = -60025
static final int ECoreCalleeEmpty = -60026
static final int ECoreInvalidUri = -60027
static final int ECoreAudioVideoCodecEmpty = -60028
static final int ECoreNoFreeDialogSession = -60029
static final int ECoreCreateAudioChannelFailed = -60030
static final int ECoreSessionTimerValueTooSmall = -60040
static final int ECoreAudioHandleNull = -60041
static final int ECoreVideoHandleNull = -60042
static final int ECoreCallIsClosed = -60043
static final int ECoreCallAlreadyHold = -60044
static final int ECoreCallNotEstablished = -60045
static final int ECoreCallNotHold = -60050
static final int ECoreSipMessaegEmpty = -60051
static final int ECoreSipHeaderNotExist = -60052
static final int ECoreSipHeaderValueEmpty = -60053
static final int ECoreSipHeaderBadFormed = -60054
static final int ECoreBufferTooSmall = -60055
static final int ECoreSipHeaderValueListEmpty = -60056
static final int ECoreSipHeaderParserEmpty = -60057
static final int ECoreSipHeaderValueListNull = -60058
static final int ECoreSipHeaderNameEmpty = -60059
static final int ECoreAudioSampleNotmultiple = -60060
static final int ECoreAudioSampleOutOfRange = -60061
static final int ECoreInviteSessionNotFound = -60062
static final int ECoreStackException = -60063
static final int ECoreMimeTypeUnknown = -60064
static final int ECoreDataSizeTooLarge = -60065
static final int ECoreSessionNumsOutOfRange = -60066
static final int ECoreNotSupportCallbackMode = -60067
static final int ECoreNotFoundSubscribeId = -60068
static final int ECoreCodecNotSupport = -60069
static final int ECoreCodecParameterNotSupport = -60070
static final int ECorePayloadOutofRange = -60071
static final int ECorePayloadHasExist = -60072
static final int ECoreFixPayloadCantChange = -60073
static final int ECoreCodecTypeInvalid = -60074
static final int ECoreCodecWasExist = -60075
static final int ECorePayloadTypeInvalid = -60076
static final int ECoreArgumentTooLong = -60077
static final int ECoreMiniRtpPortMustIsEvenNum = -60078
static final int ECoreCallInHold = -60079
static final int ECoreNotIncomingCall = -60080
static final int ECoreCreateMediaEngineFailure = -60081
static final int ECoreAudioCodecEmptyButAudioEnabled = -60082
static final int ECoreVideoCodecEmptyButVideoEnabled = -60083
static final int ECoreNetworkInterfaceUnavailable = -60084
static final int ECoreWrongDTMFTone = -60085
static final int ECoreWrongLicenseKey = -60086
static final int ECoreTrialVersionLicenseKey = -60087
static final int ECoreOutgoingAudioMuted = -60088
static final int ECoreOutgoingVideoMuted = -60089
static final int ECoreFailedCreateSdp = -60090
static final int ECoreTrialVersionExpired = -60091
static final int ECoreStackFailure = -60092
static final int ECoreTransportExists = -60093
static final int ECoreUnsupportTransport = -60094
static final int ECoreAllowOnlyOneUser = -60095
static final int ECoreUserNotFound = -60096
static final int ECoreTransportsIncorrect = -60097
static final int ECoreCreateTransportFailure = -60098
static final int ECoreTransportNotSet = -60099
static final int ECoreECreateSignalingFailure = -60100
static final int ECoreArgumentIncorrect = -60101
static final int ECoreIVRObjectNull = -61001
static final int ECoreIVRIndexOutOfRange = -61002
static final int ECoreIVRReferFailure = -61003
static final int ECoreIVRWaitingTimeOut = -61004
static final int EAudioFileNameEmpty = -70000
static final int EAudioChannelNotFound = -70001
static final int EAudioStartRecordFailure = -70002
static final int EAudioRegisterRecodingFailure = -70003
static final int EAudioRegisterPlaybackFailure = -70004
static final int EAudioGetStatisticsFailure = -70005
static final int EAudioPlayFileAlreadyEnable = -70006
static final int EAudioPlayObjectNotExist = -70007
static final int EAudioPlaySteamNotEnabled = -70008
static final int EAudioRegisterCallbackFailure = -70009
static final int EAudioCreateAudioConferenceFailure = -70010
static final int EAudioOpenPlayFileFailure = -70011
static final int EAudioPlayFileModeNotSupport = -70012
static final int EAudioPlayFileFormatNotSupport = -70013
static final int EAudioPlaySteamAlreadyEnabled = -70014
static final int EAudioCreateRecordFileFailure = -70015
static final int EAudioCodecNotSupport = -70016
static final int EAudioPlayFileNotEnabled = -70017
static final int EAudioPlayFileUnknowSeekOrigin = -70018
static final int EAudioCantSetDeviceIdDuringCall =-70019
static final int EAudioVolumeOutOfRange =-70020
static final int EVideoFileNameEmpty = -80000
static final int EVideoGetDeviceNameFailure = -80001
static final int EVideoGetDeviceIdFailure = -80002
static final int EVideoStartCaptureFailure = -80003
static final int EVideoChannelNotFound = -80004
static final int EVideoStartSendFailure = -80005
static final int EVideoGetStatisticsFailure = -80006
static final int EVideoStartPlayAviFailure = -80007
static final int EVideoSendAviFileFailure = -80008
static final int EVideoRecordUnknowCodec = -80009
static final int EVideoCantSetDeviceIdDuringCall = -80010
static final int EVideoUnsupportCaptureRotate = -80011
static final int VideoUnsupportCaptureResolution = -80012
static final int ECameraSwitchTooOften = -80013
static final int EMTUOutOfRange = -80014
static final int EDeviceGetDeviceNameFailure = -90001
Last updated