# User Manual for Android ### FAQ #### Where can I download the PortSIP VoIP SDK for testing? You can download the **PortSIP VoIP SDK** along with sample projects from the [PortSIP Website](https://www.portsip.com). *** #### What Android API version is required? The PortSIP VoIP SDK requires **Android API level 16 (Android 4.1)** or later. *** #### How can I create a new project with the PortSIP VoIP SDK? 1. **Download the Sample Project and SDK**\ Download the sample project and trial SDK from the PortSIP Website, then extract them to a local directory. 2. **Create a New Android Project**\ Open **Android Studio** and create a new **Android Application** project. 3. **Add the SDK Libraries**\ Copy all files from the SDK’s `libs` directory into the `libs` directory of your new Android project. 4. **Import Required SDK Classes**\ Import the necessary PortSIP SDK classes into your project: ```java import com.portsip.OnPortSIPEvent; import com.portsip.PortSipSdk; ``` *** #### How can I process callback events? 1. **Implement the Callback Interface**\ Your class must implement the `OnPortSIPEvent` interface to receive SDK callback events. 2. **Override Callback Methods**\ Override the required callback methods to handle events, such as: * `onRegistrationState` * `onCallState` * Other call, media, and signaling-related callbacks as needed *** #### How do I initialize the SDK? 1. **Create an SDK Instance**\ Create an instance of the `PortSipSdk` class. 2. **Set the Event Listener**\ Register the callback handler using `setOnPortSIPEvent`. 3. **Create the Call Manager**\ Initialize the call manager using `CreateCallManager`. 4. **Initialize the SDK**\ Call the `initialize` method with the appropriate configuration parameters. *** #### Is the SDK thread-safe? Yes, the PortSIP SDK is **thread-safe**. You can safely call API functions from multiple threads without additional synchronization. **Exceptions:**\ The following callbacks **must not** be called directly from other threads: * `onAudioRawCallback` * `onVideoRawCallback` * `onRTPPacketCallback` *** ### Register events ```java 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. | ```java 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** ```java 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. | ```java void onInviteTrying(long sessionId); ``` If the outgoing call is being processed, this event will be triggered. **Parameters** | *sessionId* | The session ID of the call. | | ----------- | --------------------------- | ```java 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. | ```java 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. | ```java 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. | ```java 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. | ```java 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. | ```java 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. | | ----------- | --------------------------- | ```java 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. | | ----------- | ------------------------------------------ | ```java 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. | ```java 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 | ```java 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. | | ----------- | --------------------------- | ```java 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 ```java 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 | | *to* | The refer target. | | *from* | The sender of REFER message. | | *referSipMessage* | The SIP message of "REFER". Pass it to "acceptRefer" function. | ```java 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. | | ----------- | --------------------------- | ```java 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. | ```java void onTransferTrying(long sessionId); ``` When the refer call is being processed, this event will be triggered. **Parameters** | *sessionId* | The session ID of the call. | | ----------- | --------------------------- | ```java void onTransferRinging(long sessionId); ``` When the refer call is ringing, this event will be triggered. **Parameters** | *sessionId* | The session ID of the call. | | ----------- | --------------------------- | ```java 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. | | ----------- | --------------------------- | ```java 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 ```java 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. | ```java 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 ```java 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. | ```java 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 ```java 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 | | | | 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 ```java void onRecvOptions(String optionsMessage); ``` This event will be triggered when receiving the OPTIONS message. **Parameters** | *optionsMessage* | The received whole OPTIONS message in text format. | | ---------------- | -------------------------------------------------- | ```java void onRecvInfo(String infoMessage); ``` This event will be triggered when receiving the INFO message. **Parameters** | *infoMessage* | The whole INFO message received in text format. | | ------------- | ----------------------------------------------- | ```java 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 ```java 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. | ```java 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* | The presence status text. | ```java void onPresenceOffline(String fromDisplayName, String from); ``` 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 | ```java void onRecvMessage(long sessionId, String mimeType, String subMimeType, byte[] messageData, int messageDataLength); ``` This event will be triggered when receiving a MESSAGE message in dialog. **Parameters** | *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". | ```java void onRecvOutOfDialogMessage(String fromDisplayName, String from, String toDisplayName, String to, String mimeType, String subMimeType, byte[] messageData, int messageDataLength, String sipMessage); ``` This event will be triggered when receiving a MESSAGE message out of dialog. For example pager message. **Parameters** | *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. | ```java void onSendMessageSuccess(long sessionId, long messageId,String sipMessage); ``` 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. | ```java void onSendMessageFailure(long sessionId, long messageId, String reason, int code, String sipMessage); ``` If the message is failed to be sent out of dialog, this event will be triggered. **Parameters** | *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. | ```java void onSendOutOfDialogMessageSuccess( long messageId, String fromDisplayName, String from, String toDisplayName, String to, String sipMessage); ``` If the message is sent successfully out of dialog, this event will be triggered. **Parameters** | *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. | ```java void onSendOutOfDialogMessageFailure(long messageId, String fromDisplayName, String from, String toDisplayName, String to, String reason, int code, String sipMessage); ``` If the message failed to be sent out of dialog, this event would be triggered. **Parameters** | *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. | ```java void onSubscriptionFailure(long subscribeId, int statusCode); ``` This event will be triggered on sending SUBSCRIBE failure. **Parameters** | *subscribeId* | The ID of SUBSCRIBE request. | | ------------- | ---------------------------- | | *statusCode* | The status code. | ```java void onSubscriptionTerminated(long subscribeId); ``` 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 ```java void onPlayFileFinished(long sessionId, String fileName); ``` If called startPlayingFileToRemote function with no loop mode, this event will be triggered once the file play finished. **Parameters** | *sessionId* | The session ID of the call. | | ----------- | --------------------------- | | *fileName* | The play file name. | ```java void onStatistics(long sessionId,String statistics); ``` 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. | ```java void onAudioDeviceChanged(PortSipEnumDefine.AudioDevice audioDevice, Set devices); ``` 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. | ```java void onAudioFocusChange(int focusChange); ``` 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 ```java void onRTPPacketCallback(long sessionId, int mediaType, int enum_direction, byte[] RTPPacket, int packetSize); ``` If enableRtpCallback function is called to enable the RTP callback, this event will be triggered once a RTP packet is received or sent. **Parameters** | *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 ```java void onAudioRawCallback(long sessionId, int enum_direction, byte[] data, int dataLength, int samplingFreqHz); ``` This event will be triggered once receiving the audio packets if called enableAudioStreamCallback function. **Parameters** | *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 ```java void onVideoRawCallback(long sessionId, int enum_direction, int width, int height, byte[] data, int dataLength); ``` This event will be triggered once receiving the video packets if enableVideoStreamCallback function is called. **Parameters** | *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 ```java int initialize(int enum_transport, String localIP, int localSIPPort, int enum_LogLevel, String LogPath, int maxLines, String agent, int audioDeviceLayer, int videoDeviceLayer, String TLSCertificatesRootPath, String TLSCipherList, boolean verifyTLSCertificate, String dnsServers) ``` Initialize the SDK. **Parameters** | *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 ```java void unInitialize() ``` Un-initialize the SDK and release resources. ```java int setInstanceId(String instanceId) ``` 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. ```java int setUser(String userName, String displayName, String authName, String password, String userDomain, String SIPServer, int SIPServerPort, String STUNServer, int STUNServerPort, String outboundServer, int outboundServerPort) ``` Set user account info. **Parameters** | *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. ```java void removeUser() ``` remove user account info. ```java int registerServer(int expires, int retryTimes) ``` 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. ```java int refreshRegistration(int expires) ``` 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. ```java int unRegisterServer(int waitMS) ``` 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. ```java int setDisplayName(String displayName) ``` 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. ```java int setLicenseKey (String key) ``` 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 ```java int addAudioCodec (int enum_audiocodec) ``` 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. ```java int addVideoCodec (int enum_videocodec) ``` 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. ```java **boolean isAudioCodecEmpty () ``` Detect if the audio codecs are enabled. **Returns** If no audio codec enabled, it will return value true; otherwise it returns false. ```java **boolean isVideoCodecEmpty () ``` Detect if the video codecs are enabled. **Returns** If no video codec enabled, it will return value true; otherwise it returns false. ```java int setAudioCodecPayloadType (int enum_audiocodec, int payloadType) ``` 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. ```java int setVideoCodecPayloadType (int enum_videocodec, int payloadType) ``` 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. ```java void clearAudioCodec () ``` Remove all the enabled audio codecs. ```java void clearVideoCodec () ``` Remove all the enabled video codecs. ```java int setAudioCodecParameter (int enum_audiocodec, String sdpParameter) ``` 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"!\[]) ```java int setVideoCodecParameter (int enum_videocodec, String sdpParameter) ``` 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 ```java String getVersion () ``` Get the version number of the current SDK. **Returns** String with version description ```java int enableRport (boolean enable) ``` 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. ```java int enableEarlyMedia (boolean enable) ``` 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. ```java int enablePriorityIPv6Domain (boolean enable) ``` 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. ```java int setUriUserEncoding (String character, boolean enable) ``` 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. ```java int setReliableProvisional (int mode) ``` 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. ```java int enable3GppTags (boolean enable) ``` 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. ```java void enableCallbackSignaling (boolean enableSending, boolean enableReceived) ``` 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. | ```java void setSrtpPolicy (int enum_srtppolicy) ``` Set the SRTP policy. **Parameters** | *enum\_srtppolicy* |

