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:
|
localIP | The local computer IP address to be bound (e.g., To allow the SDK to automatically choose the correct network interface (IP), use |
localSIPPort | The SIP message transport listener port (e.g., |
logLevel | Set the application log level to enable logging. When logging is enabled, the SDK will generate a log file named The supported log levels are:
|
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:
|
videoDeviceLayer | Specify the video device layer to be used:
|
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., |
localSipPort | The SIP message transport listener port (e.g., |
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 | 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 |
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 |
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. |
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 |
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 |
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:
|
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 |
enableReceived | Set to |
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:
|
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 |
ip | Specify the |
ipSize | Specify the |
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
|
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 VIDEO
|
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:
|
allowSrtpOverUnsecureTransport | The |
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 |
forwardTo | The call forward target. It must be in the format |
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):
|
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 |
Allows enabling or disabling the automatic check for Message Waiting Indication (MWI).
Parameters
state | If set to |
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 |
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 |
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 |
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 |
|
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 |
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 |
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 |
|
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 |
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 |
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 |
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
|
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 |
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 |
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 |
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 |
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 |
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:
|
direction | The direction of the RTP stream:
|
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 |
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 |
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