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.
Audio and video stream callback events
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
Was this helpful?