Inherits from NSObject
Conforms to FlurryEventsDelegate
UserInfoDelegate
WaitIndicatorDelegate
Declared in SIPPhone.h

Overview

The SIPPhone class encapsules the SIP communication layer of the C2Call SDK.

The SIPPhone class will be instantiated by the C2CallPhone class. It’s not recommended to use the SIPPhone methods directly. All relevant call and messaging specific methods are mirrored in the C2CallPhone class for convenience.

Tasks

Properties

SIPPhone lifecycle handling

Call handling methods

Message Functions

Remote Party Information

DTMF Tones

Static Methods

Properties

callStatus

Current call status information

@property (nonatomic, readonly) SCCallStatus callStatus

Discussion

Available call states:

SCCallStatusNone        - No active call
SCCallStatusDialing     - Dialing
SCCallStatusRinging     - Ringing
SCCallStatusConnected   - Connected

Declared In

SIPPhone.h

callerIdVerified

This option will be automatically set if the callerid of the user is verified

@property (nonatomic) BOOL callerIdVerified

Declared In

SIPPhone.h

delegate

SIPPhone delegate.

@property (nonatomic, weak) id<SIPPhoneDelegate> delegate

Declared In

SIPPhone.h

groupCall

Is the current call a group call

@property (nonatomic, readonly) BOOL groupCall

Declared In

SIPPhone.h

isCaller

Is this client the caller in the current active call?

@property (nonatomic, readonly) BOOL isCaller

Declared In

SIPPhone.h

preferMessageEncryption

Automatically uses public key encryption for instant messages and rich media messages if available for the receiver

@property (nonatomic) BOOL preferMessageEncryption

Discussion

In case the receiver provdes a public key in his user record, automatically force end-to-end encryption for instant messages and rich media message attachments

Declared In

SIPPhone.h

userid

SIPPhone userid.

@property (nonatomic, readonly) NSString *userid

Declared In

SIPPhone.h

videoCall

Is the current call a video call

@property (nonatomic, readonly) BOOL videoCall

Declared In

SIPPhone.h

Class Methods

currentPhone

Current SIPPhone Instance.

+ (SIPPhone *)currentPhone

Return Value

Current SIPPhone Instance

Declared In

SIPPhone.h

normalizeNumber:

+ (NSString *)normalizeNumber:(id)number

setDefaultOfflineStatus:

Set the default OfflineStatus

+ (void)setDefaultOfflineStatus:(id)status

Parameters

status
  • Offline status in background or when application will exit

Discussion

Valid Values are: OS_OFFLINE, OS_IPUSH, OS_IPUSHCALL

Declared In

SIPPhone.h

setDisableTunnel:

Disable the UDP Tunnel

+ (void)setDisableTunnel:(id)disable

Parameters

disable
  • YES - Don’t use a UDP Tunnel Connection at all

Declared In

SIPPhone.h

setForceCallerIdVerify:

Set this option if you want to allow calls to PSTN / Landline only for verified callerids

+ (void)setForceCallerIdVerify:(id)forceCallerIdVerify

Discussion

In case the user try to call or SMS to a landline or mobile phone number and his callerId has not been verified via PIN SMS / PIN Call, the action will be denied by the API and an NSNotification is posted:

NSNotification: SC_CALLERIDVERFICATION_REQUIRED

You can handle this notification and present a dialog to the user to verify his callerid first.

Declared In

SIPPhone.h

setForceRinging:

Force Ringing instead of SessionProgress

+ (void)setForceRinging:(id)force

Parameters

force
  • Enable / Disable

Discussion

SessionProgress is the ringback tone send by the receiver when the other phone is ringing. Sometimes, the session progress fails to deliver audio data, so no ringback tone will be played. Setting forceRinging will always play the locally created ringing sound.

Declared In

SIPPhone.h

setForceTunnel:

Force to use a UDP Tunnel Connection

+ (void)setForceTunnel:(id)force

Parameters

force
  • YES - Always use a tunnel connection (only for testing purpuses)

Declared In

SIPPhone.h

setUDPTunnelHost:andPort:

Set the default UDP Tunnel server and port

+ (void)setUDPTunnelHost:(id)tunnelHost andPort:(id)tunnelPort

Parameters

tunnelHost
  • Hostname of the Tunnel Server
tunnelPort
  • Port of the Tunnel Server

Declared In

SIPPhone.h

setUseG729:

Enable G729 Codec for VoIP Audio

+ (void)setUseG729:(id)use

Parameters

use
  • Enable / Disable the codec

Discussion

IMPORTANT: Enabling the G729 Codec requires to license it from the patent owner. Default G729 is disabled.

Declared In

SIPPhone.h

speakerOff

Turns Speaker Off during a call-

+ (void)speakerOff

