User Manual for macOS
FAQ
Where can I download the PortSIP VoIP SDK for testing?
You can download the PortSIP VoIP SDK, along with sample projects, from the PortSIP Website.
What macOS versions are required for development?
Development using the PortSIP VoIP/IMS SDK for macOS requires a Mac running macOS Ventura 13.5 or later and Xcode 15.0 or above.
How can I create a new project with the PortSIP VoIP SDK?
Download the Sample Project: Download the sample project from tthe PortSIP Website and extract it to a desired directory.
Create a New Project: In Xcode, create a new OS X Cocoa Application project.
Add the PortSIPVoIPSDK Framework: Drag and drop the
PortSIPVoIPSDK.framework
from Finder to your project's Frameworks folder.Copy Frameworks Files: Under the Build Phases section of your project editor, add a "Copy Files" build phase. Specify the destination as "Frameworks" and add the
PortSIPVoIPSDK.framework
to be copied.Import the SDK: In your header file, import the SDK using the following line:
How can I process callback events?
Inherit the PortSIPEventDelegate: Your class should inherit the
PortSIPEventDelegate
protocol to handle callback events.Implement Callback Methods: Implement the necessary callback methods (e.g.,
onRegistrationState
,onCallState
) to handle specific events.
How do I initialize the SDK?
Create an Instance: Create an instance of the
PortSIPSDK
class.Set the Delegate: Set the delegate of the SDK instance to your class that implements the
PortSIPEventDelegate
protocol.
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.
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. |
Once the caller received the "183 session in progress" message, 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. |
existsEarlyMedia | By setting to true, it indicates that the call has early media. |
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 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.