User Manual for iOS
FAQ
Where can I download the PortSIP VoIP SDK for testing?
You can download the PortSIP VoIP SDK and sample projects from the PortSIP website.
How can I compile the sample project?
Download the sample project from the PortSIP website.
Extract the downloaded .zip file.
Open the project in Xcode.
Compile the sample project directly.
What device models and iOS versions are required?
Applications built with the PortSIP VoIP SDK for iOS can run on iPhone 5s or later, iPod touch 6 or later, and iPad 5 or later devices. These devices must be running iOS 11 or higher.
We strongly recommend testing your applications on actual devices to ensure functionality and performance. Testing solely on the simulator may not provide an accurate picture of real-world behavior.
How can I create a new project with the PortSIP VoIP SDK?
Download the sample project and extract it to a desired directory.
In Xcode, create a new iOS project.
Drag and drop the
PortSIPVoIPSDK.frameworkfrom Finder to your project's Frameworks folder.Add required frameworks:
Go to Build Phases -> Link Binary With Libraries.
Add
libresolv.tbd,VideoToolbox.framework,Network.framework, andMetalKit.framework.
In Build Settings -> Other Linker Flags, add
-ObjC.Import the SDK in a header file:
Use code with caution.
Implement the
PortSIPEventDelegateprotocol in your class to handle callback events.Initialize the SDK:
Objective-C
Use code with caution.
For more details and examples, refer to the sample project source code provided by PortSIP.
Is the SDK thread-safe?
Yes, the PortSIP SDK is thread-safe. You can call API functions from multiple threads without worrying about synchronization issues. However, there are exceptions: the onAudioRawCallback, onVideoRawCallback, and onRTPPacketCallback callbacks should not be called directly from other threads.
Does the SDK support VoIP push notifications?
Yes, the PortSIP SDK supports VoIP push notifications. Refer to the PortSIP Knowledge Base for more details.
SDK Callback events
Register events
When successfully registered to server, this event will be triggered.
Parameters
statusText | The status text. |
statusCode | The status code. |
sipMessage | The SIP message received. |
If registration to SIP server fails, this event will be triggered.
Parameters
statusText | The status text. |
statusCode | The status code. |
sipMessage | The SIP message received. |
Call events
When the call is coming, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller |
caller | The caller. |
calleeDisplayNam e | The display name of callee. |
callee | The callee. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, it indicates that this call includes the audio. |
existsVideo | By setting to true, it indicates that this call includes the video. |
sipMessage | The SIP message received. |
If the outgoing call is being processed, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
```objc |
(void)onInviteSessionProgress: (long)sessionId audioCodecs: (NSString *)audioCodecs videoCodecs: (NSString *)videoCodecs existsEarlyMedia: (BOOL)existsEarlyMedia existsAudio: (BOOL)existsAudio existsVideo: (BOOL)existsVideo sipMessage: (NSString *)sipMessage
If the outgoing call is ringing, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
statusText | The status text. |
statusCode | The status code. |
sipMessage | The SIP message received. |
If the remote party answered the call, this event would be triggered.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller |
caller | The caller. |
calleeDisplayNam e | The display name of callee. |
callee | The callee. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, it indicates that this call includes the audio. |
existsVideo | By setting to true, it indicates that this call includes the video. |
sipMessage | The SIP message received. |
If the outgoing/incoming call fails, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
callerDisplayNam e | The display name of caller |
caller | The caller. |
calleeDisplayNam e | The display name of callee. |
callee | The callee. |
reason | The failure reason. |
code | The failure code. |
sipMessage | The SIP message received. |
This event will be triggered when remote party updates this call.
Parameters
sessionId | The session ID of the call. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
screenCodecs | The matched screen codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, it indicates that this call includes the audio. |
existsVideo | By setting to true, it indicates that this call includes the video. |
existsScreen | By setting to true, it indicates that this call includes the screen. |
sipMessage | The SIP message received. |
This event will be triggered when UAC sent/UAS received ACK (the call is connected). Some functions (hold, updateCall etc...) can be called only after the call is connected, otherwise it will return error.
Parameters
sessionId | The session ID of the call. |
If the enableCallForward method is called and a call is incoming, the call will be forwarded automatically and this event will be triggered.
Parameters
forwardTo | The target SIP URI for forwarding. |
This event will be triggered once remote side closes the call.
Parameters
sessionId | The session ID of the call. |
sipMessage | The SIP message received. |
If a user subscribed and his dialog status monitored, when the monitored user is holding a call or being rang, this event will be triggered.
Parameters
BLFMonitoredUri | the monitored user's URI |
BLFDialogState | - the status of the call |
BLFDialogId | - the id of the call |
BLFDialogDirecti on | - the direction of the call |
If the remote side has placed the call on hold, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
If the remote side un-holds the call, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
audioCodecs | The matched audio codecs. It's separated by "#" if there are more than one codecs. |
videoCodecs | The matched video codecs. It's separated by "#" if there are more than one codecs. |
existsAudio | By setting to true, it indicates that this call includes the audio. |
existsVideo | By setting to true, it indicates that this call includes the video. |
Refer events
This event will be triggered once receiving a REFER message.
Parameters
sessionId | The session ID of the call. |
referId | The ID of the REFER message. Pass it to acceptRefer or rejectRefer. |
to | The refer target. |
from | The sender of REFER message. |
referSipMessage | The SIP message of "REFER". Pass it to "acceptRefer" function. |
This callback will be triggered once remote side calls "acceptRefer" to accept the REFER.
Parameters
sessionId | The session ID of the call. |
This callback will be triggered once remote side calls "rejectRefer" to reject the REFER.
Parameters
sessionId | The session ID of the call. |
reason | Reason for rejecting. |
code | Rejecting code. |
When the refer call is being processed, this event will be trigged.
Parameters
sessionId | The session ID of the call. |
When the refer call rings, this event will be triggered.
Parameters
sessionId | The session ID of the call. |
When the refer call succeeds, this event will be triggered. ACTV means Active. For example: A starts the call with B, and A transfers B to C. When C accepts the refered call, A will receive this event.
Parameters
sessionId | The session ID of the call. |
When the refer call fails, this event will be triggered. ACTV means Active. For example: A starts the call with B, and A transfers B to C. When C rejects the refered call, A will receive this event.
Parameters
sessionId | The session ID of the call. |
reason | The error reason. |
code | The error code. |
Signaling events
This event will be triggered when receiving an SIP message. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
sessionId | The session ID of the call. |
message | The SIP message received. |
This event will be triggered when a SIP message is sent. This event is disabled by default. To enable, use enableCallbackSignaling.
Parameters
sessionId | The session ID of the call. |
message | The SIP message sent. |
MWI events
If there are any waiting voice messages (MWI), this event will be triggered.
Parameters
messageAccount | Account for voice message. |
urgentNewMessag eCount | Count of new urgent messages. |
urgentOldMessage Count | Count of old urgent messages. |
newMessageCount | Count of new messages. |
oldMessageCount | Count of old messages. |
If there are any waiting fax messages (MWI), this event will be triggered.
Parameters
messageAccount | Account for fax message. |
urgentNewMessag eCount | Count of new urgent messages. |
urgentOldMessage Count | Count of old urgent messages. |
newMessageCount | Count of new messages. |
oldMessageCount | Count of old messages. |
DTMF events
This event will be triggered when receiving a DTMF tone from remote side.
Parameters
sessionId | The session ID of the call. | ||
tone | DTMF tone. | ||
code | Description | ||
0 | The DTMF tone 0. | ||
1 | The DTMF tone 1. | ||
2 | The DTMF tone 2. | ||
3 | The DTMF tone 3. | ||
4 | The DTMF tone 4. | ||
5 | The DTMF tone 5. | ||
6 | The DTMF tone 6. | ||
7 | The DTMF tone 7. | ||
8 | The DTMF tone 8. | ||
9 | The DTMF tone 9. | ||
10 | The DTMF tone *. | ||
11 | The DTMF tone #. | ||
12 | The DTMF tone A. | ||
13 | The DTMF tone B. | ||
14 | The DTMF tone C. | ||
15 | The DTMF tone D. | ||
16 | The DTMF tone FLASH. |
INFO/OPTIONS message events
This event will be triggered when receiving the OPTIONS message.
Parameters
optionsMessage | The whole received OPTIONS message in text format. |
This event will be triggered when receiving the INFO message.
Parameters
infoMessage | The whole received INFO message in text format. |
This event will be triggered when receiving a NOTIFY message of the subscription.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
notifyMessage | The received INFO message in text format. |
messageData | The received message body. It can be either text or binary data. |
messageDataLengt h | The length of "messageData". |
Presence events
This event will be triggered when receiving the SUBSCRIBE request from a contact.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request. |
subject | The subject of the SUBSCRIBE request. |
This event will be triggered when the contact is online or changes presence status.
Parameters
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request. |
stateText | The presence status text. |
When the contact status is changed to offline, this event will be triggered. Parameters
fromDisplayName | The display name of contact. |
from | The contact who sends the SUBSCRIBE request |
MESSAGE message events
This event will be triggered when receiving a MESSAGE message in dialog.
Parameters
sessionId | The session ID of the call. |
mimeType | The message mime type. |
subMimeType | The message sub mime type. |
messageData | The received message body. It can be either text or binary data. |
messageDataLengt h | The length of "messageData". |
This event will be triggered when receiving a MESSAGE message out of dialog. For example: pager message.
Parameters
fromDisplayName | The display name of sender. |
from | The message sender. |
toDisplayName | The display name of receiver. |
to | The recipient. |
mimeType | The message mime type. |
subMimeType | The message sub mime type. |
messageData | The received message body. It can be text or binary data. |
messageDataLengt h | The length of "messageData". |
sipMessage | The SIP message received. |
This event will be triggered when the message is sent successfully in dialog.
Parameters
sessionId | The session ID of the call. |
messageId | The message ID. It's equal to the return value of sendMessage function. |
sipMessage | The SIP message received. |
This event will be triggered when the message fails to be sent out of dialog.
Parameters
sessionId | The session ID of the call. |
messageId | The message ID. It's equal to the return value of sendMessage function. |
reason | The failure reason. |
code | Failure code. |
sipMessage | The SIP message received. |
This event will be triggered when the message is sent successfully out of dialog.
Parameters
messageId | The message ID. It's equal to the return value of SendOutOfDialogMessage function. |
fromDisplayName | The display name of message sender. |
from | The message sender. |
toDisplayName | The display name of message receiver. |
to | The message receiver. |
sipMessage | The SIP message received. |
This event will be triggered when the message fails to be sent out of dialog.
Parameters
messageId | The message ID. It's equal to the return value of SendOutOfDialogMessage function. |
fromDisplayName | The display name of message sender |
from | The message sender. |
toDisplayName | The display name of message receiver. |
to | The message recipient. |
reason | The failure reason. |
code | The failure code. |
sipMessage | The SIP message received. |
This event will be triggered on sending SUBSCRIBE failure.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
statusCode | The status code. |
This event will be triggered when a SUBSCRIPTION is terminated or expired.
Parameters
subscribeId | The ID of SUBSCRIBE request. |
Play audio and video file finished events
If startPlayingFileToRemote function is called with no loop mode, this event will be triggered once the file play finished.
Parameters
sessionId | The session ID of the call. |
fileName | The play file name. |
If getStatistics function is called, this event will be triggered once receiving a RTP statistics .
Parameters
sessionId | The session ID of the call. |
stat | RTP statistics of a json format. |
RTP callback events
If enableRtpCallback function is called to enable the RTP callback, this event will be triggered once a RTP packet received.
Parameters
sessionId | The session ID of the call. | ||
mediaType | If the received RTP packet is audio this parameter is 0 video this parameter is 1 screen this parameter is 2 | ||
direction | The RTP stream callback direction. | ||
Type | Description | ||
DIRECTION_SEND | Callback the send RTP stream for one channel based on the given sessionId. | ||
DIRECTION_RECV | Callback the received RTP stream for one channel based on the given sessionId. |
Parameters
RTPPacket | The memory of whole RTP packet. |
packetSize | The size of received RTP Packet. |
Note
Don't call any SDK API functions in this event directly. If you want to call the API functions or other code, which is time-consuming, you should post a message to another thread and execute SDK API functions or other code in another thread.
Audio and video stream callback events
This event will be triggered once receiving the audio packets when enableAudioStreamCallback function is called.
Parameters
sessionId | The session ID of the call. |
audioCallbackMod e | The type that is passed in enableAudioStreamCallback function. |
data | The memory of audio stream. It's in PCM format. |
dataLength | The data size. |
samplingFreqHz | The audio stream sample in HZ. For example, it could be 8000 or 16000. |
Note
Don't call any SDK API functions in this event directly. If you want to call the API functions or other code, which is time-consuming, you should post a message to another thread and execute SDK API functions or other code in another thread.
This event will be triggered once received the video packets if called enableVideoStreamCallback function.
Parameters
sessionId | The session ID of the call. |
videoCallbackMod e | The type passed in enableVideoStreamCallback function. |
width | The width of video image. |
height | The height of video image. |
data | The memory of video stream. It's in YUV420 format, such as YV12. |
dataLength | The data size. |
Returns
If you changed the sent video data, dataLength should be returned, otherwise 0.
Note
Don't call any SDK API functions in this event directly. If you want to call the API functions or other code, which is time-consuming, you should post a message to another thread and execute SDK API functions or other code in another thread.
SDK functions
Initialize and register functions
Initialize the SDK.
Parameters
transport | Transport for SIP signaling. TRANSPORT_PERS_UDP/TRANSPORT_PERS_TCP is the PortSIP private transport for anti SIP blocking. It must be used with PERS Server. |
localIP | The local computer IP address to be bounded (for example: 192.168.1.108). It will be used for sending and receiving SIP messages and RTP packets. If this IP is transferred in IPv6 format, the SDK will use IPv6. If you want the SDK to choose correct network interface (IP) automatically, please pass the "0.0.0.0"(for IPv4) or "::" (for IPv6). |
localSIPPort | The SIP message transport listener port (for example: 5060). |
logLevel | Set the application log level. The SDK will generate "PortSIP_Log_datatime.log" file if the log enabled. |
logFilePath | The log file path. The path (folder) MUST be existent. |
maxCallLines | Theoretically, unlimited lines are supported depending on the device capability. For SIP client recommended value ranges 1 - 100. |
sipAgent | The User-Agent header to be inserted in SIP messages. |
audioDeviceLayer | 0 = Use OS default device 1 = Set to 1 to use the virtual audio device if the no sound device installed. |
videoDeviceLayer | 0 = Use OS default device 1 = Set to 1 to use the virtual video device if no camera installed. |
TLSCertificatesRo otPath | Specify the TLS certificate path, from which the SDK will load the certificates automatically. Note: On Windows, this path will be ignored, and SDK will read the certificates from Windows certificates stored area instead. |
TLSCipherList | Specify the TLS cipher list. This parameter is usually passed as empty so that the SDK will offer all available ciphers. |
verifyTLSCertificat e | Indicate if SDK will verify the TLS certificate. By setting to false, the SDK will not verify the validity of TLS certificate. |
dnsServers | Additional Nameservers DNS servers. Value null indicates system DNS Server. Multiple servers will be split by ";", e.g "8.8.8.8;8.8.4.4" |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the instance Id, the outbound instanceId((RFC5626) ) used in contact headers.
Parameters
instanceId | The SIP instance ID. If this function is not called, the SDK will generate an instance ID automatically. The instance ID MUST be unique on the same device (device ID or IMEI ID is recommended). Recommend to call this function to set the ID on Android devices. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Un-initialize the SDK and release resources.
Set user account info.
Parameters
userName | Account (username) of the SIP. It's usually provided by an IP-Telephony service provider. |
displayName | The display name of user. You can set it as your like, such as "James Kend". It's optional. |
authName | Authorization user name (usually equal to the username). |
password | The password of user. It's optional. |
userDomain | User domain. This parameter is optional. It allows to pass an empty string if you are not using domain. |
sipServer | SIP proxy server IP or domain. For example: xx.xxx.xx.x or sip.xxx.com. |
sipServerPort | Port of the SIP proxy server. For example: 5060. |
stunServer | Stun server, used for NAT traversal. It's optional and can pass an empty string to disable STUN. |
stunServerPort | STUN server port. It will be ignored if the outboundServer is empty. |
outboundServer | Outbound proxy server. For example: sip.domain.com. It's optional and allows to pass an empty string if not using outbound server. |
outboundServerPo rt | Outbound proxy server port. It will be ignored if the outboundServer is empty. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the display name of user.
Parameters
displayName | that will appear in the From/To Header. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remove user account info.
Register to SIP proxy server (login to server)
Parameters
expires | Registration refreshment interval in seconds. Maximum of 3600 allowed. It will be inserted into SIP REGISTER message headers. |
retryTimes | The retry times if failed to refresh the registration. Once set to <= 0, the retry will be disabled and onRegisterFailure callback triggered for retry failure. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code. If registration to server succeeds, onRegisterSuccess will be triggered, otherwise onRegisterFailure triggered.
Refresh the registration manually after successfully registered.
Parameters
expires | Registration refreshment interval in seconds. Maximum of 3600 supported. It will be inserted into SIP REGISTER message header. If it's set to 0, default value will be used. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code. If registration to server succeeds, onRegisterSuccess will be triggered, otherwise onRegisterFailure triggered.
Un-register from the SIP proxy server.
Parameters
waitMS | Wait for the server to reply that the un-registration is successful, waitMS is the longest waiting milliseconds, 0 means not waiting. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the license key. It must be called before setUser function.
Parameters
key | The SDK license key. Please purchase from PortSIP. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Parameters
NIC and local IP functions
Get the Network Interface Card numbers. Returns
If the function succeeds, it will return NIC numbers, which are 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 | The IP address index. For example, suppose the PC has two NICs. If we want to obtain the second NIC IP, please set this parameter as 1, and the first NIC IP index 0. |
Returns
The buffer for receiving the IP.
Audio and video codecs functions
Enable an audio codec. It will appear in SDP.
Parameters
codecType | Audio codec type. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable a video codec. It will appear in SDP.
Parameters
codecType | Video codec type. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Detect if the enabled audio codecs is empty.
Returns
If no audio codec is enabled, it will return value true, otherwise false.
Detect if enabled video codecs is empty or not.
Returns
If no video codec is enabled, it will return value true, otherwise false.
Set the RTP payload type for dynamic audio codec.
Parameters
codecType | Audio codec type 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 RTP payload type for dynamic Video codec.
Parameters
codecType | Video codec type 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 parameter for audio codec.
Parameters
codecType | Audio 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 a specific error code.
Remarks
Example:
[myVoIPsdk setAudioCodecParameter:AUDIOCODEC\_AMR parameter:"mode-set=0; octet-align=1; robust-sorting=0"];
Set the codec parameter for 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
Example:
[myVoIPsdk setVideoCodecParameter:VIDEOCODEC\_H264 parameter:"profile-level-id=420033; packetization-mode=0"];
Remove all enabled audio codecs.
Remove all enabled video codecs.
Additional settings functions
Get the current version number of the SDK.
Returns
Return a current version number MAJOR.MINOR.PATCH of the SDK.
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.
enable | Set to true to enable the SDK to support Early Media. By default the Early Media is disabled. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable which allows specifying the preferred protocol when a domain supports both IPV4 and IPV6 simultaneously.
Parameters
enable | Set to true to enable priority IPv6 Domain. with the default priority being IPV4. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Modifies the default URI user character needs to be escaped.
Parameters
character | The character to be modified, set one character at a time. |
enable | Whether escaping is required, true for allowing escaping, false for disabling escaping. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable PRACK.
Parameters
mode | Modes work as follows: 0 - Never, Disable PRACK,By default the PRACK is disabled. 1 - SupportedEssential, Only send reliable provisionals if sending a body and far end supports. 2 - Supported, Always send reliable provisionals if far end supports. 3 - Required Always send reliable provisionals. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable the 3Gpp tags, including "ims.icsi.mmtel" and "g.3gpp.smsip".
Parameters
enable | Set to true to enable the 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.
Enable/disable to callback the SIP messages.
Parameters
enableSending | Set as true to enable to callback the sent SIP messages, or false to disable. Once enabled, the "onSendingSignaling" event will be triggered when the SDK sends a SIP message. |
enableReceived | Set as true to enable to callback the received SIP messages, or false to disable. Once enabled, the "onReceivedSignaling" event will be triggered when the SDK receives a SIP message. |
Parameters
srtpPolicy | The SRTP policy. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the RTP ports range for audio and video streaming.
Parameters
minimumRtpPort | The minimum RTP port. |
maximumRtpPort | The maximum RTP port. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The port range ((max - min) / maxCallLines) should be greater than 4.
Enable call forwarding.
Parameters
forBusyOnly | If this parameter is set as true, the SDK will forward all incoming calls when currently it's busy. If it's set as false, the SDK forward all incoming calls anyway. |
forwardTo | The target of call forwarding. It must in the format of sip:xxxx@sip.portsip.com. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Disable the call forwarding. The SDK is not forwarding any incoming calls once this function is called.
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Allows to periodically refresh Session Initiation Protocol (SIP) sessions by sending INVITE requests repeatedly.
Parameters
timerSeconds | The value of the refreshment interval in seconds. Minimum of 90 seconds required. |
refreshMode | Allow to set the session refreshment by UAC or UAS: SESSION_REFERESH_UAC or SESSION_REFERESH_UAS; |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
The INVITE requests, or re-INVITEs, are sent repeatedly during an active call log to allow user agents (UA) or proxies to determine the status of a SIP session. Without this keep-alive mechanism, proxies for remembering incoming and outgoing requests (stateful proxies) may continue to retain call state needlessly. If a UA fails to send a BYE message at the end of a session or if the BYE message is lost because of network problems, a stateful proxy does not know that the session has ended. The re-INVITEs ensure that active sessions stay 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 the "Do not disturb" to enable/disable.
Parameters
state | If it is set to true, the SDK will reject all incoming calls anyway. |
Enable the CheckMwi to enable/disable.
Parameters
state | If it is set to true, the SDK will check Mwi automatically. |
Enable or disable to send RTP keep-alive packet when the call is established.
Parameters
state | Set as true to allow to send the keep-alive packet during the conversation. |
keepAlivePayload Type | The payload type of the keep-alive RTP packet. It's usually set to 126. |
deltaTransmitTime MS | The keep-alive RTP packet sending interval, in milliseconds. Recommended value ranges 15000 - 300000. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable or disable to send SIP keep-alive packet.
Parameters
keepAliveTime | This is the SIP keep-alive time interval in seconds. By setting to 0, the SIP keep-alive will be disabled. Recommended value is 30 or 50. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the audio capturing sample.
Parameters
ptime | It should be a multiple of 10 between 10 - 60 (with 10 and 60 inclusive). |
maxPtime | For the "maxptime" attribute, it should be a multiple of 10 between 10 - 60 (with 10 and 60 inclusive). It cannot be less than "ptime". |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
It will appear in the SDP of INVITE and 200 OK message as "ptime and "maxptime" attribute.
Set the SDK to receive the SIP message that includes special mime type.
Parameters
methodName | Method name of the SIP message, such as INVITE, OPTION, INFO, MESSAGE, UPDATE, ACK etc. For more details please refer to the RFC3261. |
|*mimeType *| The mime type of SIP message. |
|subMimeType| The sub mime type of SIP message. |
Returns If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
By default, PortSIP VoIP SDK supports the media types (mime types) listed in the below incoming SIP messages:
"message/sipfrag" in NOTIFY message. application/simple-message-summary" in NOTIFY message. "text/plain" in MESSAGE message. "application/dtmf-relay" in INFO message. "application/media_control+xml" in INFO message.
The SDK allows to receive SIP messages that include above mime types. Now if remote side sends an INFO SIP message with its "Content-Type" header value "text/plain", SDK will reject this INFO message, for "text/plain" of INFO message is not included in the default supported list. How should we enable the SDK to receive the SIP INFO messages that include "text/plain" mime type? The answer is to use addSupportedMimyType:
[myVoIPSdk addSupportedMimeType:@"INFO" mimeType:@"text" subMimeType:@"plain"];
To receive the NOTIFY message with "application/media_control+xml":
[myVoIPSdk addSupportedMimeType:@"NOTIFY" mimeType:@"application" ]subMimeType:@"media\_control+xml"];
For more details about the mime type, please visit: http://www.iana.org/assignments/media-types/
Access SIP message header functions
Access the SIP header of SIP message.
Parameters
sipMessage | The SIP message. |
headerName | The header with which to access the SIP message. |
Returns
If the function succeeds, it will return value headerValue. If the function fails, it will return value null.
Remarks
When receiving an SIP message in the onReceivedSignaling callback event, and user wishes to get SIP message header value, use getExtensionHeaderValue:
NSString* headerValue = [myVoIPSdk getSipMessageHeaderValue:message headerName:name];
Add the SIP Message header into the specified outgoing SIP message.
Parameters
sessionId | Add the header to the SIP message with the specified session Id only. By setting to -1, it will be added to all messages. |
methodName | Just add the header to the SIP message with specified method name. For example: "INVITE", "REGISTER", "INFO" etc. If "ALL" specified, it will add all SIP messages. |
msgType | 1 refers to apply to the request message, 2 refers to apply to the response message, 3 refers to apply to both request and response. |
headerName | The header name that will appear in 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 headers (custom header) added by addSipMessageHeader.
Parameters
addedSipMessageI d | The addedSipMessageId return by addSipMessageHeader. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the added extension headers (custom headers).
Remarks
For example, we have added two custom headers into every outgoing SIP message and wish to remove them.
Modify the special SIP header value for every outgoing SIP message.
Parameters
sessionId | The header to the SIP message with the specified session Id. By setting to -1, it will be added to all messages. |
methodName | Modify the header to the SIP message with specified method name only. For example: "INVITE", "REGISTER", "INFO" etc. If "ALL" specified, it will add all SIP messages. |
msgType | 1 refers to apply to the request message, 2 refers to apply to the response message, 3 refers to apply to both request and response. |
headerName | The SIP header name of which the value will be modified. |
headerValue | The heaver value to be modified. |
Returns
If the function succeeds, it will return modifiedSipMessageId, which is greater than 0. If the function fails, it will return a specific error code.
Remove the extension header (custom header) from every outgoing SIP message.
Parameters
modifiedSipMessa geId | The modifiedSipMessageId is returned by modifySipMessageHeader. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Clear the modified headers value, and do not modify every outgoing SIP message header values any longer.
Remarks
For example, to modify two headers' value for every outging SIP message and wish to clear it:
Audio and video functions
Set the video device that will be used for video call.
Parameters
deviceId | Device ID (index) for video device (camera). |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video Device Orientation.
Parameters
rotation | Device Orientation for video device (camera), e.g 0,90,180,270. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video capturing resolution.
Parameters
width | Video width. |
height | Video height. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the audio bit rate.
Parameters
sessionId | The session ID of the call. |
codecType | Audio codec type. |
bitrateKbps | The Audio bit rate in KBPS. |
- | - |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video bitrate.
Parameters
sessionId | The session ID of the call. Set it to -1 for all calls. |
bitrateKbps | The video bit rate in KBPS. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the video frame rate.
Parameters
sessionId | The session ID of the call. Set it to -1 for all calls. |
frameRate | The frame rate value, with its minimum value 5, and maximum value 30. Greater value renders better video quality but requires more bandwidth. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Usually you do not need to call this function to set the frame rate, as the SDK uses default frame rate.
Send the video to remote side.
Parameters
sessionId | The session ID of the call. |
sendState | Set to true to send the video, or false to stop sending. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the window for a session to display the received remote video image.
sessionId | The session ID of the call. |
remoteVideoWindo w | The PortSIPVideoRenderView for displaying 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.
Set the window for a session to display the received remote screen image.
Parameters
sessionId | The session ID of the call. |
remoteScreenWind ow | The PortSIPVideoRenderView for displaying received remote screen image. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Start/stop displaying the local video image.
Parameters
state | Set to true to display local video image. |
mirror | Set to true to display the mirror image of local video. |
localVideoWindow | The PortSIPVideoRenderView for displaying local video image from camera. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Enable/disable the NACK feature (RFC4585) to help to improve the video quality.
Parameters
state | Set to true to enable. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Mute the device microphone. It's unavailable for Android and iOS.
mute | If the value is set to true, the microphone is muted, or set to false to be un-muted. |
Mute the device speaker. It's unavailable for Android and iOS.
Parameters
mute | If the value is set to true, the speaker is muted, or set to false to be un-muted. |
Set the audio device that will be used for audio call.
Parameters
enable | By setting to true the SDK uses loudspeaker for audio call. This is available for mobile platform only. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Allow to switch between earphone and loudspeaker only.
Set a volume |scaling| to be applied to the outgoing signal of a specific audio channel.
Parameters
sessionId | The session ID of the call. |
scaling | Valid scale ranges [0, 1000]. Default is 100. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set a volume |scaling| to be applied to the microphone signal of a specific audio channel.
Parameters
sessionId | The session ID of the call. |
scaling | Valid scale ranges [0, 1000]. Default is 100. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Call functions
Make a call.
Parameters
callee | The callee. It can be a name only or full SIP URI. For example, user001, sip:user001@sip.iptel.org or sip:user002@sip.yourdomain.com:5068. |
sendSdp | If set to false, the outgoing call will not include the SDP in INVITE message. |
videoCall | If set to true and at least one video codec was 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, which is greater than 0. If the function fails, it will return a specific error code. Note: the function success just means the outgoing call is being processed, and you need to detect the final state of calling in onInviteTrying, onInviteRinging, onInviteFailure callback events.
rejectCall Reject the incoming call.
Parameters
sessionId | The session ID of the call. |
code | Reject code. For example, 486 and 480. |
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.
Parameters
sessionId | The session ID of the 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. If set to false, the answer call will not include video codec answer anyway. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
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 a specific error code.
Remarks
Example usage:
Example 1: A called B with the audio only, and B answered A, then there would be an audio conversation between A and B. Now if A wants to see B visually, A could use these functions to fulfill it.
Example 2: Remove video stream from current conversation.
Place a call on hold.
Parameters
sessionId | The 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.
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 true to mute incoming audio stream, and user cannot hear from remote side audio. |
muteOutgoingAudi o | Set it true to mute outgoing audio stream, and the remote side cannot hear the audio. |
muteIncomingVide o | Set it true to mute incoming video stream, and user cannot see remote side video. |
muteOutgoingVide o | Set it true to mute outgoing video stream, and the remote side cannot see video. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Forward the call to another user once received an incoming call.
Parameters
sessionId | The session ID of the call. |
forwardTo | Target of the call 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 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 ID of the call to be picked up. It comes with onDialogStateUpdated callback. |
videoCall | Indicates if it is video call or audio call to be picked up. |
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 | Support sending DTMF tone with two methods: DTMF_RFC2833 and DTMF_INFO. The DTMF_RFC2833 is recommended. | ||
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 | By setting 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. It could 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
[myVoIPSdk refer:sessionId referTo:@"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.
Make an attended refer.
Parameters
sessionId | The session ID of the call. |
replaceSessionId | Session ID of the replaced call. |
referTo | Target of the refer. 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.
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 embedded 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.
Once the REFER request accepted, 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. |
referSignaling | The SIP message of REFER request that comes from onReceivedRefer callback event. |
Returns
If the function succeeds, it will return a session ID that is greater than 0 to the new call for REFER, otherwise returns a specific error code that is 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 sending 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
To send the PCM stream data to another side, this function MUST be called first.
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 in 16bit, mono. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Usually we should use it like below:
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 to 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. |
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 we should use it like below:
RTP packets, audio stream and video stream callback functions
Set the RTP callbacks to allow to access the sent and received RTP packets.
Parameters
sessionId | The session ID of call. | ||
mediaType | 0 -audo 1-video 2-screen. | ||
mode | The RTP stream callback mode. | ||
Type | Description | ||
DIRECTION_SEND | Callback the send RTP stream for one channel based on the given sessionId. | ||
DIRECTION_RECV | Callback the received RTP stream for one channel based on the given sessionId. | ||
DIRECTION_SEND_RECV | Callback both local and remote RTP stream 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.
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. | ||
callbackMode | The audio stream callback mode. | ||
Type | Description | ||
DIRECTION_SEND | Callback the audio stream from microphone 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 local and remote audio stream 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
onAudioRawCallback event will be triggered if the callback is enabled.
Enable/disable the video stream callback.
Parameters
sessionId | The session ID of call. | ||
callbackMode | The video stream callback mode. | ||
Mode | Description | ||
DIRECTION_INACTIVE | Disable video stream callback. | ||
DIRECTION_SEND | Local video stream callback. | ||
DIRECTION_RECV | Remote video stream callback. | ||
DIRECTION_SEND_RECV | Both of local and remote video stream callback. |
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 filepath to which the recording will be saved. It must be existent. |
recordFileName | The filename of the recording. For example audiorecord.wav or videorecord.avi. |
appendTimeStamp | Set to true to append the timestamp to the filename of the recording. |
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 recording.
Parameters
sessionId | The session ID of call conversation. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Play audio and video files to remote party
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 | If it is set to 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. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Play a file to locally.
Parameters
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.
Used for the loop back testing against audio device.
Parameters
enable | Set to true to start audio look back test, or false to stop. |
Conference functions
Create an audio conference.
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.
Parameters
conferenceVideoW indow | The PortSIPVideoRenderView used for displaying the conference video. |
videoWidth | The conference video width. |
videoHeight | The conference video height. |
- | - |
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.
Destroy the existent conference.
Set the window for a conference that is used to display the received remote video image.
Parameters
conferenceVideoW indow | The PortSIPVideoRenderView 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, please un-hold first.
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 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.
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.
Set the DSCP (differentiated services code point) value of QoS (Quality of Service) for audio channel.
Parameters
state | Set to YES to enable audio QoS, and DSCP value will be 46; or NO to disable audio QoS, and DSCP value will be 0. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the DSCP (differentiated services code point) value of QoS (Quality of Service) for video channel.
Parameters
state | Set to YES to enable video QoS and DSCP value will be 34; or NO to disable video QoS, and DSCP value will be 0. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Set the MTU size for video RTP packet.
Parameters
mtu | Set MTU value. Allowed value ranges 512-65507. Other values will be automatically changed to the default 1400. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Media 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 it. |
Enable/disable Comfort Noise Generator (CNG).
Parameters
state | Set to true to enable CNG, or false to disable. |
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 an INFO message to remote side in dialog.
Parameters
sessionId | The session ID of call. |
mimeType | The mime type of INFO message. |
subMimeType | The sub mime type of INFO message. |
infoContents | The contents to be sent with INFO message. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
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 to be sent with MESSAGE message. Binary data allowed. |
messageLength | The message size. |
Returns
If the function succeeds, it will return a message ID that allows to track the message sending state in onSendMessageSuccess and onSendMessageFailure. If the function fails, it will return a specific error code less than 0.
Remarks
Example 1: Send a plain text message. Note: to send other languages text, please use the UTF-8 to encode the message before sending.
[myVoIPsdk sendMessage:sessionId mimeType:@"text" subMimeType:@"plain" message:data messageLength:dataLen];
Example 2: Send a binary message.
[myVoIPsdk sendMessage:sessionId mimeType:@"application" subMimeType:@"vnd.3gpp.sms" message:data messageLength:dataLen];
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 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 UTF-8 to encode the message before sending.
[myVoIPsdk sendOutOfDialogMessage:@"sip:user1@sip.portsip.com" mimeType:@"text" subMimeType:@"plain" message:data messageLength:dataLen];
Example 2: Send a binary message.
[myVoIPsdk sendOutOfDialogMessage:@"sip:user1@sip.portsip.com" mimeType:@"application" subMimeType:@"vnd.3gpp.sms" isSMS:NO message:data messageLength:dataLen];
Presence functions
Indicate that SDK uses the P2P mode for presence or presence agent mode.
Parameters
mode | 0 - P2P mode; 1 - Presence Agent mode, default is P2P mode. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Since presence agent mode requires the PBX/Server support the PUBLISH, please ensure you have your server and PortSIP PBX support this feature. For more details please visit: https://www.portsip.com/portsip-pbx
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.
Send a SUBSCRIBE message for subscribing the contact's presence status.
Parameters
contact | 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 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.
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.
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.
Send a NOTIFY message to contact to notify that presence status is online/offline/changed.
Parameters
subscribeId | Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe that includes the Subscription ID will be triggered. |
statusText | The state text of presence status. For example: "I'm here", offline must use "offline" |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.
Send a SUBSCRIBE message to remote side.
Parameters
to | The subscribe user. |
eventName | The event name to be subscribed. |
Returns
If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.
Remarks
Example 1, to subscribe the MWI (Message Waiting notifications), You can use this code: long 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 is the one 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); '
Keep awake functions
Functions
Keep VoIP awake in the background. @discussion If you want your application to be able to receive the incoming call while it's running in background, you should call this function in applicationDidEnterBackground.
Returns
If the function succeeds, it will return value true. If the function fails, it will return value false.
Keep VoIP awake in the background. @discussion Call this function in applicationWillEnterForeground once your application comes back to foreground.
Returns
If the function succeeds, it will return value true. If the function fails, it will return value false.
Audio Controller
Start Audio Device. @discussion Call it as AVAudioSessionInterruptionTypeEnded.
Returns
If the function succeeds, it will return value true. If the function fails, it will return value false.
Stop Audio Device. @discussion Call it as AVAudioSessionInterruptionTypeBegan.
Returns
If the function succeeds, it will return value true. If the function fails, it will return value false.
Enable/disable CallKit(Native Integration).
Parameters
state | Set to true to enable CallKit, 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.
PortSIPVideoRenderView
Change the Video Render size.
Remarks
Example:
Last updated