User Manual for Windows
FAQ
Where can I download the PortSIP VoIP SDK for testing?
You can download the PortSIP VoIP SDK along with the sample project from the PortSIP Website.
How can I compile the sample project?
Download the sample project from the PortSIP Website.
Uncompress the .zip file.
Open the project with Visual Studio.
Compile the sample project directly and run it to test.
If the SDK connects to the PortSIP PBX, there are no limitations. The trial SDK works with any third-party PBX and SIP server, but it only allows for a 2-3 minute conversation.
What are operating systems supported?
PortSIP VoIP SDK supports development on:
Windows 10
Windows 11
Windows Server 2016, 2019, and 2022
What are development tools supported?
Microsoft Visual Studio versions 2017, 2019, and 2023 are supported.
Ensure you have the appropriate build tools installed for your desired languages: C#, VB.NET, and VC++.
How can I create a new project with PortSIP VoIP SDK?
C#/VB.NET:
Download and uncompress the sample project.
Create a new “Windows Application” project in Visual Studio.
Copy
portsip_sdk.dllandportsip_media.dllfrom the sample project directory to your project’s output directories:bin\releaseandbin\debug.Copy the
PortSIPfolder from the sample project directory to your project folder and add it to the Solution.Implement the
SIPCallbackEventsinterface to process callback events.Right-click the project, choose Properties, click the Build tab, and check the Allow unsafe code checkbox.
For more details, please refer to the sample project source code.
VC++:
Download and uncompress the sample project.
Create a new “MFC Application” project.
Copy
portsip_sdk.dllandportsip_media.dllfrom the sample project directory to your project’s output directories.Copy the
include/PortSIPLibfolder to your project folder and add the.hxxfiles from thePortSIPLibfolder to your project.Copy the
libfolder to your project folder and linkportsip_sdk.libinto your project.
For more details, please refer to the sample project source code.
How can I test a P2P call (without a SIP server PBX)?
Uncompress the SDK sample project ZIP file and compile the
P2PSampleproject.Run the
P2PSampleon device A and device B. For example, IP address for A is192.168.1.10, and IP address for B is192.168.1.11.Enter a username and password on A (e.g., username:
111, password:aaa). You can enter anything for the password as the SDK will ignore it. Do the same for B (e.g., username:222, password:aaa).Click the Initialize button on both A and B. If the default port
5060is already in use by another application, theP2PSamplewill prompt “Initialize failure”. In this case, click the Uninitialize button, change the local port, and click the Initialize button again.The log box will display “Initialized.” if the SDK is successfully initialized.
To make a call from A to B, enter
sip:222@192.168.1.11and click the Dial button. To make a call from B to A, entersip:111@192.168.1.10. If A used5066as the local port, for example, dial tosip:111@192.168.1.10:5066, and vice versa for B.
Is the SDK thread-safe?
Yes, the SDK is thread-safe. You can call any of the API functions without worrying about multiple threads. Note: The SDK allows calling API functions in callback events directly, except for the onAudioRawCallback, onVideoRawCallback, and onRTPPacketCallback callbacks.
Does the SDK support native 64-bit?
Yes, the SDK supports both 32-bit and 64-bit architectures.
SDK API Functions
Initialize and register functions
Initialize the SDK.
Parameters
transport
The transport for SIP signaling can be one of the following values:
TRANSPORT_UDPTRANSPORT_TLSTRANSPORT_TCP
localIP
The local computer IP address to be bound (e.g., 192.168.1.108) will be used for sending and receiving SIP messages and RTP packets. If this IP is provided in IPv6 format, the SDK will use IPv6.
To allow the SDK to automatically choose the correct network interface (IP), use "0.0.0.0" for IPv4 or "::" for IPv6.
localSIPPort
The SIP message transport listener port (e.g., 5060) is used for SIP signaling. Please ensure this port is not being used by another application.
logLevel
Set the application log level to enable logging. When logging is enabled, the SDK will generate a log file named PortSIP_Log_<datetime>.log.
The supported log levels are:
PORTSIP_LOG_NONE = -1PORTSIP_LOG_ERROR = 1PORTSIP_LOG_WARNING = 2PORTSIP_LOG_INFO = 3PORTSIP_LOG_DEBUG = 4
logFilePath
Specify the log file path. The path (folder) must already exist.
maxCallLines
Theoretically, unlimited lines could be supported depending on the device’s capability. For a client app, the recommended value ranges from 1 to 100.
sipAgent
The User-Agent header to be inserted into SIP messages.
audioDeviceLayer
Specify the audio device layer to be used:
0= Use the OS default device.1= Virtual device, typically used for devices without a sound device installed.
videoDeviceLayer
Specify the video device layer to be used:
0= Use the OS default device.1= Use a virtual device, typically used for devices without a camera installed.
TLSCertificatesRootPath
Specify the TLS certificate path from which the SDK will automatically load the certificates. Note: On Windows, this path will be ignored, and the SDK will read the certificates from the Windows certificate store instead.
TLSCipherList
Specify the TLS cipher list. This parameter is usually passed as empty so that the SDK will offer all available ciphers. It can be passed empty string if not use the TLS transport.
verifyTLSCertificat
Specify the TLS cipher list. This parameter is usually left empty so that the SDK will offer all available ciphers.
Returns
If the function succeeds, it will return a value of 0. If the function fails, it will return a specific error code.
Get the current version number of the SDK.
Returns
Return a current version number MAJOR.MINOR.PATCH of the SDK.
Set the license key. It must be called before the 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.
Set user account info.
Parameters
userName
The SIP account (username) is usually provided by an IP-Telephony service provider. For PortSIP PBX, this is the extension number.
displayName
The display name of the user. You can set it to anything you like, such as “James Kend”. This field is optional and can be an empty string.
authName
The authorization username is usually the same as the SIP account (username).
password
The password of user. It's optional and can be an empty string.
localIp
The local computer IP address to be bound (e.g., 192.168.1.108) will be used for sending and receiving SIP messages and RTP packets. If this IP is provided in IPv6 format, the SDK will use IPv6.
localSipPort
The SIP message transport listener port (e.g., 5060) is used for SIP signaling.
userDomain
The user domain is an optional parameter. You can pass an empty string if you are not using a domain. To connect to the PortSIP PBX, this is the tenant SIP domain.
sipServer
Specify the IP address or domain of the SIP server or PBX.
sipServerPort
Specify the SIP message port that the SIP server or PBX is listening on.
stunServer
Specify the STUN server used for NAT traversal. This parameter is optional, and you can pass an empty string to disable STUN.
stunServerPort
Specify the STUN server port. This parameter will be ignored if the outboundServer is empty.
outboundServer
Specify the outbound proxy server IP address or domain. This parameter is optional, and you can pass an empty string if you are not using an outbound server.
outboundServerPo rt
Specify the outbound proxy server port. This parameter will be ignored if the outboundServer is empty.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the display name for the user.
Parameters
displayName
that will appear in the From/To Header.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set outbound (RFC5626) instanceId to be used in contact headers.
Parameters
uuid
The ID that will appear in the contact header. Please make sure it's a unique ID.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Register to the SIP server or PBX server(login to the server).
15 Parameters
expires
Specify the registration refresh interval in seconds, with a maximum of 3600 seconds. This value will be inserted into the SIP REGISTER message headers.
retryTimes
The number of retry attempts if registration refresh fails. If set to 0 or less, retries will be disabled, and the onRegisterFailure callback will be triggered upon failure.
Returns
If the function succeeds, it will return 0. If it fails, it will return a specific error code. Upon successful registration to the server, the onRegisterSuccess callback will be triggered; otherwise, the onRegisterFailure callback will be triggered.
Unregister from the SIP server/PBX.
Parameters
waitMS
Wait for the server to confirm successful un-registration. waitMS specifies the maximum wait time in milliseconds; a value of 0 means no waiting
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable rport(RFC3581).
Parameters
enable
Set to true to enable the SDK to support rport. By default it is enabled.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable Early Media.
Parameters
enable
Set to true to enable the SDK to support Early Media. By default Early Media is disabled.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable the option to specify the preferred protocol when a domain supports both IPv4 and IPv6 simultaneously.
16 Parameters
enable
Set to true to prioritize IPv6 domains. By default, IPv4 is prioritized.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Indicate to the SDK that the user part of the URI should be encoded for escaping.
Parameters
character
Specify the character to be encoded, setting one at a time.
enable
Indicate whether escaping is required: set to true to allow escaping, or false to disable it.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable PRACK.
Parameters
mode
This mode parameter can be set to one of the following values:
0 - Never: Disable PRACK. By default, PRACK is disabled.1 - SupportedEssential: Only send reliable provisionals if sending a body and the far end supports it.2 - Supported: Always send reliable provisionals if the far end supports it.3 - Required: Always send reliable provisionals.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable the 3Gpp tags, including "ims.icsi.mmtel" and "g.3gpp.smsip".
Parameters
enable
Set to true to enable SDK to support 3Gpp tags.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function is used to enable or disable the callback for SIP messages.
Parameters
enableSending
Set to true to enable the callback for sent SIP messages, or false to disable it. Once enabled, the onSendingSignaling event will be triggered when the SDK sends a SIP message.
enableReceived
Set to true to enable the callback for received SIP messages, or false to disable it. Once enabled, the onReceivedSignaling event will be triggered when the SDK receives a SIP message.
Enable RTP callbacks to access sent and received RTP packets. The onRTPPacketCallback events will be triggered.
Parameters
sessionId
The session ID of call.
mediaType
0 -audo 1-video 2-screen.
directionMode
Specify the RTP stream callback mode. The available options are:
DIRECTION_SEND: Callback for the sending RTP stream of a single channel, based on the provided
sessionId.DIRECTION_RECV: Callback for the receiving RTP stream of a single channel, based on the provided
sessionId.DIRECTION_SEND_RECV: Callback for both the local and remote RTP streams on the provided
sessionId.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
NIC and local IP functions
Retrieve the number of Network Interface Cards (NICs) available on the device.
Returns
If the function succeeds, it will return the number of Network Interface Cards (NICs), which will be greater than or equal to 0. If the function fails, it will return a specific error code.
Get the local IP address by Network Interface Card index.
Parameters
index
Specify the IP address index. For example, if the PC has two NICs and you wish to obtain the IP address of the second NIC, set this parameter to 1. The first NIC IP index is 0.
ip
Specify the StringBuilder buffer that is used to receive the IP address.
ipSize
Specify the StringBuilder buffer size, which must be at least 32 bytes.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Audio and video codec functions
Enables an audio codec, making it appear in the Session Description Protocol (SDP).
Parameters
codecType
This parameter specifies the type of audio codec you want to enable. It should be of the AUDIOCODEC_TYPE enum. The enum values are following:
AUDIOCODEC_NONE: Undefined video codec..
AUDIOCODEC_G729: G729 codec, 8kHz, 8kbps.
AUDIOCODEC_PCMA: PCMA/G711 A-law codec, 8kHz, 64kbps.
AUDIOCODEC_PCMU: PCMU/G711 μ-law codec, 8kHz, 64kbps.
AUDIOCODEC_GSM: GSM codec, 8kHz, 13kbps.
AUDIOCODEC_G722: G722 codec, 16kHz, 64kbps.
AUDIOCODEC_ILBC: iLBC codec, 8kHz, 30ms-13kbps or 20ms-15kbps.
AUDIOCODEC_AMR: Adaptive Multi-Rate (AMR) codec, 8kHz, various bitrates (4.75-12.20kbps).
AUDIOCODEC_AMRWB: Adaptive Multi-Rate Wideband (AMR-WB) codec, 16kHz, various bitrates (6.60-23.85kbps).
AUDIOCODEC_SPEEX: SPEEX codec, 8kHz, various bitrates (2-24kbps).
AUDIOCODEC_SPEEXWB: SPEEX Wideband codec, 16kHz, various bitrates (4-42kbps).
AUDIOCODEC_ISACWB: iSAC Wideband codec, 16kHz, various bitrates (32-54kbps).
AUDIOCODEC_ISACSWB: iSAC Super Wideband codec, 16kHz, various bitrates (32-160kbps).
AUDIOCODEC_G7221: G722.1 codec, 16kHz, various bitrates (16, 24, 32kbps).
AUDIOCODEC_OPUS: OPUS codec, 48kHz, 32kbps.
AUDIOCODEC_DTMF: DTMF codec, RFC 2833.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enables a video codec, making it appear in the Session Description Protocol (SDP).
Parameters
codecType
This parameter specifies the type of video codec you want to enable. It should be of the VIDEOCODEC_TYPE enum. The enum values are following:
VIDEO_CODEC_NONE: Undefined video codec..
VIDEO_CODEC_I420
VIDEO_CODEC_H263
VIDEO_CODEC_H263_1998
VIDEO_CODEC_H264
VIDEO_CODEC_VP8
VIDEO_CODEC_VP9
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function checks whether any audio codecs are enabled.
Returns
If no audio codec is enabled, it will return value true, otherwise false.
This function checks whether any video codecs are enabled.
Returns
If no video codec is enabled, it will return value true, otherwise false.
Set the RTP payload type for a dynamic audio codec.
Parameters
codecType
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 value a specific error code.
Set the RTP payload type for a dynamic Video codec.
Parameters
codecType
Video codec type, which is defined in the PortSIPTypes file.
payloadType
The new RTP payload type that you want to set.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the codec parameters for an audio codec.
Parameters
codecType
Audio codec type, defined in the PortSIPTypes file.
parameter
The code parameter 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
Here is an example:
setAudioCodecParameter(AUDIOCODEC_AMR, "mode-set=0; octet-align=1; robust-sorting=0");
Set the codec parameter for a video codec.
Parameters
codecType
Video codec type, defined in the PortSIPTypes file.
parameter
The parameter in string format.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
Remarks
Here is an example:
setVideoCodecParameter(VIDEO_CODEC_H264, "profile-level-id=420033; packetization-mode=0");
Additional setting functions
Set the SRTP policy.
Parameters
srtpPolicy
The SRTP policy can be one of the following enum values:
SRTP_POLICY_NONE = 0: Do not use SRTP. The SDK can receive both encrypted (SRTP) and unencrypted calls, but cannot place outgoing encrypted calls.
SRTP_POLICY_FORCE: All calls must use SRTP. The SDK allows receiving encrypted calls and placing outgoing encrypted calls only.
SRTP_POLICY_PREFER: Prefer using SRTP. The SDK allows receiving both encrypted and unencrypted calls, and placing both outgoing encrypted and unencrypted calls.
allowSrtpOverUnsecureTransport
The allowSrtpOverUnsecureTransport parameter specifies whether SRTP is allowed over unsecured transport protocols such as UDP and TCP. Set to true to allow, and false to disallow.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
Set the RTP port range for RTP traffic.
Parameters
minimumRtpPort
The minimum RTP port.
maximumRtpPort
The maximum RTP port.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The port range ((max - min) % maxCallLines) should be greater than 4.
Enable call forwarding.
Parameters
forBusyOnly
If set to true, the SDK will forward all incoming calls when it is busy. If set to false, the SDK will forward all incoming calls regardless.
forwardTo
The call forward target. It must be in the format sip: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.
Disable call forwarding. The SDK will not forward any incoming calls after this function is called.
Returns
If the function succeeds, it will return value 0. If the function fails, the return value is a specific error code.
Allows periodic refreshing of Session Initiation Protocol (SIP) sessions by repeatedly sending INVITE requests.
Parameters
timerSeconds
The refresh interval value in seconds. A minimum value of 90 seconds is required.
refreshMode
Allows setting the session refresh by either the User Agent Client (UAC) or the User Agent Server (UAS):
SESSION_REFRESH_UACSESSION_REFRESH_UAS
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Repeated INVITE requests, or re-INVITEs, are sent during an active call to allow user agents (UAs) or proxies to determine the status of a SIP session. Without this keepalive mechanism, stateful proxies that remember incoming and outgoing requests may continue to retain call state unnecessarily. 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 issues, a stateful proxy will not know that the session has ended. Re-INVITEs ensure that active sessions remain active and completed sessions are terminated.
Disable the session timer.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable the "Do Not Disturb" feature.
Parameters
state
If set to true, the SDK will reject all incoming calls automatically.
Allows enabling or disabling the automatic check for Message Waiting Indication (MWI).
Parameters
state
If set to true, MWI will be checked automatically once successfully registered to a SIP server/PBX.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable to send RTP keep-alive packet when the call is established.
Parameters
state
Set to true to allow to send the keep-alive packet during the call.
keepAlivePayload Type
The payload type of the keep-alive RTP packet, usually set to 126.
deltaTransmitTime MS
The keep-alive RTP packet sending interval, in milliseconds. The recommended value ranges from 15,000 to 300,000.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable the sending of SIP keep-alive packets.
Parameters
keepAliveTime
This is the SIP keep-alive time interval in seconds. Set it to 0 to disable SIP keep-alive. It is recommended to set it to 30 or 50 seconds.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the SDK to receive SIP messages that include a special MIME type.
Parameters
methodName
The 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 the value 0. If the function fails, it will return a specific error code.
Remarks
By default, the PortSIP VoIP SDK supports the following media types (MIME types) for incoming SIP messages:
"message/sipfrag"in NOTIFY messages."application/simple-message-summary"in NOTIFY messages."text/plain"in MESSAGE messages."application/dtmf-relay"in INFO messages."application/media_control+xml"in INFO messages.
The SDK allows receiving SIP messages that include the above MIME types. If the remote side sends an INFO SIP message with its “Content-Type” header value set to "text/plain", the SDK will reject this INFO message, as "text/plain" for INFO messages is not included in the default support list.
To enable the SDK to receive SIP INFO messages that include the "text/plain" MIME type, use the following command:
If you want to receive NOTIFY messages with "application/media_control+xml", use the following command:
For more details about MIME types, please visit the IANA Media Types website:http://www.iana.org/assignments/media-types/
Access SIP message header functions
Access the SIP header of a SIP message.
Parameters
sipMessage
The SIP message.
headerName
The header to access in the SIP message.
headerValue
The buffer to receive header value.
headerValueLengt h
The headerValue buffer size. It is usually recommended to set it to more than 512 bytes.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
When receiving a SIP message in the onReceivedSignaling callback event and you wish to get the SIP message header value, please use getSipMessageHeaderValue. Example:
Add a custom SIP message header to the specified outgoing SIP message.
Parameters
sessionId
To add a header to the SIP message with a specified session ID, use the following instructions. If you set the session ID to -1, the header will be added to all messages.
methodName
To add a header to the SIP message with a specified method name, such as “INVITE”, “REGISTER”, or “INFO”, follow these instructions. If you specify “ALL”, the header will be added to all SIP messages.
msgType
msgType: 1- Applies to the request message.msgType: 2- Applies to the response message.msgType: 3- Applies to both request and response messages.
headerName
The custom header name that will appear in every outgoing SIP message.
headerValue
The custom header value.
Returns
If the function succeeds, it will return addedSipMessageId, which is greater than 0. If the function fails, it will return a specific error code.
Remove the custom headers that were added using addSipMessageHeader.
Parameters
addedSipMessageId
The addedSipMessageId is returned by the addSipMessageHeader function.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the added extension headers (custom headers).
Remarks
Example: Adding and Removing Custom Headers
For example, if you have added two custom headers to every outgoing SIP message and wish to remove them, you can use the following commands:
Modify the special SIP header value for every outgoing SIP message.
Parameters
sessionId
The header of the SIP message with the specified session ID. By setting it to -1, the header will be modified to all messages.
methodName
Modify the header of the SIP message with the specified method name only. For example, “INVITE”, “REGISTER”, or “INFO”. If “ALL” is specified, the header will be added to all SIP messages.
msgType
1- Applies to the request message.2- Applies to the response message.3- Applies to both request and response messages.
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.
Remove the modified headers (custom headers) from every outgoing SIP message.
Parameters
modifiedSipMessageId
The modifiedSipMessageId is returned by the modifySipMessageHeader function.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the modified header values, and stop modifying the header values of every outgoing SIP message.
For example, to modify the values of two headers for every outgoing SIP message and then clear them, use the following commands:
Audio and video functions
Set the audio capture sample for the SDK.
Parameters
ptime
It should be a multiple of 10 between 10 - 60 (with 10 and 60 inclusive).
maxPtime
The maxptime attribute should be a multiple of 10, ranging from 10 to 60 (inclusive). It cannot be less than the ptime attribute.
Returns
If the function succeeds, it will return the value 0. If the function fails, it will return a specific error code.
Remarks
The ptime and maxptime attributes will appear in the SDP of INVITE and 200 OK messages.
This function specifies the audio devices to be used for recording and playback during voice calls.
Parameters
recordingDeviceId
The ID(index) of the audio device to use for recording(microphone).
playoutDeviceId
The ID(index) of the audio device to use for playback(speaker).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function sets the rotation angle for the video captured by the camera.
Parameters
rotation
The rotation angle in degrees. Valid values are 0 (no rotation), 90 (clockwise rotation), 180 (180-degree rotation), and 270 (counterclockwise rotation).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function specifies the video device to be used for capturing and sending video during video calls.
Parameters
deviceId
The ID(index) of the video device(camera) to use.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function sets the resolution (width and height) of the video captured by the camera.
Parameters
width
The desired width of the video in pixels.
height
The desired height of the video in pixels.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function sets the audio bitrate for a specific audio codec in a given session.
Parameters
sessionId
The ID of the session for which to set the audio bitrate.
audioCodecType
The type of audio codec to configure.
bitrateKbps
The desired audio bitrate in kilobits per second (kbps).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function sets the video bitrate for a given session.
Parameters
sessionId
The ID of the session for which to set the video bitrate.
videoCodecType
The type of video codec to configure.
bitrateKbps
The desired video bitrate in kilobits per second (kbps).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function sets the video frame rate for a given session.
Parameters
sessionId
The ID of the session for which to set the video frame rate.
frameRate
The desired video frame rate in frames per second (fps). The minimum allowed frame rate is 5 fps, and the maximum is 30 fps. Increasing the frame rate can improve video smoothness but will also require more bandwidth.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
By default, the SDK uses a reasonable frame rate for video calls. You generally do not need to explicitly set the frame rate using this function unless you require a specific value. However, if you want to fine-tune the video quality-bandwidth trade-off, you can adjust the frame rate as needed within the supported range.
This function controls whether video is sent to the remote party in a given session.
Parameters
sessionId
The ID of the session for which to control video sending.
sendState
A Boolean value indicating whether to start sending video (true) or stop sending video (false).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function controls whether the microphone is muted for audio input. This function is not available on Android and iOS platforms.
Parameters
mute
A Boolean value indicating whether to mute the microphone (true) or unmute it (false).
This function controls whether the speaker is muted for audio output. This function is not available on Android and iOS platforms.
Parameters
mute
A Boolean value indicating whether to mute the speaker (true) or unmute it (false).
This function adjusts the volume scaling for a specific audio channel in a given session.
Parameters
sessionId
The ID of the session for which to adjust the volume scaling.
scaling
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.
This function adjusts the volume scaling for the microphone signal of a specific audio channel in a given session.
Parameters
sessionId
The ID of the session for which to adjust the volume scaling.
scaling
Ccale 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.
This function specifies the window handle where the received remote video will be displayed for a given session.
Parameters
sessionId
The ID of the session for which to set the remote video window.
remoteVideoWindo
The window handle where the remote video will be rendered.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function controls whether the local video is displayed in a specified window.
Parameters
state
A Boolean value indicating whether to start displaying local video (true) or stop displaying it (false).
mirror
A Boolean value indicating whether to mirror the local video horizontally.
localVideoWindow
The window handle where the local video will be rendered.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
This function controls whether the NACK (Negative ACKnowledgement) feature is enabled for video transmission in a session. NACK helps to improve video quality by requesting retransmission of lost packets.
Parameters
state
A Boolean value indicating whether to enable NACK (true) or disable it (false).
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Call functions
Make a call.
Parameters
callee
The callee. It can be either name or full SIP URI. For example: user001, sip:user001@sip.iptel.org or sip:user002@sip.yourdomain.com:5068
sendSdp
If it's set to false, the outgoing call doesn't include the SDP in INVITE message.
videoCall
If it's set to true with at least one video codecs added, the outgoing call will include the video codec into SDP.
Returns
If the function succeeds, it will return the session ID of the call that 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 being processed. You need to detect the call final state in onInviteTrying, onInviteRinging, onInviteFailure callback events.
rejectCall Reject the incoming call.
Parameters
sessionId
The sessionId of the call.
code
Reject code. For example, 486, 480 etc.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
hangUp Hang up the call.
Parameters
sessionId
Session ID of the call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
answerCall Answer the incoming call.
Parameters
sessionId
The session ID of call.
videoCall
If the incoming call is a video call and the video codec is matched, set it to true to answer the video call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
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 updated 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 value a specific error code.
Remarks
Example usage:
Example 1: A called B with the audio only, B answered A, there has an audio conversation between A, B. Now A wants to see B visually, A could use these functions to do it.
clearVideoCodec(); addVideoCodec(VIDEOCODEC_H264); updateCall(sessionId, true, true);
Example 2: Remove video stream from current conversation.
updateCall(sessionId, true, false);
To place a call on hold.
Parameters
sessionId
The session ID of call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Take off hold.
Parameters
sessionId
The session ID of call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Mute the specified session audio or video. Parameters
sessionId
The session ID of the call.
muteIncomingAudi o
Set it to true to mute incoming audio stream, and remote side audio cannot be heard.
muteOutgoingAudi o
Set it to true to mute outgoing audio stream, and the remote side can't hear the audio.
muteIncomingVide o
Set it to true to mute incoming video stream, and the remote side video will be invisible.
muteOutgoingVide o
Set it to true to mute outgoing video stream, and the remote side can't see the video.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Forward call to another one when receiving the incoming call.
Parameters
sessionId
The session ID of the call.
forwardTo
Target of the forwarding. It can be "sip:number@sipserver.com" or "number" only.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
This function will be used for picking up a call based on the BLF (Busy Lamp Field) status. Parameters
replaceDialogId
The session ID of the call.
videoCall
Target of the forwarding. It can be "sip:number@sipserver.com" or "number" only.
Returns
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:
User 101 subscribed the user 100's call status: sendSubscription("100", "dialog");
When 100 hold a call or 100 is ringing, onDialogStateUpdated callback will be triggered, and 101 will receive this callback. Now 101 can use pickupBLFCall function to pick the call rather than 100 to talk with caller.
Send DTMF tone. Parameters
sessionId
The session ID of the call.
dtmfMethod
DTMF tone could be sent with two methods: DTMF_RFC2833 and DTMF_INFO, of which DTMF_RFC2833 is recommend.
code
The DTMF tone (0-16).
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
If it is set to true, the SDK plays local DTMF tone sound when sending DTMF.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Refer functions
Refer the current call to another one.
Parameters
sessionId
The session ID of the call.
referTo
Target of the refer, which can be either "sip:number@sipserver.com" 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:testuser12@sip.portsip.com");
You can watch the video on YouTube at https://www.youtube.com/watch?v=_2w9EGgr3FY. It will demonstrate the transfer.
Parameters
sessionId
The session ID of the call.
replaceSessionId
Session ID of the repferred call.
referTo
Target of the refer, which can be either
"sip:number@sipserver.com" or "number".
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Please read the sample project source code for more details, or you can watch the video on YouTube at https://www.youtube.com/watch?v=NezhIZW4lV4,
which will demonstrate the transfer.
Make an attended refer with specified request line and specified method embedded into the "Refer-To" header.
Parameters
sessionId
Session ID of the call.
replaceSessionId
Session ID of the replaced call.
replaceMethod
The SIP method name which will be embeded in the "Refer-To" header, usually INVITE or BYE.
target
The target to which the REFER message will be sent. It appears in the "Request Line" of REFER message.
referTo
Target of the refer that appears in the "Refer-To" header. It can be either "sip:number@sipserver.com" 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 for more details, or you can watch the video on YouTube at https://www.youtube.com/watch?v=NezhIZW4lV4, which will demonstrate the transfer.
Send an out of dialog REFER to replace the specified call.
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 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.
Accept the REFER request, and a new call will be made if called this function. The function is usually called after onReceivedRefer callback event.
Parameters
referId
The ID of REFER request that comes from onReceivedRefer callback event.
referSignalingMes sage
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 a specific error code less than 0.
Reject the REFER request.
Parameters
referId
The ID of REFER request that comes from onReceivedRefer callback event.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send audio and video stream functions
Enable the SDK to send PCM stream data to remote side from another source instead of microphone.
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.
Remarks
This function MUST be called first to send the PCM stream data to another side.
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 it should be used as below:
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.
Enable the SDK send video stream data to remote side from another source instead of camera. Parameters
sessionId
The session ID of call.
state
Set to true to enable the sending stream, or false to disable.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send the video stream to remote side.
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 video image width.
height
The video image height.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
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.
Usually it should be used as below:
enableSendVideoStreamToRemote(sessionId, true); sendVideoStreamToRemote(sessionId, data, dataSize, 352, 288);
Enable the SDK send Screen stream data to remote side from selected screen source instead of camera.
Parameters
sessionId
The session ID of call.
state
Set to true to enable the sending 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.
RTP packets, Audio stream and video stream callback functions
Enable/disable the audio stream callback.
Parameters
sessionId
The session ID of call.
enable
Set to true to enable audio stream callback, or false to stop the callback.
direction
The audio stream callback direction.
Type
Description
DIRECTION_SEND
Callback the send audio stream for one channel based on the given sessionId.
DIRECTION_RECV
Callback the received audio stream for one channel based on the given sessionId.
DIRECTION_SEND_RECV
Callback both send & received audio stream for one channel based on the given sessionId.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The onAudioRawCallback event will be triggered if the callback is enabled.
Enable/disable the video stream callback.
Parameters
callbackObject
The callback object that you passed in can be accessed once callback function triggered.
sessionId
The session ID of call.
direction
The video stream callback direction.
Type
Description
DIRECTION_SEND
Callback the send video stream for one channel based on the given sessionId.
DIRECTION_RECV
Callback the received video stream for one channel based on the given sessionId.
DIRECTION_SEND_RECV
Callback both send & received video stream for one channel based on the given sessionId.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The onVideoRawCallback event will be triggered if the callback is enabled.
Enable/disable the video stream callback.
Parameters
callbackObject
The callback object that you passed in can be accessed once callback function triggered.
sessionId
The session ID of call.
direction
The video stream callback direction.
Type
Description
DIRECTION_SEND
Callback the send video stream for one channel based on the given sessionId.
DIRECTION_RECV
Callback the received video stream for one channel based on the given sessionId.
DIRECTION_SEND_RECV
Callback both send & received video stream for one channel based on the given sessionId.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The onVideoRawCallback event will be triggered if the callback is enabled.
Record functions
Start recording the call.
Parameters
sessionId
The session ID of call conversation.
recordFilePath
The file path to which the record file will be saved. 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 recording file name.
channels
Set to record file audio channels, 1 - mono 2 - stereo.
recordFileFormat
The file format for the recording.
audioRecordMode
Allow to set audio recording mode. Support to record received and/or sent audio.
videoRecordMode
Allow to set video recording mode. Support to record received and/or sent video.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop record.
Parameters
sessionId
The session ID of call conversation.
Play audio and video file to remote functions
Play a file to remote party.
Parameters
sessionId
Session ID of the call.
fileUrl
url or file name, such as "/test.mp4","/test.wav".
loop
Set to false to stop playing video file when it is ended, or true to play it repeatedly.
playAudio
0 - Not play file audio. 1 - Play file audio, 2 - Play file audio mix with Mic.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop playing file to remote party.
Parameters
sessionId
Session ID of the call.
Play a file to remote party.
Parameters
sessionId
Session ID of the call.
fileUrl
url or file name, such as "/test.mp4","/test.wav".
loop
Set to false to stop playing video file when it is ended, or true to play it repeatedly.
playVideoWindow
The PortSIPVideoRenderView used for displaying the video.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Stop playing file to locally.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Conference functions
Create an audio conference. It will be failed if the existent conference is not ended yet.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Create a video conference. It will be failed if the existent conference is not ended yet.
Parameters
conferenceVideoWindow
The UIView used to display the conference video.
videoResolution
The 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.
Set the window for a conference that is used to display the received remote video image.
Parameters
videoWindow
The UIView used to display the conference video.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Join a session into existent conference. If the call is in hold, it will be un-hold automatically.
Parameters
sessionId
Session ID of the call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remove a session from an existent conference.
Parameters
sessionId
Session ID of the call.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
RTP and RTCP QOS functions
Set the audio RTCP bandwidth parameters to the RFC3556.
Parameters
sessionId
The session ID of call conversation.
BitsRR
The bits for the RR parameter.
BitsRS
The bits for the RS parameter.
KBitsAS
The Kbits for the AS parameter.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the 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.
RTP statistics functions
Obtain the statistics of channel. the event onStatistics will be triggered.
Parameters
sessionId
The session ID of call conversation.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Audio effect functions
Enable/disable Voice Activity Detection (VAD).
Parameters
state
Set to true to enable VAD, or false to disable.
Enable/disable AEC (Acoustic Echo Cancellation).
Parameters
state
Set it to true to enable AEC, or false to disable.
Enable/disable Comfort Noise Generator (CNG).
Parameters
state
Set it to true to enable CNG, or false to disable.
Enable/disable Automatic Gain Control (AGC).
Parameters
state
Set it to true to enable AGC, or false to disable.
Enable/disable Audio Noise Suppression (ANS).
Parameters
state
Set it to true to enable ANS, or false to disable.
Set the DSCP (differentiated services code point) value of QoS (Quality of Service) for audio channel.
Parameters
state
Set to true to enable audio QoS, and DSCP value will be 46; or false to disable audio QoS, and DSCP value will be 0.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the DSCP (differentiated services code point) value of QoS (Quality of Service) for video channel.
Parameters
state
Set as true to enable video QoS and DSCP value will be 34; or false to disable Video Qos , and DSCP value will be 0.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the MTU size for video RTP packet.
Parameters
mtu
Set MTU value. Allow value ranges (512-65507). Other value will be modified to the default 1450.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send OPTIONS/INFO/MESSAGE functions
Send OPTIONS message.
Parameters
to
The recipient of OPTIONS message.
sdp
The SDP of OPTIONS message. It's optional if user does not wish to send the SDP with OPTIONS message.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a INFO message to remote side in a call. 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 is sent with INFO message.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Send a SUBSCRIBE message to subscribe an event.
Parameters
to
The user/extension to be subscribed.
eventName
The event name to be subscribed.
Returns
If the function succeeds, it will return the ID of 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("100", "dialog"); Extension 100 refers to the user/extension to be monitored. Once being monitored, when extension 100 hold a call or is ringing, the onDialogStateUpdated callback will be triggered.
Terminate the given subscription.
Parameters
subscribeId
The ID of the subscription.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
For example, if you want stop check the MWI, use below code:
terminateSubscription(mwiSubId);
Send a MESSAGE message to remote side in dialog.
Parameters
sessionId
The session ID of the call.
mimeType
The mime type of MESSAGE message.
subMimeType
The sub mime type of MESSAGE message.
message
The contents which is 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 less than 0.
Remarks
Example 1: send a plain text message. Note: to send text in other languages, please use the UTF-8 to encode the message before sending.
sendMessage(sessionId, "text", "plain", "hello",6);
Example 2: send a binary message.
sendMessage(sessionId, "application", "vnd.3gpp.sms", binData, binDataSize);
Send an out of dialog MESSAGE message to remote side.
Parameters
to
The message recipient, such as sip:receiver@portsip.com
mimeType
The mime type of MESSAGE message.
subMimeType
The sub mime type of MESSAGE message. @isSMS isSMS Set to YES to specify "messagetype=SMS" in the To line, or NO to disable.
message
The contents which is 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 less than 0.
Remarks
Example 1: send a plain text message. Note: to send text in other languages, please use the UTF-8 to encode the message before sending.
sendOutOfDialogMessage("sip:user1@sip.portsip.com", "text", "plain", false, "hello", 6);
Example 2: send a binary message.
sendOutOfDialogMessage("sip:user1@sip.portsip.com","application", "vnd.3gpp.sms", false, binData, binDataSize);
Set the default expiration time to be used when creating a subscription.
Parameters
secs
The default expiration time of subscription.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the default expiration time to be used when creating a publication.
Parameters
secs
The default expiration time of publication.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
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 and PortSIP PBX support this feature. For more details please visit: https://www.portsip.com/portsip-pbx
Presence functions
Send a SUBSCRIBE message for subscribing the contact's presence status.
Parameters
to
The target contact. It must be like sip:contact001@sip.portsip.com.
subject
This subject text will be inserted into the SUBSCRIBE message. For example: "Hello, I'm Jason".
The subject maybe in UTF-8 format. You should use UTF-8 to decode it.
Returns
If the function succeeds, it will return value subscribeId. If the function fails, it will return a specific error code.
Terminate the given presence subscription.
Parameters
subscribeId
The ID of the subscription.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Reject a presence SUBSCRIBE request which is 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.
Remarks
If the P2P presence mode is enabled, when someone subscribe your presence status, you will receive the subscribe request in the callback, and you can use this function to accept it.
Accept the presence SUBSCRIBE request which is received from contact.
Parameters
subscribeId
Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event will include the subscription ID.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
If the P2P presence mode is enabled, when someone subscribes your presence status, you will receive the subscription request in the callback, and you can use this function to reject it.
Set the presence status.
Parameters
subscribeId
Subscription ID.
stateText
The state text of presence online. For example: "I'm here". If you want to appear as offline to others, please pass the "Offline" to "statusText" parameter.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
With P2P presence mode, when receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event includes the subscription ID. This
function will cause the SDK sending a NOTIFY message to update your presence status, and you must pass the correct subscribeId.
With presence agent mode, this function will cause the SDK to send a PUBLISH message to update your presence status, and you must pass 0 to the "subscribeId" parameter.
Device Manage functions.
Gets the count of audio devices available for audio recording.
Returns
It will return the count of recording devices. If the function fails, it will return a specific error code less than 0.
Gets the number of audio devices available for audio playout.
Returns
It will return the count of playout devices. If the function fails, it will return a specific error code less than 0.
Gets the name of a specific recording device given by an index.
Parameters
deviceIndex
Device index (0, 1, 2, ..., N-1), where N is given by getNumOfRecordingDevices (). Also -1 is a valid value and will return the name of the default recording device.
nameUTF8
A character buffer to which the device name will be copied as a null-terminated string in UTF-8 format.
nameUTF8Length
The size of nameUTF8 buffer. It cannot be less than 128.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Get the name of a specific playout device given by an index.
Parameters
deviceIndex
deviceIndex
Device index (0, 1, 2, ..., N-1), where N is given by getNumOfRecordingDevices (). Also -1 is a valid value and will return the name of the default recording device.
nameUTF8
A character buffer to which the device name will be copied as a null-terminated string in UTF-8 format.
nameUTF8Length
The size of nameUTF8 buffer. It cannot be less than 128.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the speaker volume level.
Parameters
volume
Volume level of speaker. Valid value ranges 0 - 255.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Gets the speaker volume level.
Returns
If the function succeeds, it will return the speaker volume with valid range 0 - 255. If the function fails, it will return a specific error code.
Sets the microphone volume level.
Parameters
volume
The microphone volume level. Valid value ranges 0 - 255.
Returns
If the function succeeds, the return value is 0. If the function fails, the return value is a specific error code.
Retrieves the current microphone volume.
Returns
If the function succeeds, it will return the microphone volume. If the function fails, it will return a specific error code.
Retrieves the current number of screen.
Returns
If the function succeeds, it will return the screen number. If the function fails, it will return a specific error code.
Retrieves the current screen title .
Returns
If the function succeeds, return value 0. If the function fails, it will return a specific error code.
Sets the Screen to share .
Returns
If the function succeeds, return value 0. If the function fails, it will return a specific error code.
Sets the Screen video framerate .
Returns
If the function succeeds, return value 0. If the function fails, it will return a specific error code.
Set the window for a session that is used to display the received screen video .
Parameters
sessionId
The session ID of the call.
remoteVideoWindo w
The window to display 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.
Use it for the audio device loop back test.
Parameters
enable
Set to true to start audio look back test; or fase to stop.
Get the number of available capturing devices.
Returns
It will return the count of video capturing devices. If it fails, it will return a specific error code less than 0.
Get the name of a specific video capture device given by an index.
Parameters
deviceIndex
Device index (0, 1, 2, ..., N-1), where N is given by getNumOfVideoCaptureDevices (). Also -1 is a valid value and will return the name of the default capturing device.
uniqueIdUTF8
Unique identifier of the capturing device.
uniqueIdUTF8Len gth
Size in bytes of uniqueIdUTF8.
deviceNameUTF8
A character buffer to which the device name will be copied as a null-terminated string in UTF-8 format.
deviceNameUTF8 Length
The size of nameUTF8 buffer. It cannot be less than 128.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Display the capture device property dialog box for the specified capture device.
Parameters
uniqueIdUTF8
Unique identifier of the capture device.
uniqueIdUTF8Len gth
Size in bytes of uniqueIdUTF8.
dialogTitle
The title of the video settings dialog.
parentWindow
Parent window used for the dialog box. It should originally be a HWND.
x
Horizontal position for the dialog relative to the parent window, in pixels.
y
Vertical position for the dialog relative to the parent window, in pixels.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
SDK Callback events
Register events
When successfully registered to server, this event will be triggered.
Parameters
callbackIndex
This is a unique identifier or index associated with a specific callback function that is registered with the SDK library during initialization. When the SDK encounters an event or condition that triggers the callback, it uses the callback index to locate and execute the corresponding function.
callbackObject
A callback object is a user-defined object or structure that contains pointers to callback functions. When creating the SDK library, you pass this callback object to the SDK. The SDK then stores the callback object and uses it to invoke the appropriate callback functions when specific events or conditions occur.
statusText
A human-readable description of the status of the operation callback event.
statusCode
A numerical code representing the status of the operation callbck event. The specific codes and their meanings are defined in the SIP protocol.
sipMessage
The complete SIP message that was received as part of the operation.
This event will be triggered if the SDK fails to register with the SIP server. This can occur due to various reasons, such as network connectivity issues, incorrect SIP credentials, or server errors.
Parameters
statusText
A human-readable description of the status of the register failure reason. This provides additional information about why the registration attempt failed, such as network errors, authentication issues, or server-specific reasons.
statusCode
A numerical code representing the status of the register failure. This code corresponds to a specific error condition defined in the SIP protocol. By examining this code, you can determine the exact reason for the registration failure and take appropriate actions.
sipMessage
The complete SIP message that was received as part of the operation.
Call events
This callback function is invoked when an incoming call is received.
Parameters
sessionId
The unique identifier for the incoming call.
callerDisplayNam e
The display name of the calling party as provided in the SIP INVITE message.
caller
he SIP URI of the calling party.
calleeDisplayNam e
The display name of the receiving party as specified in the SIP INVITE message.
callee
The SIP URI of the receiving party.
audioCodecNames
A string containing the names of the matched audio codecs for the call, separated by "#" if there are multiple codecs.
videoCodecNames
A string containing the names of the matched video codecs for the call, separated by "#" if there are multiple codecs.
existsAudio
Boolean value indicating whether the call includes audio.
existsVideo
A Boolean value indicating whether the call includes video.
sipMessage
A string object containing the complete SIP INVITE message received.
If the outgoing call is being processed, this event will be triggered.
Parameters
sessionId
The unique identifier for the incoming call.
This callback function is invoked when the SDK receives a 183 Session Progress response from the SIP server during an incoming call. This indicates that the call is progressing and that early media may be available.
Parameters
sessionId
The unique identifier for the incoming call.
audioCodecNames
A string containing the names of the matched audio codecs for the call, separated by "#" if there are multiple codecs.
videoCodecNames
A string containing the names of the matched video codecs for the call, separated by "#" if there are multiple codecs.
existsEarlyMedia
A Boolean value indicating whether early media is available. Early media allows for audio or video to be transmitted before the call is fully established.
existsAudio
A Boolean value indicating whether the call includes audio.
existsVideo
A Boolean value indicating whether the call includes video.
sipMessage
A string containing the complete 183 Session Progress SIP message received.
This callback function is invoked when an outgoing call starts ringing. This indicates that the call has been initiated and is waiting for the remote party to answer.
Parameters
sessionId
The unique identifier for the incoming call.
statusText
A human-readable description of the call status.
statusCode
A numerical code representing the call status.
sipMessage
A string object containing the complete SIP response received from the SIP server indicating that the call is ringing.
This callback function is invoked when the remote party answers an incoming or outgoing call.
Parameters
sessionId
The unique identifier for the call.
callerDisplayNam e
he display name of the calling party.
caller
he SIP URI of the calling party.
calleeDisplayNam e
The display name of the receiving party.
callee
The SIP URI of the receiving party.
audioCodecNames
A string containing the names of the matched audio codecs for the call, separated by "#" if there are multiple codecs.
videoCodecNames
A string containing the names of the matched video codecs for the call, separated by "#" if there are multiple codecs.
existsAudio
A Boolean value indicating whether the call includes audio.
existsVideo
A Boolean value indicating whether the call includes video.
sipMessage
A string object containing the complete SIP INVITE message received.
This callback function is invoked when an outgoing call fails.
Parameters
sessionId
The unique identifier for the call.
callerDisplayNam e
The display name of the calling party.
caller
The SIP URI of the calling party.
calleeDisplayNam e
The display name of callee.The display name of the receiving party.
callee
The SIP URI of the receiving party.
reason
A human-readable description of the reason for the call failure.
code
A numerical code representing the reason for the call failure.
sipMessage
A string object containing the complete SIP response received from the SIP server indicating the call failure.
This callback function is invoked when the remote party updates the parameters of an existing call. This can occur, for example, when the remote party changes the audio or video codecs being used, or when additional media streams are added or removed.
Parameters
sessionId
The unique identifier for the call.
audioCodecNames
A string containing the names of the matched audio codecs for the call, separated by "#" if there are multiple codecs.
videoCodecNames
A string containing the names of the matched video codecs for the call, separated by "#" if there are multiple codecs.
existsAudio
A Boolean value indicating whether the call includes audio.
existsVideo
A Boolean value indicating whether the call includes video.
sipMessage
A string object containing the complete SIP UPDATE message received.
This callback function is invoked when a call is successfully established. This occurs after both parties have exchanged the necessary SIP messages and agreed to the terms of the call (Received the ACK).
Parameters
sessionId
The unique identifier for the call.
This callback function is invoked when an incoming call is automatically forwarded to another destination. This occurs if call forwarding is enabled and an incoming call is received.
Parameters
forwardTo
The SIP URI of the destination to which the call is being forwarded.
This callback function is invoked when the remote party ends a call.
Parameters
sessionId
The unique identifier for the call that has been closed.
This callback function is invoked when the status of a monitored user's call changes. This is typically used in BLF (Busy Lamp Field) scenarios where a user subscribes to the status of another user's calls.
Parameters
BLFMonitoredUri
The SIP URI of the user being monitored.
BLFDialogState
A string representing the current state of the monitored user's call.
BLFDialogId
A unique identifier for the monitored user's call.
BLFDialogDirecti on
A string indicating the direction of the monitored user's call.
This callback function is invoked when the remote party places a call on hold.
Parameters
sessionId
The unique identifier for the call that has been placed on hold.
This callback function is invoked when the remote party resumes a call that was previously placed on hold.
Parameters
sessionId
The unique identifier for the call that has been resumed.
audioCodecNames
A string containing the names of the matched audio codecs for the call, separated by "#" if there are multiple codecs.
videoCodecNames
A string containing the names of the matched video codecs for the call, separated by "#" if there are multiple codecs.
existsAudio
A Boolean value indicating whether the call includes audio.
existsVideo
A Boolean value indicating whether the call includes video.
Refer events
This callback function is invoked when the SDK receives a REFER message during an active call. A REFER message is used to transfer a call to a different party.
Parameters
sessionId
The unique identifier for the call that received the REFER message.
referId
A unique identifier for the REFER message itself. This ID is used to accept or reject the transfer.
to
The SIP URI of the target party to which the call is being transferred.
from
The SIP URI of the party who sent the REFER message.
referSipMessage
A string object containing the complete REFER SIP message received. This message contains the details of the call transfer request, including the target party, reason for the transfer, and other relevant information. You can pass this message to the acceptRefer function to accept the call transfer.
This callback function is invoked when the remote party accepts a call transfer that was previously requested using a REFER message.
Parameters
sessionId
The unique identifier for the call that was transferred.
This callback function is invoked when the remote party rejects a call transfer.
Parameters
sessionId
The unique identifier for the call that was not transferred. This parameter provides a way to track and manage the call even though the transfer was rejected.
reason
A human-readable description of the reason for the call transfer rejection.
code
A numerical code representing the reason for the call transfer rejection.
This callback function is invoked when a call transfer is in progress. This indicates that the SIP SERVER/PBX is processing the REFER message and attempting to transfer the call to the specified destination.
Parameters
sessionId
The unique identifier for the call that is being transferred.
This callback function is invoked when a call transfer is ringing at the destination. This indicates that the transferred call has reached the target party and is waiting for them to answer.
Parameters
sessionId
The unique identifier for the transferred call.
This callback function is invoked when an active call transfer is successful. This occurs when the target party accepts a call that was transferred using a REFER message.
Parameters
sessionId
The unique identifier for the transferred call.
This callback function is invoked when an active call transfer fails. This occurs when the target party rejects a call that was transferred using a REFER message.
Parameters
sessionId
The unique identifier for the transferred call.
reason
A human-readable description of the reason for the call transfer failure.
code
A numerical code representing the reason for the call transfer failure.
Signaling events
This callback function is invoked when the SDK receives any SIP message related to a call. This includes INVITE, ACK, BYE, CANCEL, HOLD, UNHOLD, REFER, and other SIP messages.
Parameters
sessionId
The session ID of the call.
signaling
The SIP message received.
This event will be triggered when a SIP message sent. Parameters
sessionId
The unique identifier for the call associated with the received SIP message.
signaling
A string object containing the complete SIP message received.
MWI events
This callback function is invoked when a new voice message (MWI) is waiting for the user.
Parameters
messageAccount
The voice message account associated with the waiting messages.
urgentNewMessag eCount
The number of urgent new voice messages.
urgentOldMessage Count
The number of urgent old voice messages.
newMessageCount
The number of new voice messages (non-urgent).
oldMessageCount
The number of old voice messages (non-urgent).
This callback function is invoked when a new fax message (MWI) is waiting for the user.
Parameters
messageAccount
The fax message account associated with the waiting messages.
urgentNewMessag eCount
The number of urgent new fax messages.
urgentOldMessage Count
The number of urgent old fax messages.
newMessageCount
The number of new fax messages.
oldMessageCount
The number of old fax messages.
DTMF events
This callback function is invoked when a DTMF tone is received from the remote party during a call.
Parameters
sessionId
The unique identifier for the call.
tone
The DTMF tone that was received. The possible values for tone are:
0: DTMF tone 0
1: DTMF tone 1
2: DTMF tone 2
3: DTMF tone 3
4: DTMF tone 4
5: DTMF tone 5
6: DTMF tone 6
7: DTMF tone 7
8: DTMF tone 8
9: DTMF tone 9
10: DTMF tone *
11: DTMF tone #
12: DTMF tone A
13: DTMF tone B
14: DTMF tone C
15: DTMF tone D
16: DTMF tone FLASH
INFO/OPTIONS message events
This callback function is invoked when the SDK receives an OPTIONS SIP message.
Parameters
optionsMessage
A string object containing the complete OPTIONS SIP message received.
This callback function is invoked when the SDK receives an INFO SIP message.
Parameters
infoMessage
A string object containing the complete INFO SIP message received.
This callback function is invoked when the SDK receives a NOTIFY message related to a previously established subscription. A subscription is used to receive updates or notifications from a SIP server or another endpoint.
Parameters
subscribeId
The unique identifier for the subscription associated with the received NOTIFY message.
notifyMessage
A string object containing the complete NOTIFY SIP message received.
contentData
A byte array containing the content of the NOTIFY message body. This can be either text or binary data.
contentLenght
The length of the contentData in bytes.
This callback function is invoked when a subscription attempt fails. This occurs when the SDK sends a SUBSCRIBE message but receives an error response from the SIP server.
Parameters
subscribeId
The unique identifier for the subscription request that failed.
statusCode
A numerical code representing the reason for the subscription failure.
This callback function is invoked when a subscription is terminated or expires. This can occur due to various reasons, such as a timeout, explicit termination by the server or client, or other factors.
Parameters
subscribeId
The unique identifier for the terminated or expired subscription.
Presence events
This callback function is invoked when the SDK receives a SUBSCRIBE message from a contact, indicating that the contact wants to subscribe to your presence status.
Parameters
subscribeId
The unique identifier for the SUBSCRIBE request.
fromDisplayName
The display name of the contact who sent the SUBSCRIBE request.
from
The SIP URI of the contact who sent the SUBSCRIBE request.
subject
The subject of the SUBSCRIBE request. This may indicate the specific type of presence information the contact is interested in (e.g., "online", "busy").
This callback function is invoked when a contact's presence status changes to "online".
Parameters
fromDisplayName
The display name of the contact whose presence status has changed.
from
The SIP URI of the contact whose presence status has changed.
stateText
A human-readable description of the contact's presence status. In this case, it will be "online".
This callback function is invoked when a contact's presence status changes to "offline".
Parameters
fromDisplayName
The display name of the contact whose presence status has changed.
from
The SIP URI of the contact whose presence status has changed.
This callback function is invoked when the SDK receives a MESSAGE SIP message during a call. A MESSAGE message is used to exchange text or binary data between parties in a call.
Parameters
sessionId
The unique identifier for the call.
mimeType
The MIME type of the received message. This specifies the content type of the message, such as "text" or "image".
subMimeType
The sub-MIME type of the received message. This provides additional information about the content type, if applicable.
messageData
A byte array containing the content of the received message. This can be text or binary data.
messageDataLengt h
The length of the messageData in bytes.
This callback function is invoked when the SDK receives a MESSAGE SIP message that is not associated with an existing call (out-of-dialog message). This is typically used for messaging scenarios where a direct call is not established.
Parameters
fromDisplayName
The display name of the sender of the message.
from
The SIP URI of the sender of the message.
toDisplayName
The display name of the recipient of the message.
to
The SIP URI of the recipient of the message.
mimeType
The MIME type of the received message. This specifies the content type of the message, such as "text" or "image".
subMimeType
The sub-MIME type of the received message. This provides additional information about the content type, if applicable.
messageData
A byte array containing the content of the received message. This can be text or binary data.
messageDataLengt h
The length of the messageData in bytes.
This callback function is invoked when a MESSAGE message is sent successfully during a call.
Parameters
sessionId
The unique identifier for the call.
messageId
The unique identifier for the sent message. This is the same value that was returned by the sendMessage function.
This callback function is invoked when a MESSAGE message fails to be sent, either during a call or out-of-dialog.
Parameters
sessionId
The unique identifier for the call (if applicable).
messageId
The unique identifier for the message that failed to be sent.
reason
A human-readable description of the reason for the message failure.
code
A numerical code representing the reason for the message failure.
This callback function is invoked when a MESSAGE message is sent successfully out of dialog (not associated with an existing call).
Parameters
messageId
The unique identifier for the sent message.
fromDisplayName
The display name of the message sender.
from
The SIP URI of the message sender.
toDisplayName
The display name of the message recipient.
to
The SIP URI of the message recipient.
This callback function is invoked when a MESSAGE message fails to be sent out of dialog.
Parameters
messageId
The unique identifier for the message that failed to be sent. This is the same value that was returned by the SendOutOfDialogMessage function when the message was originally sent. It allows you to track and reference the failed message.
fromDisplayName
The display name of the message sender.
from
The SIP URI of the message sender.
toDisplayName
The display name of the message recipient.
to
he SIP URI of the message recipient.
reason
A human-readable description of the reason for the message failure.
code
A numerical code representing the reason for the message failure.
Play audio and video files finished events
This callback function is invoked when the playback of a file to the remote party has completed in a non-looping mode.
Parameters
sessionId
The unique identifier for the call.
fileName
The name of the file that was played.
This callback function is invoked when RTP statistics are received for a given session. This occurs after calling the getStatistics function.
Parameters
sessionId
The unique identifier for the call.
stat
A JSON string representing the RTP statistics for the session.
RTP callback events
This callback function is invoked when an RTP packet is received or sent during a call. This callback is enabled by calling the enableRtpCallback function.
Parameters
sessionId
The unique identifier for the call.
mediaType
The type of media associated with the RTP packet:
0: Audio
1: Video
2: Screen
direction
The direction of the RTP stream:
DIRECTION_SEND: Callback for sending RTP streams for a channel.DIRECTION_RECV: Callback for receiving RTP streams for a channel.
RTPPacket
A pointer to the memory containing the entire RTP packet.
packetSize
The size of the received RTP packet in bytes.
Note
It is important to avoid calling SDK API functions directly within this callback function, as it may lead to performance issues or unexpected behavior. Instead, consider posting a message to another thread to execute time-consuming operations.
Audio and video stream callback events
This callback function is invoked when audio packets are received or sent during a call. This callback is enabled by calling the enableAudioStreamCallback function.
Parameters
sessionId
The unique identifier for the call.
audioCallbackMod e
The type of audio callback, as specified in the enableAudioStreamCallback function.
data
A byte array containing the raw audio data in PCM format.
dataLength
The size of the audio data in bytes.
samplingFreqHz
The sampling frequency of the audio data in Hertz (Hz). Common values include 8000 and 16000.
Note
It is important to avoid calling SDK API functions directly within this callback function, as it may lead to performance issues or unexpected behavior. Instead, consider posting a message to another thread to execute time-consuming operations.
This callback function is invoked when video packets are received or sent during a call. This callback is enabled by calling the enableVideoStreamCallback function.
Parameters
sessionId
The unique identifier for the call.
videoCallbackMod e
The type of video callback, as specified in the enableVideoStreamCallback function.
width
The width of the video frame in pixels.
height
The height of the video frame in pixels.
data
A byte array containing the raw video data in YUV420 format (YV12).
dataLength
The size of the video data in bytes.
Note
It is important to avoid calling SDK API functions directly within this callback function, as it may lead to performance issues or unexpected behavior. Instead, consider posting a message to another thread to execute time-consuming operations.
Last updated