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?

  1. Download the sample project from the PortSIP Website.

  2. Uncompress the .zip file.

  3. Open the project with Visual Studio.

  4. 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:

  1. Download and uncompress the sample project.

  2. Create a new “Windows Application” project in Visual Studio.

  3. Copy portsip_sdk.dll and portsip_media.dll from the sample project directory to your project’s output directories: bin\release and bin\debug.

  4. Copy the PortSIP folder from the sample project directory to your project folder and add it to the Solution.

  5. Implement the SIPCallbackEvents interface to process callback events.

  6. 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++:

  1. Download and uncompress the sample project.

  2. Create a new “MFC Application” project.

  3. Copy portsip_sdk.dll and portsip_media.dll from the sample project directory to your project’s output directories.

  4. Copy the include/PortSIPLib folder to your project folder and add the .hxx files from the PortSIPLib folder to your project.

  5. Copy the lib folder to your project folder and link portsip_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)?

  1. Uncompress the SDK sample project ZIP file and compile the P2PSample project.

  2. Run the P2PSample on device A and device B. For example, IP address for A is 192.168.1.10, and IP address for B is 192.168.1.11.

  3. 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).

  4. Click the Initialize button on both A and B. If the default port 5060 is already in use by another application, the P2PSample will prompt “Initialize failure”. In this case, click the Uninitialize button, change the local port, and click the Initialize button again.

  5. The log box will display “Initialized.” if the SDK is successfully initialized.

  6. 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, enter sip:111@192.168.1.10. If A used 5066 as the local port, for example, dial to sip: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

Int32 PortSIP.PortSIPLib.initialize (TRANSPORT_TYPE transportType, 
                                String localIp, 
                                Int32 localSIPPort,
                                PORTSIP_LOG_LEVEL logLevel, 
                                String logFilePath, 
                                Int32 maxCallSessions, 
                                String sipAgentString, 
                                Int32 audioDeviceLayer, 
                                Int32 videoDeviceLayer, 
                                String TLSCertificatesRootPath, 
                                String TLSCipherList, 
                                Boolean verifyTLSCertificate)

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.

String PortSIP.PortSIPLib.getVersion ()

Get the current version number of the SDK.

Returns

Return a current version number MAJOR.MINOR.PATCH of the SDK.

Int32 PortSIP.PortSIPLib.setLicenseKey (String key)

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.

Int32 PortSIP.PortSIPLib.setUser (String userName, 
                                String displayName, 
                                String authName, 
                                String password, 
                                String sipDomain, 
                                String sipServerAddr,
                                Int32 sipServerPort, 
                                String stunServerAddr, 
                                Int32 stunServerPort, 
                                String outboundServerAddr,
                                Int32 outboundServerPort)

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.

Int32 PortSIP.PortSIPLib.setDisplayName (String displayName)

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.

Int32 PortSIP.PortSIPLib.setInstanceId (String uuid)

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.

Int32 PortSIP.PortSIPLib.registerServer (Int32 expires, Int32 retryTimes)

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.

Int32 PortSIP.PortSIPLib.unRegisterServer (Int32 waitMS)

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.

Int32 PortSIP.PortSIPLib.enableRport (Boolean enable)

Enable/disable rport(RFC3581).

Parameters

enable

Set to true to enable the SDK to support rport. By default it is enabled.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Int32 PortSIP.PortSIPLib.enableEarlyMedia (Boolean enable)

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.

Int32 PortSIP.PortSIPLib.enablePriorityIPv6Domain (Boolean enable)

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.

Int32 PortSIP.PortSIPLib.setUriUserEncoding (String character, Boolean enable)

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.

Int32 PortSIP.PortSIPLib.setReliableProvisional (Int32 mode)

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.

Int32 PortSIP.PortSIPLib.enable3GppTags (Boolean enable)

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.

void PortSIP.PortSIPLib.enableCallbackSignaling (Boolean enableSending, 
                                Boolean enableReceived)

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.

Int32 PortSIP.PortSIPLib.enableRtpCallback (Int32 sessionId, 
                                Int32 mediaType, 
                                Int32 directionMode)

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

Int32 PortSIP.PortSIPLib.getNICNums ()

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.

Int32 PortSIP.PortSIPLib.getLocalIpAddress (Int32 index, 
                                StringBuilder ip, 
                                Int32 ipSize)

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

