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.