Discussion

On iPhone only.

Declared In

SIPPhone.h

speakerOn

Turns Speaker On during a call.

+ (void)speakerOn

Discussion

On iPhone only.

Declared In

SIPPhone.h

Instance Methods

callAction

Receive callAction submitted with the inbound call notification

- (NSString *)callAction

Return Value

User defined call action

Discussion

In order to support specific user definied call actions, the caller can provide an a user defined action parameter, for example “EMERGENCY” when calling, so that the receiver of the call can differently notified.

Declared In

SIPPhone.h

callNumber:

Calls a phone number.

- (void)callNumber:(id)number

Parameters

number
  • Phone number in international format

Discussion

Calling a phone number, the number should typically start with the + and the international country code, followed by the area code without leading “0” and then the number (e.g. +14081234567). If the submitted number is not in international format, the function automatically tries to convert the number into international format.

Declared In

SIPPhone.h

callVideo:

Calls another C2Call Service user or group via Video call.

- (void)callVideo:(id)callee

Parameters

callee
  • C2Call Userid or Email Address of a registered user

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. In order to call a user by his email address, simply do:

[[SIPPhone currentPhone] callVideo:@“max.muster@registeredemail.com”];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

callVideo:callAction:

Calls another C2Call Service user via Video call providing an additional action parameter

- (void)callVideo:(id)callee callAction:(id)action

Parameters

callee
  • C2Call Userid or Email Address of a registered user
action
  • User defined action parameter

Discussion

In addition to the regular callVideo method, this method allows to submit an additional user defined action parameter. This parameter can be retrieved at the receiver side via [[SIPPhone currentPhone] callAction] when the call has been notified. This allows to take specific action at the receiver, for example for emergency cases. The action parameter should be a single word only ASCII characters, for example @“EMERGENCY”

Declared In

SIPPhone.h

callVideo:groupCall:

Calls another C2Call Service user or group via Video call.

- (void)callVideo:(id)callee groupCall:(id)isGroupCall

Parameters

callee
  • C2Call Userid or Email Address of a registered user
isGroupCall
  • Specify whether it’s a group call.

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. In order to call a user by his email address, simply do:

[[SIPPhone currentPhone] callVideo:@“max.muster@registeredemail.com”];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

callVoIP:

Calls another C2Call Service user or group via VoIP call.

- (void)callVoIP:(id)callee

Parameters

callee
  • C2Call Userid or Email Address of a registered user

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. For example, the userid of the C2Call Test Call is “9bc2858f1194dc1c107”. In order to call the Test Call simply do:

[[SIPPhone currentPhone] callVoIP:@“9bc2858f1194dc1c107”];

In order to call a user by his email address, simply do:

[[SIPPhone currentPhone] callVoIP:@“max.muster@registeredemail.com”];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

callVoIP:callAction:

Calls another C2Call Service user via VoIP call providing an additional action parameter

- (void)callVoIP:(id)callee callAction:(id)action

Parameters

callee
  • C2Call Userid or Email Address of a registered user
action
  • User defined action parameter

Discussion

In addition to the regular callVoIP method, this method allows to submit an additional user defined action parameter. This parameter can be retrieved at the receiver side via [[SIPPhone currentPhone] callAction] when the call has been notified. This allows to take specific action at the receiver, for example for emergency cases. The action parameter should be a single word only ASCII characters, for example @“EMERGENCY”

Declared In

SIPPhone.h

callVoIP:groupCall:

Calls another C2Call Service user or group via VoIP call.

- (void)callVoIP:(id)callee groupCall:(id)isGroupCall

Parameters

callee
  • C2Call Userid or Email Address of a registered user
isGroupCall
  • Specify whether it’s a group call.

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. For example, the userid of the C2Call Test Call is “9bc2858f1194dc1c107”. In order to call the Test Call simply do:

[[SIPPhone currentPhone] callVoIP:@“9bc2858f1194dc1c107”];

In order to call a user by his email address, simply do:

[[SIPPhone currentPhone] callVoIP:@“max.muster@registeredemail.com”];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

didBecomeActive

Handles the Application Status didBecomeActive.

- (void)didBecomeActive

Discussion

The actual SIPPhone didBecomeActive is handled automatically by C2CallPhone. Calling this method manually is not recommended.

Declared In

SIPPhone.h

didEnterBackground

Handles the Application Status didEnterBackground.

- (void)didEnterBackground

Discussion

The actual SIPPhone didEnterBackground is handled automatically by C2CallPhone. Calling this method manually is not recommended.

Declared In

SIPPhone.h

didReceiveCallInBackground

Handles an incoming call while in background

- (void)didReceiveCallInBackground

Declared In

SIPPhone.h

endToneEvent

Ends a DTMF tone event.

