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