The SRTP policy.allow:
enum\_SRTPPOLICY\_NONE,
enum\_SRTPPOLICY \_FORCE,
enum\_SRTPPOLICY\_PREFER.

| | ------------------ | ------------------------------------------------------------------------------------------------------------------ | ```java int setRtpPortRange (int minimumRtpPort, int maximumRtpPort) ``` 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. ```java int enableCallForward (boolean forBusyOnly, String forwardTo) ``` 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[:xxxx@sip.portsip.com.](mailto:xxxx@sip.portsip.com) | **Returns** If the function succeeds, it will return value 0. If the function fails, it will return a specific error code. ```java int disableCallForward () ``` Disable the call forwarding. The SDK will not forward any incoming call when this function is called. **Returns** If the function succeeds, it will not return value 0. If the function fails, it will return a specific error code. ```java int enableSessionTimer (int timerSeconds) ``` 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. ```java void disableSessionTimer () ``` Disable the session timer. ```java void setDoNotDisturb (boolean state) ``` Enable/disable the "Do not disturb" status. **Parameters** | *state* | If it is set to true, the SDK will reject all incoming calls. | | ------- | ------------------------------------------------------------- | ```java void enableAutoCheckMwi (boolean state) ``` Enable/disable the "Auto Check MWI" status. **Parameters** | *state* | If it is set to true, the SDK will check Mwi automatically. | | ------- | ----------------------------------------------------------- | ```java int setRtpKeepAlive (boolean state, int keepAlivePayloadType, int deltaTransmitTimeMS) ``` 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. ```java int setKeepAliveTime (int keepAliveTime) ``` 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. ```java int setAudioSamples (int ptime, int maxptime) ``` Set the audio capture sample, which will be present in the SDP of INVITE and 200 OK message as "ptime and "maxptime" attribute. **Parameters** | *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. ```java int addSupportedMimeType (String methodName, String mimeType, String subMimeType) ``` 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: ### Access SIP message header functions ```java String getSipMessageHeaderValue (String sipMessage, String headerName) ``` 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. ```java long addSipMessageHeader(long sessionId, String methodName, int msgType, String headerName, String headerValue) ``` 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. ```java int removeAddedSipMessageHeader (long addedSipMessageId) ``` 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. ```java void clearAddedSipMessageHeaders () ``` 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. ```java addSipMessageHeader(-1,"ALL",3,"Blling", "usd100.00"); addSipMessageHeader(-1,"ALL",3,"ServiceId", "8873456"); clearAddedSipMessageHeaders(); ``` If this function is called, the added extension headers will no longer appear in outgoing SIP message. ```java long modifySipMessageHeader(long sessionId, String methodName, int msgType, String headerName, String headerValue) ``` 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"); ```java int removeModifiedSipMessageHeader (long modifiedSipMessageId) ``` 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. ```java void clearModifiedSipMessageHeaders () ``` 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: ```java modifySipMessageHeader(-1,"ALL",3, "Expires", "1000"); modifySipMessageHeader(-1,"ALL",3, "User-Agent", "MyTest Softphone 1.0"); cleaModifyHeaders(); ``` **Parameters** ### Audio and video functions ```java int setVideoDeviceId (int deviceId) ``` 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. ```java int setVideoOrientation (int rotation) ``` 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. ```java int enableVideoHardwareCodec (boolean enableHWEncoder, boolean enableHWDecoder) ``` 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. ```java int setVideoResolution (int width, int height) ``` 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. ```java int setAudioBitrate (long sessionId, int enum_audiocodec, int bitrateKbps) ``` 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. ```java int setVideoBitrate (long sessionId, int bitrateKbps) ``` 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. ```java int setVideoFrameRate (long sessionId, int frameRate) ``` 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. ```java int sendVideo (long sessionId, boolean send) ``` 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. ```java int setRemoteVideoWindow (long sessionId, PortSIPVideoRenderer renderer) ``` 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. ```java int setRemoteScreenWindow (long sessionId, PortSIPVideoRenderer renderer) ``` 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. ```java void displayLocalVideo (boolean state, boolean mirror, PortSIPVideoRenderer renderer) ``` 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. | ```java int setVideoNackStatus (boolean state) ``` 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. ```java int setChannelOutputVolumeScaling (long sessionId, int scaling) ``` 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. ```java int setChannelInputVolumeScaling (long sessionId, int scaling) ``` 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. ```java void enableAudioManager (boolean state) ``` 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 | | ------- | ----------------------------------------------------------- | ```java Set getAudioDevices () ``` Get current set of available/selectable audio devices. **Returns** Current set of available/selectable audio devices. ```java int setAudioDevice (PortSipEnumDefine.AudioDevice defaultDevice) ``` 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 ```java long call (String callee, boolean sendSdp, boolean videoCall) ``` Make a call **Parameters** | *callee* | The callee. It can be a name only or full SIP URI, for example: user001 or sip[:user001@sip.iptel.org ](mailto:user001@sip.iptel.org)or sip[:user002@sip.yourdomain.com:](mailto:user002@sip.yourdomain.com)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. ```java int rejectCall (long sessionId, int code) ``` 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. ```java int hangUp (long sessionId) ``` 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. ```java int answerCall (long sessionId, boolean videoCall) ``` 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. ```java int updateCall (long sessionId, boolean enableAudio, boolean enableVideo) ``` 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); ```java int hold (long sessionId) ``` 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. ```java int unHold (long sessionId) ``` 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. ```java int muteSession(long sessionId, boolean muteIncomingAudio, boolean muteOutgoingAudio, boolean muteIncomingVideo, boolean muteOutgoingVideo) ``` 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. ```java int forwardCall (long sessionId, String forwardTo) ``` 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:" or "number". | **Returns** If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code. ```java long pickupBLFCall (String replaceDialogId, boolean videoCall) ``` 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. ```java int sendDtmf (long sessionId, int enum_dtmfMethod, int code, int dtmfDuration, boolean playDtmfTone) ``` 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 ```java int refer (long sessionId, String referTo) ``` 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:" 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:"); You can refer to the video on Youtube at: [https://www.youtube.com/watch?v=\_2w9EGgr3FY,](https://www.youtube.com/watch?v=_2w9EGgr3FY) which will demonstrate how to complete the transfer. ```java int attendedRefer (long sessionId, long replaceSessionId, String referTo) ``` 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:" 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: Note: Please use Windows Media Player to play the AVI file, which demonstrates how to complete the transfer. ```java int attendedRefer2(long sessionId, long replaceSessionId, String replaceMethod, String target, String referTo) ``` 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. ```java int outOfDialogRefer (long replaceSessionId, String replaceMethod, String target, String referTo) ``` 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. ```java long acceptRefer (long referId, String referSignaling) ``` 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; ```java int rejectRefer (long referId) ``` 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 ```java int enableSendPcmStreamToRemote (long sessionId, boolean state, int streamSamplesPerSec) ``` 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. ```java int sendPcmStreamToRemote (long sessionId, byte[] data, int dataLength) ``` 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: ```java enableSendPcmStreamToRemote(sessionId, true, 16000); sendPcmStreamToRemote(sessionId, data, dataSize); ``` 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. ```java int enableSendVideoStreamToRemote (long sessionId, boolean state) ``` 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. ```java int sendVideoStreamToRemote (long sessionId, byte[] data, int dataLength, int width, int height) ``` 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 ```java long enableRtpCallback (long sessionId, int mediaType, int directionMode) ``` 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. ```java void enableAudioStreamCallback (long sessionId, boolean enable, int enum_direction) ``` 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. | | ```java void enableVideoStreamCallback (long sessionId, int enum_direction) ``` 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** ```java int startRecord(long sessionId, String recordFilePath, String recordFileName, boolean appendTimeStamp, int audioChannels, int enum_fileFormat, int enum_audioRecordMode, int enum_videoRecordMode) ``` 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. ```java int stopRecord (long sessionId) ``` 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 ```java int startPlayingFileToRemote (long sessionId, String fileUrl, boolean loop, int playAudio) ``` 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. ```java int stopPlayingFileToRemote (long sessionId) ``` 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. ```java int startPlayingFileLocally (String fileUrl, boolean loop, PortSIPVideoRenderer renderer) ``` 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. ```java int stopPlayingFileLocally () ``` 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. ```java void audioPlayLoopbackTest (boolean enable) ``` 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 ```java int createAudioConference () ``` 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. ```java int createVideoConference(PortSIPVideoRenderer conferenceVideoWindow, int videoWidth, int videoHeight, int layout) ``` 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. ```java void destroyConference () ``` End the exist conference. ```java int setConferenceVideoWindow (PortSIPVideoRenderer conferenceVideoWindow) ``` 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. ```java int joinToConference (long sessionId) ``` 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. ```java int removeFromConference (long sessionId) ``` 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 ```java int setAudioRtcpBandwidth (long sessionId, int BitsRR, int BitsRS, int KBitsAS) ``` 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. ```java int setVideoRtcpBandwidth (long sessionId, int BitsRR, int BitsRS, int KBitsAS) ``` 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. ```java int enableAudioQos (boolean state) ``` 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. ```java int enableVideoQos (boolean state) ``` 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. ```java int setVideoMTU (int mtu) ``` 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 ```java int getStatistics (long sessionId) ``` 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 ```java void enableVAD (boolean state) ``` Enable/disable Voice Activity Detection(VAD). **Parameters** | *state* | Set to true to enable VAD, or false to disable. | | ------- | ----------------------------------------------- | ```java void enableAEC (boolean state) ``` Enable/disable AEC (Acoustic Echo Cancellation). **Parameters** | *state* | Set to true to enable AEC, or false to disable. | | ------- | ----------------------------------------------- | ```java void enableCNG (boolean state) ``` Enable/disable Comfort Noise Generator(CNG). **Parameters** | *state* | Set to true to enable CNG, or false to disable. | | ------- | ----------------------------------------------- | ```java void enableAGC (boolean state) ``` Enable/disable Automatic Gain Control(AGC). **Parameters** | *state* | Set to true to enable AEC, or false to disable. | | ------- | ----------------------------------------------- | ```java void enableANS (boolean state) ``` Enable/disable Audio Noise Suppression(ANS). **Parameters** | *state* | Set to true to enable ANS, or false to disable. | | ------- | ----------------------------------------------- | ### Send OPTIONS/INFO/MESSAGE functions ```java int sendOptions (String to, String sdp) ``` 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. ```java int sendInfo (long sessionId, String mimeType, String subMimeType, String infoContents) ``` 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. ```java long sendMessage(long sessionId, String mimeType, String subMimeType, byte[] message, int messageLength) ``` 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); ```java long sendOutOfDialogMessage (String to, String mimeType, String subMimeType, boolean isSMS, byte[] message, int messageLength) ``` Send a out of dialog MESSAGE message to remote side. **Parameters** | *to* | The message receiver. Likes sip[:receiver@portsip.com](mailto:receiver@portsip.com) | | --------------- | ----------------------------------------------------------------------------------- | | *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:", "text", "plain", "hello", 6); Example 2: Send a binary message. sendOutOfDialogMessage("sip:","application", "vnd.3gpp.sms", binData, binDataSize); ```java long setPresenceMode (int mode) ``` 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: ```java long setDefaultSubscriptionTime (int secs) ``` 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. ```java long setDefaultPublicationTime (int secs) ``` 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. ```java long presenceSubscribe (String contact, String subject) ``` Send a SUBSCRIBE message for presence to a contact. **Parameters** | *contact* | The target contact, it must be in the format of sip[:contact001@sip.portsip.com.](mailto:contact001@sip.portsip.com) | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *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. ```java int presenceTerminateSubscribe (long subscribeId) ``` 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. ```java int presenceAcceptSubscribe (long subscribeId) ``` 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. ```java int presenceRejectSubscribe (long subscribeId) ``` 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. ```java int setPresenceStatus (long subscribeId, String statusText) ``` 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. ```java long sendSubscription (String to, String eventName) ``` 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:<101@test.com>", "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. ```java int terminateSubscription (long subscribeId) ``` 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