- (void)endToneEvent

Declared In

SIPPhone.h

forceCallerIdVerify

Return forceCallerIdVerify status

- (BOOL)forceCallerIdVerify

Declared In

SIPPhone.h

forceTunnel

Force a UDP Tunnel Connection

- (BOOL)forceTunnel

Declared In

SIPPhone.h

hangUp

Hangs up a call.

- (void)hangUp

Discussion

Hangs up an active call.

Declared In

SIPPhone.h

inboundLine

InboundCall line identifier

- (NSString *)inboundLine

Return Value

Inbound Line Number or “VoIP”

Discussion

If a call comes from an external number, this method returns the number which has been called.

Declared In

SIPPhone.h

initWithProperties:

Classes Initialization with a dictionary of properties.

- (id)initWithProperties:(id)properties

Parameters

properties

A dictionary of properties

Return Value

SIPPhone instance

Discussion

The actual SIPPhone initialization is actually done by the C2CallPhone. Calling this method manually is not recommended.

Declared In

SIPPhone.h

isBackgroundCall

Is BackgroundCall running

- (BOOL)isBackgroundCall

Return Value

YES/NO

Discussion

Indicates whether during background start whether the App has been woken up for a call.

Declared In

SIPPhone.h

isOnline

Current online / connection status.

- (BOOL)isOnline

Return Value

YES - online/connected / NO - offline / disconnected

Declared In

SIPPhone.h

isUDPTunnelActive

Is UDPTunnel over TCP active

- (BOOL)isUDPTunnelActive

Return Value

YES - Connection via TCP / NO - Connection via UDP

Discussion

In case the firewall is blocking UDP data packet, the client automatically establish a UDP Tunnel over TCP port 80. This will cause additional delay on the connection, but will get at least through the firewall in most cases.

Declared In

SIPPhone.h

isValidNumber:

Check whether the given number is a valid phone number

- (BOOL)isValidNumber:(id)number

Return Value

YES / NO

Declared In

SIPPhone.h

messageBodyFromEvent:

Extract the message body from event data

- (NSString *)messageBodyFromEvent:(id)data

Parameters

data

Return Value

message body if available or nil

Declared In

SIPPhone.h

normalizeNumber:

Convert a local number into international number format

- (NSString *)normalizeNumber:(id)number

Parameters

number
  • Local number (e.g. (408) 123456)

Return Value

international number (e.g. +1408123456)

Discussion

Based on the vailable information from country and local area, local numbers will be converted into internaltional number format starting with +

Declared In

SIPPhone.h

rejectCall

Reject an incoming call.

- (void)rejectCall

Declared In

SIPPhone.h

remoteDisplayname

Remotes party display name.

- (NSString *)remoteDisplayname

Return Value

Remote party display name

Declared In

SIPPhone.h

remoteParty

Remotes party userid or phone number of an incoming or established call.

- (NSString *)remoteParty

Return Value

Remote party userid or phone number

Declared In

SIPPhone.h

sendDTMFTone:withInterval:

Sends a DTMF Tone to the remote party.

- (void)sendDTMFTone:(id)tone withInterval:(id)durationInMS

Parameters

tone
  • The DTMF tone (Allowed values : 0 - 11)
durationInMS
  • Duration of the DTMF Tone (typically 200ms)

Discussion

Sometimes IVRs / answer maschines require DTMF tones to select menu options during a call. Supported DTMF tones are : 0 - 9, ‘*’ = 10, ‘#’ = 11

Declared In

SIPPhone.h

setAffiliateId:

Sets the AffiliateId.

- (void)setAffiliateId:(id)affiliateId

Parameters

affiliateId
  • AffiliateId

Discussion

Calling this method manually is not recommended.

Declared In

SIPPhone.h

setApplicationSessionId:

Sets the Application SessionId.

- (void)setApplicationSessionId:(id)sid

Parameters

sid
  • Application SessionId

Discussion

Calling this method manually is not recommended.

Declared In

SIPPhone.h

startSIPPhone

Starts the SIPPhone.

- (void)startSIPPhone

Discussion

Calling this method manually is not recommended.

Declared In

SIPPhone.h

startToneEvent:

Sends a DTMF Tone to the remote party.

- (void)startToneEvent:(id)event

Parameters

tone
  • The DTMF tone (Allowed values : 0 - 11)
durationInMS
  • Duration of the DTMF Tone (typically 200ms)

Discussion

Sometimes IVRs / answer maschines require DTMF tones to select menu options during a call. Supported DTMF tones are : 0 - 9, ‘*’ = 10, ‘#’ = 11 The duration of the tone event call be defined by the length of the key press. (Start on key down / End on key up)

Declared In

SIPPhone.h

stopSIPPhone

Stops the SIPPhone.

