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 the libs directory of your new application.
Import Necessary Classes: Import the required classes from the SDK:
```
import com.portsip.OnPortSIPEvent;
import com.portsip.PortSipSdk;
```

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

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

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

Parameters

reason

The status text.

code

The status code.

sipMessage

The SIP message received.

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

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

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

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.

void onInviteTrying(long sessionId);

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

Parameters

sessionId

The session ID of the call.

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

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.

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

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.

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

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.

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

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.

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

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.

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

sessionId

The session ID of the call.

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

forwardTo

The target SIP URI of the call forwarding.

void onInviteClosed(long sessionId, String sipMessage);

This event is triggered once remote side ends the call.

Parameters

sessionId

The session ID of the call.

sipMessage

The SIP message received.

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

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

void onRemoteHold(long sessionId);

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

Parameters

sessionId

The session ID of the call.

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

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

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

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

The refer target.

from

The sender of REFER message.

referSipMessage

The SIP message of "REFER". Pass it to "acceptRefer" function.

void onReferAccepted(long sessionId);

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

sessionId

The session ID of the call.

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

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.

void onTransferTrying(long sessionId);

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

Parameters

sessionId

The session ID of the call.

void onTransferRinging(long sessionId);

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

Parameters

sessionId

The session ID of the call.

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

sessionId

The session ID of the call.

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

sessionId

The session ID of the call.

reason

The error reason.

code

The error code.

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

sessionId

The session ID of the call.

message

The received SIP message.

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

sessionId

The session ID of the call.

message

The sent SIP message.

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

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.

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

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

void onRecvDtmfTone(long sessionId, int tone);

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

Parameters

sessionId

Session ID of the call.

tone

code

Description

The DTMF tone 0.

The DTMF tone 1.

The DTMF tone 2.

The DTMF tone 3.

The DTMF tone 4.

The DTMF tone 5.

The DTMF tone 6.

The DTMF tone 7.

The DTMF tone 8.

The DTMF tone 9.

The DTMF tone *.

The DTMF tone #.

The DTMF tone A.

The DTMF tone B.

The DTMF tone C.

The DTMF tone D.

The DTMF tone FLASH.

INFO/OPTIONS message events

void onRecvOptions(String optionsMessage);

This event will be triggered when receiving the OPTIONS message.

Parameters

optionsMessage

The received whole OPTIONS message in text format.

void onRecvInfo(String infoMessage);

This event will be triggered when receiving the INFO message.

Parameters

infoMessage

The whole INFO message received in text format.

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

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

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

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.

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

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