Int32 PortSIP.PortSIPLib.addAudioCodec (AUDIOCODEC_TYPE codecType)

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.

Int32 PortSIP.PortSIPLib.addVideoCodec (VIDEOCODEC_TYPE codecType)

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.

Boolean PortSIP.PortSIPLib.isAudioCodecEmpty ()

This function checks whether any audio codecs are enabled.

Returns

If no audio codec is enabled, it will return value true, otherwise false.

Boolean PortSIP.PortSIPLib.isVideoCodecEmpty ()

This function checks whether any video codecs are enabled.

Returns

If no video codec is enabled, it will return value true, otherwise false.

Int32 PortSIP.PortSIPLib.setAudioCodecPayloadType (AUDIOCODEC_TYPE codecType, 
                                                   Int32 payloadType)

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.

Int32 PortSIP.PortSIPLib.setVideoCodecPayloadType (VIDEOCODEC_TYPE codecType, 
                                                   Int32 payloadType)

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.

Int32 PortSIP.PortSIPLib.setAudioCodecParameter (AUDIOCODEC_TYPE codecType, 
                                                 String parameter)

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");

Int32 PortSIP.PortSIPLib.setVideoCodecParameter (VIDEOCODEC_TYPE codecType, 
                                                 String parameter)

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

Int32 PortSIP.PortSIPLib.setSrtpPolicy (SRTP_POLICY srtpPolicy, 
                                        Boolean allowSrtpOverUnsecureTransport)

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.

Int32 PortSIP.PortSIPLib.setRtpPortRange (Int32 minimumRtpPort, Int32 maximumRtpPort)

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.

Int32 PortSIP.PortSIPLib.enableCallForward (Boolean forBusyOnly, String forwardTo)

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.

Int32 PortSIP.PortSIPLib.disableCallForward ()

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.

Int32 PortSIP.PortSIPLib.enableSessionTimer (Int32 timerSeconds, 
                                             SESSION_REFRESH_MODE refreshMode)

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.

Int32 PortSIP.PortSIPLib.disableSessionTimer ()

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.

void PortSIP.PortSIPLib.setDoNotDisturb (Boolean state)

Enable or disable the "Do Not Disturb" feature.

Parameters

state

If set to true, the SDK will reject all incoming calls automatically.

Int32 PortSIP.PortSIPLib.enableAutoCheckMwi (Boolean state)

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.

Int32 PortSIP.PortSIPLib.setRtpKeepAlive (Boolean state, 
                                Int32 keepAlivePayloadType, 
                                Int32 deltaTransmitTimeMS)

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.

Int32 PortSIP.PortSIPLib.setKeepAliveTime (Int32 keepAliveTime)

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.

Int32 PortSIP.PortSIPLib.addSupportedMimeType (String methodName, String mimeType, String subMimeType)

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:

addSupportedMimeType("INFO", "text", "plain");

If you want to receive NOTIFY messages with "application/media_control+xml", use the following command:

addSupportedMimeType("NOTIFY", "application", "media_control+xml");

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

Int32 PortSIP.PortSIPLib.getSipMessageHeaderValue (String sipMessage, 
                                String headerName, 
                                StringBuilder headerValue, 
                                Int32 headerValueLength)

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:

StringBuilder value = new StringBuilder(); 
value.Length = 512; 
getSipMessageHeaderValue(message, name, value);

Int32 PortSIP.PortSIPLib.addSipMessageHeader (Int32 sessionId, 
                                String methodName, 
                                Int32 msgType, 
                                String headerName, 
                                String headerValue)

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.

Int32 PortSIP.PortSIPLib.removeAddedSipMessageHeader (Int32 sipMessageHeaderId)

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.

Int32 PortSIP.PortSIPLib.clearAddedSipMessageHeaders ()

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:

addExtensionHeader(-1, "ALL", 3, "Billing", "usd100.00");
addExtensionHeader(-1, "ALL", 3, "ServiceId", "8873456");
clearAddedSipMessageHeaders();
Int32 PortSIP.PortSIPLib.modifySipMessageHeader (Int32 sessionId, 
                                String methodName, 
                                Int32 msgType, 
                                String headerName, 
                                String headerValue)

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.

Int32 PortSIP.PortSIPLib.removeModifiedSipMessageHeader (Int32 sipMessageHeaderId)

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.

