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
libs
directory of the extracted SDK to thelibs
directory 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
OnPortSIPEvent
interface 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
PortSipSdk
class.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
initialize
method 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
When failed to register to SIP server, this event will be triggered.
Parameters
Call events
When a call is coming, this event will be triggered.
Parameters
If the outgoing call is being processed, this event will be triggered.
Parameters
Once the caller received the "183 session progress" message, this event would be triggered.
Parameters
If the outgoing call is ringing, this event will be triggered.
Parameters
If the remote party answered the call, this event would be triggered.
Parameters
This event will be triggered if the outgoing or incoming call fails.
Parameters
This event will be triggered when remote party updates the call.
Parameters
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
If the enableCallForward method is called and a call is incoming, the call will be forwarded automatically and this event will be triggered.
Parameters
This event is triggered once remote side ends the call.
Parameters
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
If the remote side places the call on hold, this event will be triggered.
Parameters
If the remote side un-holds the call, this event will be triggered Parameters
Refer events
This event will be triggered once received a REFER message.
Parameters
This callback will be triggered once remote side calls "acceptRefer" to accept the REFER Parameters
This callback will be triggered once remote side calls "rejectRefer" to reject the REFER Parameters
When the refer call is being processed, this event will be triggered.
Parameters
When the refer call is ringing, this event will be triggered.
Parameters
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
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
Signaling events
This event will be triggered when receiving a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
This event will be triggered when sent a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
MWI events
If there is the waiting voice message (MWI), this event will be triggered.
Parameters
If there is waiting fax message (MWI), this event will be triggered.
Parameters
DTMF events
This event will be triggered when receiving a DTMF tone from remote side.
Parameters
INFO/OPTIONS message events
This event will be triggered when receiving the OPTIONS message.
Parameters
This event will be triggered when receiving the INFO message.
Parameters
This event will be triggered when receiving a NOTIFY message of the subscription.
Parameters
Presence events
This event will be triggered when receiving the SUBSCRIBE request from a contact.
Parameters
When the contact is online or changes presence status, this event will be triggered.
Parameters
When the contact is offline, this event will be triggered.
Parameters
This event will be triggered when receiving a MESSAGE message in dialog.
Parameters
This event will be triggered when receiving a MESSAGE message out of dialog. For example pager message.
Parameters
If the message is sent successfully in dialog, this event will be triggered.
Parameters
If the message is failed to be sent out of dialog, this event will be triggered.
Parameters
If the message is sent successfully out of dialog, this event will be triggered.
Parameters
If the message failed to be sent out of dialog, this event would be triggered.
Parameters
This event will be triggered on sending SUBSCRIBE failure.
Parameters
This event will be triggered when a SUBSCRIPTION is terminated or expired.
Parameters
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
If called getStatistics function, this event will be triggered once the statistics get finished.
Parameters
fired When available audio devices changed or audio device currently in use changed.
Parameters
fired when the audio focus has been changed.
Parameters
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
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
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
See also
PortSipSdk::enableVideoStreamCallback
SDK functions
Initialize and register functions
Initialize the SDK.
Parameters
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Set the SRTP policy.
Parameters
This function allows to set the RTP port range for audio and video streaming.
Parameters
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
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
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
Enable/disable the "Auto Check MWI" status.
Parameters
Enable or disable to send RTP keep-alive packet when the call is ongoing.
Parameters
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
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
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
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
Returns
String. The SIP header of SIP message.
Add the SIP Message header into the specified outgoing SIP message.
Parameters
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