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