Int32 PortSIP.PortSIPLib.clearModifiedSipMessageHeaders ()

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:

modifySipMessageHeader(-1, "ALL", 3, "Expires", "1000");
modifySipMessageHeader(-1, "ALL", 3, "User-Agent", "MyTest Softphone 1.0");
clearModifiedSipMessageHeaders();

Audio and video functions

Int32 PortSIP.PortSIPLib.setAudioSamples (Int32 ptime, Int32 maxPtime)

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.

Int32 PortSIP.PortSIPLib.setAudioDeviceId (Int32 recordingDeviceId, 
                                           Int32 playoutDeviceId)

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.

Int32 PortSIP.PortSIPLib.setVideoOrientation (Int32 rotation)

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.

Int32 PortSIP.PortSIPLib.setVideoDeviceId (Int32 deviceId)

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.

Int32 PortSIP.PortSIPLib.setVideoResolution (Int32 width, Int32 height)

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.

Int32 PortSIP.PortSIPLib.setAudioBitrate (Int32 sessionId, AUDIOCODEC_TYPE audioCodecType, Int32 bitrateKbps)

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.

Int32 PortSIP.PortSIPLib.setVideoBitrate (Int32 sessionId, Int32 bitrateKbps)

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.

Int32 PortSIP.PortSIPLib.setVideoFrameRate (Int32 sessionId, Int32 frameRate)

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.

Int32 PortSIP.PortSIPLib.sendVideo (Int32 sessionId, Boolean sendState)

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.

void PortSIP.PortSIPLib.muteMicrophone (Boolean mute)

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).

void PortSIP.PortSIPLib.muteSpeaker (Boolean mute)

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).

void PortSIP.PortSIPLib.setChannelOutputVolumeScaling (Int32 sessionId, 
                                                       Int32 scaling)

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.

void PortSIP.PortSIPLib.setChannelInputVolumeScaling (Int32 sessionId, Int32 scaling)

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.

Int32 PortSIP.PortSIPLib.setRemoteVideoWindow (Int32 sessionId, 
                                               IntPtr remoteVideoWindow)

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.

Int32 PortSIP.PortSIPLib.displayLocalVideo (Boolean state, 
                                      Boolean mirror, 
                                      IntPtr localVideoWindow)

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.

Int32 PortSIP.PortSIPLib.setVideoNackStatus (Boolean state)

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

Int32 PortSIP.PortSIPLib.call (String callee, Boolean sendSdp, Boolean videoCall)

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.

Int32 PortSIP.PortSIPLib.rejectCall (Int32 sessionId, int code)

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.

Int32 PortSIP.PortSIPLib.hangUp (Int32 sessionId)

hangUp Hang up the call.

Parameters

sessionId

Session ID of the call.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Int32 PortSIP.PortSIPLib.answerCall (Int32 sessionId, Boolean videoCall)

answerCall Answer the incoming call.

Parameters

sessionId

The session ID of call.

videoCall

If the incoming call is a video call and the video codec is matched, set 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.

Int32 PortSIP.PortSIPLib.updateCall (Int32 sessionId, bool enableAudio, bool enableVideo, bool enableScreen)

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); 

Int32 PortSIP.PortSIPLib.hold (Int32 sessionId)

To place a call on hold.

Parameters

sessionId

The session ID of call.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Int32 PortSIP.PortSIPLib.unHold (Int32 sessionId)

Take off hold.

Parameters

sessionId

The session ID of call.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Int32 PortSIP.PortSIPLib.muteSession (Int32 sessionId, Boolean muteIncomingAudio, Boolean muteOutgoingAudio, Boolean muteIncomingVideo, Boolean muteOutgoingVideo)

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.

Int32 PortSIP.PortSIPLib.forwardCall (Int32 sessionId, String forwardTo)

Forward call to another one when receiving the incoming call.

Parameters

sessionId

The session ID of the call.

forwardTo

Target of the 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.

Int32 PortSIP.PortSIPLib.pickupBLFCall (String replaceDialogId, Boolean videoCall)

This function will be used for picking up a call based on the BLF (Busy Lamp Field) status. Parameters

replaceDialogId

The 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:

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

  2. 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.

Int32 PortSIP.PortSIPLib.sendDtmf (Int32 sessionId, DTMF_METHOD dtmfMethod, int code, int dtmfDuration, bool playDtmfTone)

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