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.dll
andportsip_media.dll
from the sample project directory to your project’s output directories:bin\release
andbin\debug
.Copy the
PortSIP
folder from the sample project directory to your project folder and add it to the Solution.Implement the
SIPCallbackEvents
interface 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.dll
andportsip_media.dll
from the sample project directory to your project’s output directories.Copy the
include/PortSIPLib
folder to your project folder and add the.hxx
files from thePortSIPLib
folder to your project.Copy the
lib
folder to your project folder and linkportsip_sdk.lib
into 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
P2PSample
project.Run the
P2PSample
on 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
5060
is already in use by another application, theP2PSample
will 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.11
and click the Dial button. To make a call from B to A, entersip:111@192.168.1.10
. If A used5066
as 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_UDP
TRANSPORT_TLS
TRANSPORT_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 = -1
PORTSIP_LOG_ERROR = 1
PORTSIP_LOG_WARNING = 2
PORTSIP_LOG_INFO = 3
PORTSIP_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_UAC
SESSION_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
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 (camer