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

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:[email protected].

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:[email protected] or sip:[email protected]: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:[email protected]" 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:

  1. User 101 subscribed the user 100's call status: sendSubscription(mSipLib, "100", "dialog");

  2. 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:[email protected]" 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:[email protected]");

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:[email protected]" 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:[email protected]

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:[email protected]", "text", "plain", "hello", 6);

Example 2: Send a binary message.

sendOutOfDialogMessage("sip:[email protected]","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:[email protected].

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:[email protected]", "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

PreviousUser Manual for iOSNextUser Manual for macOS

Last updated