- (void)stopSIPPhone

Discussion

Calling this method manually is not recommended.

Declared In

SIPPhone.h

submitEvent:withMessage:toUser:

Submitting an Event Message.

- (void)submitEvent:(id)event withMessage:(id)msg toUser:(id)userid

Parameters

event
  • The event name, SCEVNT_ plus just 7 Bit ASCII characters no blanks
userid
message
  • The message

Discussion

An Event Message is supposed to be an internal notification from app to app to submit status information or other information which shouldn’t be displayed to the user directly.

Every event name has to start with prefix “SCEVNT_” otherwise it will not be handled

On the receiver side, the event can be handled by overwriting C2CallAppDelegate method as follows:

-(void) notifySIPEvent:(NSString *)event andData:(id)data
{
    [super notifySIPEvent:event andData:data];

    if ([event isEqualToString:@"SCEVNT_MYEVENT"]) {
        NSString *message = [[SIPPhone currentPhone] messageBodyFromEvent:data];
        NSString *userid = [[SIPPhone currentPhone] useridFromEvent:data];
        NSString *displayName = [[SIPPhone currentPhone] displayNameFromEvent:data];
        NSLog(@"SCEVNT_MYEVENT : %@ <%@> : %@", displayName, userid, message);
    }

}

Declared In

SIPPhone.h

submitMessage:toNumber:

Submits an SMS/Text message.

- (void)submitMessage:(id)message toNumber:(id)number

Parameters

message
  • The message
number
  • Receiver number in international format

Discussion

Sending an SMS/Text message will be charged to the user credit according to our pricelist. SMS/Text messages are 160 characters or 70 2-Byte characters. Longer messages will be automatically split into multiple SMS and charged accordingly. In of mixing 1-Byte character and 2-Bytes character in a message, you have only 70 characters per messages even it contains only one 2-Byte character. Sending SMS/Text messages into the USA requires a C2Call DID-Number.

[[SIPPhone currentPhone] submitMessage:@“This is a message” toNumber:@“+14081234567”];

The number should typically start with the + and the international country code, followed by the area code without leading “0” and then the number (e.g. +14081234567). If the submitted number is not in international format, the function automatically tries to convert the number into international format automatically, based on the users country settings. To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

submitMessage:toUser:

Submits an instant message.

- (void)submitMessage:(id)message toUser:(id)target

Parameters

message
  • The message
target
  • C2Call Userid or email address

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. An instant message will be either delivered via SIP message to the receiver while the app is in foreground or via Push Notification while the app is in background.

[[SIPPhone currentPhone] submitMessage:@“This is a message” toUser:@“max.muster@registeredemail.com”];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

submitMessage:toUser:preferEncryption:

Submits an instant message.

- (void)submitMessage:(id)message toUser:(id)target preferEncryption:(id)encrypted

Parameters

message
  • The message
target
  • C2Call Userid or email address
encrypted
  • If set to YES, the message will be encrypted with the Public Key of the remot user if available.

Discussion

Every C2Call user can be addressed by his email address or his C2Call UserId. An instant message will be either delivered via SIP message to the receiver while the app is in foreground or via Push Notification while the app is in background.

[[SIPPhone currentPhone] submitMessage:@“This is a message” toUser:@“max.muster@registeredemail.com” preferEncryption:NO];

To access user data, please see also SCDataManager class.

Declared In

SIPPhone.h

submitTypingEventToUser:

Submitting a isTyping Event to target userid.

- (void)submitTypingEventToUser:(id)userid

Parameters

userid

Discussion

This event will be fired by SCChatController if the user is typing. The event should only be fired every 2 seconds while a user is typing

Declared In

SIPPhone.h

takeCall:

Accepts an incoming call.

- (void)takeCall:(id)useVideo

Parameters

useVideo
  • Allow video for this call

Declared In

SIPPhone.h

useridFromEvent:

Extract the userid from event data

- (NSString *)useridFromEvent:(id)data

Parameters

data

Return Value

userid if available or nil

Declared In

SIPPhone.h

willEnterForeground

Handles the Application Status willEnterForeground.

- (void)willEnterForeground

Discussion

The actual SIPPhone willEnterForeground is handled automatically by C2CallPhone. Calling this method manually is not recommended.

Declared In

SIPPhone.h

willResignActive

Handles the Application Status willResignActive.

- (void)willResignActive

Discussion

The actual SIPPhone willResignActive is handled automatically by C2CallPhone. Calling this method manually is not recommended.

Declared In

SIPPhone.h

willTerminate

Handles the Application Status willTerminate.

- (void)willTerminate

Discussion

The actual SIPPhone willTerminate is handled automatically by C2CallPhone. It’s not recommended to call this method manually.

Declared In

SIPPhone.h