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?

  1. Download the Sample Project and SDK: Obtain the sample project and trial SDK from the PortSIP Website and extract them to a desired directory.

  2. Create a New Project: In Android Studio, create a new Android Application project.

  3. Add the SDK Libraries: Copy all files from the libs directory of the extracted SDK to the libs directory of your new application.

  4. Import Necessary Classes: Import the required classes from the SDK:

    import com.portsip.OnPortSIPEvent;
import com.portsip.PortSipSdk;

How can I process callback events?

  1. Implement the OnPortSIPEvent Interface: Your class should implement the OnPortSIPEvent interface to handle callback events.

  2. Override Callback Methods: Override the necessary callback methods (e.g., onRegistrationState, onCallState) to handle specific events.

How do I initialize the SDK?

  1. Create an Instance: Create an instance of the PortSipSdk class.

  2. Set the Event Listener: Set the event listener using setOnPortSIPEvent.

  3. Create a Call Manager: Create a call manager using CreateCallManager.

  4. 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

void onRegisterSuccess(String reason, int code,String sipMessage);

When successfully registered to server, this event will be triggered.

Parameters

void onRegisterFailure(String reason, int code,String sipMessage);

When failed to register to SIP server, this event will be triggered.

Parameters

Call events

void onInviteIncoming(long sessionId,
                      String callerDisplayName,
                      String caller,
                      String calleeDisplayName,
                      String callee,
                      String audioCodecs,
                      String videoCodecs,
                      boolean existsAudio,
                      boolean existsVideo,
                      String sipMessage);

When a call is coming, this event will be triggered.

Parameters

void onInviteTrying(long sessionId);

If the outgoing call is being processed, this event will be triggered.

Parameters

void onInviteSessionProgress(long sessionId,
                             String audioCodecs,
                             String videoCodecs,
                             boolean existsEarlyMedia,
                             boolean existsAudio,
                             boolean existsVideo,
                             String sipMessage);

Once the caller received the "183 session progress" message, this event would be triggered.

Parameters

void onInviteRinging(long sessionId,
                                String statusText,
                                int statusCode,
                                String sipMessage);

If the outgoing call is ringing, this event will be triggered.

Parameters

void onInviteAnswered(long sessionId,
                      String callerDisplayName,
                      String caller,
                      String calleeDisplayName,
                      String callee,
                      String audioCodecs,
                      String videoCodecs,
                      boolean existsAudio,
                      boolean existsVideo,
                      String sipMessage);

If the remote party answered the call, this event would be triggered.

Parameters

void onInviteFailure(long sessionId, String callerDisplayName,
                                String caller,
                                String calleeDisplayName,
                                String callee,
                                String reason,
                                int code,
                                String sipMessage);

This event will be triggered if the outgoing or incoming call fails.

Parameters

public void onInviteUpdated(long sessionId,
                            String audioCodecs,
                            String videoCodecs,
                            String screenCodecs,
                            boolean existsAudio,
                            boolean existsVideo,
                            boolean existsScreen,
                            String sipMessage);

This event will be triggered when remote party updates the call.

Parameters

void onInviteConnected(long sessionId);

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

void onInviteBeginingForward(String forwardTo);

If the enableCallForward method is called and a call is incoming, the call will be forwarded automatically and this event will be triggered.

Parameters

void onInviteClosed(long sessionId, String sipMessage);

This event is triggered once remote side ends the call.

Parameters

void onDialogStateUpdated(String BLFMonitoredUri,
                          String BLFDialogState,
                          String BLFDialogId,
                          String BLFDialogDirection);

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

void onRemoteHold(long sessionId);

If the remote side places the call on hold, this event will be triggered.

Parameters

void onRemoteUnHold(long sessionId,
                               String audioCodecs,
                               String videoCodecs,
                               boolean existsAudio,
                               boolean existsVideo);

If the remote side un-holds the call, this event will be triggered Parameters

Refer events

    public void onReceivedRefer(long sessionId,
                         long referId,
                         String to,
                         String from,
                         String referSipMessage);

This event will be triggered once received a REFER message.

Parameters

void onReferAccepted(long sessionId);

This callback will be triggered once remote side calls "acceptRefer" to accept the REFER Parameters

void onReferRejected(long sessionId, String reason, int code);

This callback will be triggered once remote side calls "rejectRefer" to reject the REFER Parameters

void onTransferTrying(long sessionId);

When the refer call is being processed, this event will be triggered.

Parameters

void onTransferRinging(long sessionId);

