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?

  1. Download the sample project from the PortSIP website.

  2. Extract the downloaded .zip file.

  3. Open the project in Xcode.

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

  1. Download the sample project and extract it to a desired directory.

  2. In Xcode, create a new iOS project.

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

  4. Add required frameworks:

    • Go to Build Phases -> Link Binary With Libraries.

    • Add libresolv.tbd, VideoToolbox.framework, Network.framework, and MetalKit.framework.

  5. In Build Settings -> Other Linker Flags, add -ObjC.

  6. Import the SDK in a header file:

    #import <PortSIPVoIPSDK/PortSIPVoIPSDK.h>

    Use code with caution.

  7. Implement the PortSIPEventDelegate protocol in your class to handle callback events.

  8. Initialize the SDK:

    Objective-C

    mPortSIPSDK = [[PortSIPSDK alloc] init];
    mPortSIPSDK.delegate = self;

    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

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

```objc

  • (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.  |

```objc
- (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