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.

from

The contact who sends the SUBSCRIBE request.

subject

The subject of the SUBSCRIBE request.

- (void)onPresenceOnline:(NSString*)fromDisplayName
                    from:(NSString*)from
               stateText:(NSString*)stateText;

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.

- (void)onPresenceOffline:(NSString*)fromDisplayName from:(NSString*)from;

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

- (void)onRecvMessage:(long)sessionId
             mimeType:(NSString*)mimeType
          subMimeType:(NSString*)subMimeType
          messageData:(unsigned char*)messageData
    messageDataLength:(int)messageDataLength;

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

- (void)onRecvOutOfDialogMessage:(NSString*)fromDisplayName
                            from:(NSString*)from
                   toDisplayName:(NSString*)toDisplayName
                              to:(NSString*)to
                        mimeType:(NSString*)mimeType
                     subMimeType:(NSString*)subMimeType
                     messageData:(unsigned char*)messageData
               messageDataLength:(int)messageDataLength
                      sipMessage:(NSString*)sipMessage;

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.

- (void)onSendMessageSuccess:(long)sessionId
                   messageId:(long)messageId
                  sipMessage:(NSString*)sipMessage;

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.

- (void)onSendMessageFailure:(long)sessionId
                   messageId:(long)messageId
                      reason:(NSString*)reason
                        code:(int)code
                  sipMessage:(NSString*)sipMessage;

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.

- (void)onSendOutOfDialogMessageSuccess:(long)messageId
                        fromDisplayName:(NSString*)fromDisplayName
                                   from:(NSString*)from
                          toDisplayName:(NSString*)toDisplayName
                                     to:(NSString*)to
                             sipMessage:(NSString*)sipMessage;

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.

- (void)onSendOutOfDialogMessageFailure:(long)messageId
                        fromDisplayName:(NSString*)fromDisplayName
                                   from:(NSString*)from
                          toDisplayName:(NSString*)toDisplayName
                                     to:(NSString*)to
                                 reason:(NSString*)reason
                                   code:(int)code
                             sipMessage:(NSString*)sipMessage;

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.

- (void)onSubscriptionFailure:(long)subscribeId
                   statusCode:(int)statusCode;

This event will be triggered on sending SUBSCRIBE failure.

Parameters

subscribeId

The ID of SUBSCRIBE request.

statusCode

The status code.

- (void)onSubscriptionTerminated:(long)subscribeId;

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

- (void)onPlayFileFinished:(long)sessionId fileName:(NSString*)fileName;

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.

- (void)onStatistics:(long)sessionId stat:(NSString*)stat;

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

- (void)onRTPPacketCallback:(long)sessionId
                  mediaType:(int)mediaType
                  direction:(DIRECTION_MODE) direction
                  RTPPacket:(unsigned char *)RTPPacket
                 packetSize:(int)packetSize;

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

- (void)onAudioRawCallback:(long)sessionId
         audioCallbackMode:(int)audioCallbackMode
                      data:(unsigned char *)data
                dataLength:(int)dataLength
            samplingFreqHz:(int)samplingFreqHz;

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.

- (int)onVideoRawCallback:(long)sessionId
        videoCallbackMode:(int)videoCallbackMode
                    width:(int)width
                   height:(int)height
                     data:(unsigned char *)data
               dataLength:(int)dataLength;

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

- (int) initialize:(TRANSPORT_TYPE)transport
           localIP:(NSString*)localIP
      localSIPPort:(int)localSIPPort
          loglevel:(PORTSIP_LOG_LEVEL)logLevel
           logPath:(NSString*)logFilePath
           maxLine:(int)maxCallLines
             agent:(NSString*)sipAgent
  audioDeviceLayer:(int)audioDeviceLayer
  videoDeviceLayer:(int)videoDeviceLayer
TLSCertificatesRootPath:(NSString*)TLSCertificatesRootPath
     TLSCipherList:(NSString*)TLSCipherList
verifyTLSCertificate:(BOOL)verifyTLSCertificate
        dnsServers:(NSString*)dnsServers;

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.

- (int)setInstanceId:(NSString*)instanceId;

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.

- (void) unInitialize;

Un-initialize the SDK and release resources.

- (int) setUser:(NSString*)userName
    displayName:(NSString*)displayName
       authName:(NSString*)authName
       password:(NSString*)password
     userDomain:(NSString*)userDomain
      SIPServer:(NSString*)sipServer
  SIPServerPort:(int)sipServerPort
     STUNServer:(NSString*)stunServer
 STUNServerPort:(int)stunServerPort
 outboundServer:(NSString*)outboundServer
outboundServerPort:(int)outboundServerPort;

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.

- (int)setDisplayName:(NSString*)displayName;

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.

- (void) removeUser;

Remove user account info.

- (int)registerServer:(int)expires
           retryTimes:(int)retryTimes;

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.

- (int)refreshRegistration:(int)expires;

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.

- (int)unRegisterServer:(int)waitMS;

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.

- (int)setLicenseKey:(NSString*)key;

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

- (int)getNICNums;

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.

- (NSString*)getLocalIpAddress:(int)index;

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

- (int)addAudioCodec:(AUDIOCODEC_TYPE)codecType;

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.