When the refer call is ringing, this event will be triggered.

Parameters

void onACTVTransferSuccess(long sessionId);

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

void onACTVTransferFailure(long sessionId, String reason, int code);

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

void onReceivedSignaling(long sessionId, String message);

This event will be triggered when receiving a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.

Parameters

void onSendingSignaling (long sessionId, String  message)

This event will be triggered when sent a SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.

Parameters

MWI events

void onWaitingVoiceMessage(String messageAccount,
                           int urgentNewMessageCount,
                           int urgentOldMessageCount,
                           int newMessageCount,
                           int oldMessageCount);

If there is the waiting voice message (MWI), this event will be triggered.

Parameters

void onWaitingFaxMessage(String messageAccount,
                         int urgentNewMessageCount,
                         int urgentOldMessageCount,
                         int newMessageCount,
                         int oldMessageCount);

If there is waiting fax message (MWI), this event will be triggered.

Parameters

DTMF events

void onRecvDtmfTone(long sessionId, int tone);

This event will be triggered when receiving a DTMF tone from remote side.

Parameters

INFO/OPTIONS message events

void onRecvOptions(String optionsMessage);

This event will be triggered when receiving the OPTIONS message.

Parameters

void onRecvInfo(String infoMessage);

This event will be triggered when receiving the INFO message.

Parameters

void onRecvNotifyOfSubscription(long subscribeId,String notifyMessage,
                                byte[] messageData,
                                int messageDataLength);

This event will be triggered when receiving a NOTIFY message of the subscription.

Parameters

Presence events

void onPresenceRecvSubscribe(long subscribeId,
                             String fromDisplayName,
                             String from,
                             String subject);

This event will be triggered when receiving the SUBSCRIBE request from a contact.

Parameters

void onPresenceOnline(String fromDisplayName,
                      String from,
                      String stateText);

When the contact is online or changes presence status, this event will be triggered.

Parameters

void onPresenceOffline(String fromDisplayName,
                       String from);

When the contact is offline, this event will be triggered.

Parameters

void onRecvMessage(long sessionId,
                   String mimeType,
                   String subMimeType,
                   byte[] messageData,
                   int messageDataLength);

This event will be triggered when receiving a MESSAGE message in dialog.

Parameters

void onRecvOutOfDialogMessage(String fromDisplayName,
                              String from,
                              String toDisplayName,
                              String to,
                              String mimeType,
                              String subMimeType,
                              byte[] messageData,
                              int messageDataLength,
                              String sipMessage);

This event will be triggered when receiving a MESSAGE message out of dialog. For example pager message.

Parameters

void onSendMessageSuccess(long sessionId, long messageId,String sipMessage);

If the message is sent successfully in dialog, this event will be triggered.

Parameters

void onSendMessageFailure(long sessionId,
                          long messageId,
                          String reason,
                          int code,
                          String sipMessage);

If the message is failed to be sent out of dialog, this event will be triggered.

Parameters

void onSendOutOfDialogMessageSuccess( long messageId,
                                      String fromDisplayName,
                                      String from,
                                      String toDisplayName,
                                      String to,
                                      String sipMessage);

If the message is sent successfully out of dialog, this event will be triggered.

Parameters

void onSendOutOfDialogMessageFailure(long messageId,
                                     String fromDisplayName,
                                     String from,
                                     String toDisplayName,
                                     String to,
                                     String reason,
                                     int code,
                                     String sipMessage);

If the message failed to be sent out of dialog, this event would be triggered.

Parameters

void onSubscriptionFailure(long subscribeId, int statusCode);

This event will be triggered on sending SUBSCRIBE failure.

Parameters

void onSubscriptionTerminated(long subscribeId);

This event will be triggered when a SUBSCRIPTION is terminated or expired.

Parameters

audio device changed,Play audio and video file finished events

void onPlayFileFinished(long sessionId, String fileName);

If called startPlayingFileToRemote function with no loop mode, this event will be triggered once the file play finished.

Parameters

void onStatistics(long sessionId,String statistics);

If called getStatistics function, this event will be triggered once the statistics get finished.

Parameters

void onAudioDeviceChanged(PortSipEnumDefine.AudioDevice audioDevice, Set<PortSipEnumDefine.AudioDevice> devices);

fired When available audio devices changed or audio device currently in use changed.

Parameters

void onAudioFocusChange(int focusChange);

fired when the audio focus has been changed.

Parameters

RTP callback events

