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?

  1. Download the Sample Project: Download the sample project from tthe PortSIP Website and extract it to a desired directory.

  2. Create a New Project: In Xcode, create a new OS X Cocoa Application project.

  3. Add the PortSIPVoIPSDK Framework: Drag and drop the PortSIPVoIPSDK.framework from Finder to your project's Frameworks folder.

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

  5. Import the SDK: In your header file, import the SDK using the following line:

    #import <PortSIPVoIPSDK/PortSIPVoIPSDK.h>

How can I process callback events?

  1. Inherit the PortSIPEventDelegate: Your class should inherit the PortSIPEventDelegate protocol to handle callback events.

  2. Implement Callback Methods: Implement the necessary callback methods (e.g., onRegistrationState, onCallState) to handle specific events.

How do I initialize the SDK?

  1. Create an Instance: Create an instance of the PortSIPSDK class.

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

- (void)onRegisterSuccess: (NSString *)statusText 
              statusCode: (int)statusCode 
              sipMessage: (NSString *)sipMessage

When successfully registered to server, this event will be triggered.

Parameters

statusText

The status text.

statusCode

The status code.

sipMessage

The SIP message received.

- (void)onRegisterFailure: (NSString *)statusText 
              statusCode: (int)statusCode 
              sipMessage: (NSString *)sipMessage

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

- (void)onInviteIncoming: (long)sessionId 
       callerDisplayName: (NSString *)callerDisplayName 
                  caller: (NSString *)caller 
       calleeDisplayName: (NSString *)calleeDisplayName 
                  callee: (NSString *)callee 
             audioCodecs: (NSString *)audioCodecs 
             videoCodecs: (NSString *)videoCodecs 
             existsAudio: (BOOL)existsAudio 
             existsVideo: (BOOL)existsVideo 
              sipMessage: (NSString *)sipMessage

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.

- (void)onInviteTrying: (long)sessionId

If the outgoing call is being processed, this event will be triggered.

Parameters

sessionId

The session ID of the call.

- (void)onInviteSessionProgress:(long)sessionId
                    audioCodecs:(NSString*)audioCodecs
                    videoCodecs:(NSString*)videoCodecs
               existsEarlyMedia:(BOOL)existsEarlyMedia
                    existsAudio:(BOOL)existsAudio
                    existsVideo:(BOOL)existsVideo
                     sipMessage:(NSString*)sipMessage;

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.

- (void)onInviteRinging: (long)sessionId 
              statusText: (NSString *)statusText 
              statusCode: (int)statusCode 
              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.

- (void)onInviteAnswered: (long)sessionId 
       callerDisplayName: (NSString *)callerDisplayName 
                  caller: (NSString *)caller 
       calleeDisplayName: (NSString *)calleeDisplayName 
                  callee: (NSString *)callee 
             audioCodecs: (NSString *)audioCodecs 
             videoCodecs: (NSString *)videoCodecs 
             existsAudio: (BOOL)existsAudio 
             existsVideo: (BOOL)existsVideo 
              sipMessage: (NSString *)sipMessage

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.

- (void)onInviteFailure: (long)sessionId 
      callerDisplayName: (NSString *)callerDisplayName 
                 caller: (NSString *)caller 
      calleeDisplayName: (NSString *)calleeDisplayName 
                 callee: (NSString *)callee 
                 reason: (NSString *)reason 
                   code: (int)code 
             sipMessage: (NSString *)sipMessage

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.

- (void)onInviteUpdated: (long)sessionId 
             audioCodecs: (NSString *)audioCodecs 
             videoCodecs: (NSString *)videoCodecs 
             screenCodecs: (NSString *)screenCodecs 
             existsAudio: (BOOL)existsAudio 
             existsVideo: (BOOL)existsVideo 
             existsScreen: (BOOL)existsScreen 
              sipMessage: (NSString *)sipMessage

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.

- (void)onInviteConnected: (long)sessionId

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.

- (void)onInviteBeginingForward: (NSString *)forwardTo

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.

- (void)onInviteClosed: (long)sessionId 
            sipMessage: (NSString *)sipMessage

This event will be triggered once remote side closes the call.

Parameters

sessionId

The session ID of the call.

sipMessage

The SIP message received.

- (void)onDialogStateUpdated: (NSString *)BLFMonitoredUri 
              BLFDialogState: (NSString *)BLFDialogState 
                BLFDialogId: (NSString *)BLFDialogId 
          BLFDialogDirection: (NSString *)BLFDialogDirection

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

- (void)onRemoteHold: (long)sessionId

If the remote side has placed the call on hold, this event will be triggered.

Parameters

sessionId

The session ID of the call.

- (void)onRemoteUnHold: (long)sessionId 
            audioCodecs: (NSString *)audioCodecs 
            videoCodecs: (NSString *)videoCodecs 
            existsAudio: (BOOL)existsAudio 
            existsVideo: (BOOL)existsVideo

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

- (void)onReceivedRefer:(long)sessionId
                referId:(long)referId
                     to:(NSString*)to
                   from:(NSString*)from
        referSipMessage:(NSString*)referSipMessage;

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.

- (void)onReferAccepted:(long)sessionId;

This callback will be triggered once remote side calls "acceptRefer" to accept the REFER.

Parameters

sessionId

The session ID of the call.

- (void)onReferRejected:(long)sessionId 
                 reason:(NSString*)reason
                   code:(int)code;

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.

- (void)onTransferTrying:(long)sessionId;

When the refer call is being processed, this event will be trigged.

Parameters

sessionId

The session ID of the call.

- (void)onTransferRinging:(long)sessionId;

When the refer call rings, this event will be triggered.

Parameters

sessionId

The session ID of the call.

- (void)onACTVTransferSuccess:(long)sessionId;

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.

- (void)onACTVTransferFailure:(long)sessionId 
                       reason:(NSString*)reason
                         code:(int)code;

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

- (void)onReceivedSignaling:(long)sessionId 
                    message:(NSString*)message; 

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.

- (void)onSendingSignaling:(long)sessionId 
                   message:(NSString*)message; 

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

- (void)onWaitingVoiceMessage:(NSString*)messageAccount
        urgentNewMessageCount:(int)urgentNewMessageCount
        urgentOldMessageCount:(int)urgentOldMessageCount
              newMessageCount:(int)newMessageCount
              oldMessageCount:(int)oldMessageCount;

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.

- (void)onWaitingFaxMessage:(NSString*)messageAccount
      urgentNewMessageCount:(int)urgentNewMessageCount
      urgentOldMessageCount:(int)urgentOldMessageCount
            newMessageCount:(int)newMessageCount
            oldMessageCount:(int)oldMessageCount;

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

- (void)onRecvDtmfTone:(long)sessionId 
                  tone:(int)tone;

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

- (void)onRecvOptions:(NSString*)optionsMessage;

This event will be triggered when receiving the OPTIONS message.

Parameters

optionsMessage

The whole received OPTIONS message in text format.

- (void)onRecvInfo:(NSString*)infoMessage;

This event will be triggered when receiving the INFO message.

Parameters

infoMessage

The whole received INFO message in text format.

- (void)onRecvNotifyOfSubscription:(long)subscribeId
                     notifyMessage:(NSString*)notifyMessage
                       messageData:(unsigned char*)messageData
                 messageDataLength:(int)messageDataLength;

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

- (void)onPresenceRecvSubscribe:(long)subscribeId
                fromDisplayName:(NSString*)fromDisplayName
                           from:(NSString*)from
                        subject:(NSString*)subject; 

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.