void onRTPPacketCallback(long sessionId,
                         int mediaType,
                         int enum_direction,
                         byte[] RTPPacket, 
                         int packetSize);

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

void onAudioRawCallback(long sessionId,
                        int enum_direction,
                        byte[] data, 
                        int dataLength,
                        int samplingFreqHz);

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

void onVideoRawCallback(long sessionId,
                        int enum_direction, 
                        int width, 
                        int height,
                        byte[] data, 
                        int dataLength);

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

int initialize(int enum_transport, 
						  String localIP, 
						  int localSIPPort, 
						  int enum_LogLevel,
						  String LogPath, 
						  int maxLines, 
						  String agent,
						  int audioDeviceLayer, 
						  int videoDeviceLayer, 
						  String TLSCertificatesRootPath,
						  String TLSCipherList, 
						  boolean verifyTLSCertificate, 
						  String dnsServers)

Initialize the SDK.

Parameters

Returns

If the function succeeds, it returns value 0. If the function fails, it will return a specific error code

void unInitialize()

Un-initialize the SDK and release resources.

int setInstanceId(String instanceId)

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.

int setUser(String userName, 
					   String displayName, 
					   String authName,
					   String password, 
					   String userDomain, 
					   String SIPServer, 
					   int SIPServerPort,
					   String STUNServer, 
					   int STUNServerPort, 
					   String outboundServer,
					   int outboundServerPort)

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.

void removeUser()

remove user account info.

int registerServer(int expires, int retryTimes)

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.

int refreshRegistration(int expires)

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.

int unRegisterServer(int waitMS)

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.

int setDisplayName(String displayName)

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.

int setLicenseKey (String  key)

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

int addAudioCodec (int  enum_audiocodec)

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.

int addVideoCodec (int  enum_videocodec)

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.

**boolean isAudioCodecEmpty ()

Detect if the audio codecs are enabled.

Returns

If no audio codec enabled, it will return value true; otherwise it returns false.

**boolean isVideoCodecEmpty ()

Detect if the video codecs are enabled.

Returns

If no video codec enabled, it will return value true; otherwise it returns false.

int setAudioCodecPayloadType (int  enum_audiocodec, int  payloadType)

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.

int setVideoCodecPayloadType (int  enum_videocodec, int  payloadType)

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.

void clearAudioCodec ()

Remove all the enabled audio codecs.

void clearVideoCodec ()

Remove all the enabled video codecs.

int setAudioCodecParameter (int  enum_audiocodec, String  sdpParameter)

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"![])

int setVideoCodecParameter (int  enum_videocodec, String  sdpParameter)

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

String getVersion ()

Get the version number of the current SDK.

Returns

String with version description

int enableRport (boolean  enable)

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.

int enableEarlyMedia (boolean  enable)

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.

int enablePriorityIPv6Domain (boolean  enable)

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.

int setUriUserEncoding (String  character, boolean  enable)

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.

int setReliableProvisional (int  mode)

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.

int enable3GppTags (boolean  enable)

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.

void enableCallbackSignaling (boolean   enableSending, boolean  enableReceived)

Enable/disable the callback of the SIP messages.

Parameters

void setSrtpPolicy (int  enum_srtppolicy)

Set the SRTP policy.

Parameters

int setRtpPortRange (int  minimumRtpPort, int  maximumRtpPort)

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.

int enableCallForward (boolean  forBusyOnly, String   forwardTo)

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.

int disableCallForward ()

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.

int enableSessionTimer (int  timerSeconds)

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.

void disableSessionTimer ()

Disable the session timer.

void setDoNotDisturb (boolean  state)

Enable/disable the "Do not disturb" status.

Parameters

void enableAutoCheckMwi (boolean  state)

Enable/disable the "Auto Check MWI" status.

Parameters

int setRtpKeepAlive (boolean  state, int  keepAlivePayloadType, int  deltaTransmitTimeMS)

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.

int setKeepAliveTime (int  keepAliveTime)

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.

int setAudioSamples (int  ptime, int  maxptime)

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.

int addSupportedMimeType (String  methodName, String  mimeType, String  subMimeType)

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

String getSipMessageHeaderValue (String  sipMessage, String  headerName)

Access the SIP header of SIP message.

Parameters

Returns

String. The SIP header of SIP message.

long addSipMessageHeader(long sessionId, 
									       String methodName, 
									       int msgType, 
									       String headerName,
									       String headerValue)

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.

int removeAddedSipMessageHeader (long  addedSipMessageId)

Remove the headers (custom header) added by addSipMessageHeader.

Parameters