Get Started

TCDevice Class Reference

Overview

An instance of TCDevice is an object that knows how to interface with Twilio Services.

A TCDevice is the primary entry point for Twilio Client. An iOS application should initialize a TCDevice with the initWithCapabilityToken:delegate: method with a Capability Token to talk to Twilio services.

A Capability Token is a JSON Web Token (JWT) that specifies what the TCDevice may do with respect to the Twilio Application, such as whether it can make outgoing calls, how long the token and the TCDevice are valid before needing to be refreshed, and so on. Please visit http://www.twilio.com/docs/client/capability-tokens for more information.

Tasks

Selector Description Type
  state

Current status of the TCDevice.

Property
  capabilities

Current capabilities of the TCDevice. The keys are defined by the “Device capability keys” constants.

Property
  delegate

The delegate object which will receive events from a TCDevice object.

Property
  incomingSoundEnabled

A BOOL indicating if a sound should be played for an incoming connection.

Property
  outgoingSoundEnabled

A BOOL indicating if a sound should be played for an outgoing connection.

Property
  disconnectSoundEnabled

A BOOL indicating if a sound should be played when a connection is disconnected for any reason.

Property
– initWithCapabilityToken:delegate:

Initialize a new TCDevice object. If the incoming capabilities are defined, then the device will automatically begin listening for incoming connections.

Instance Method
– listen

Start TCDevice to listen for incoming connections.

Instance Method
– unlisten

Stop the device from listening for incoming connections. This could be used for a “silence” mode on the your iOS application, for instance.

Instance Method
– updateCapabilityToken:

Update the capabilities of the TCDevice.

Instance Method
– connect:delegate:

Create an outgoing connection.

Instance Method
– disconnectAll

Disconnect all current connections associated with the receiver.

Instance Method

Properties

capabilities

Current capabilities of the TCDevice. The keys are defined by the “Device capability keys” constants.

@property (nonatomic, readonly) NSDictionary *capabilities
Discussion

Current capabilities of the TCDevice. The keys are defined by the “Device capability keys” constants.

Declared In
TCDevice.h

delegate

The delegate object which will receive events from a TCDevice object.

@property (nonatomic, assign) id<TCDeviceDelegate> delegate
Discussion

The delegate object which will receive events from a TCDevice object.

Declared In
TCDevice.h

disconnectSoundEnabled

A BOOL indicating if a sound should be played when a connection is disconnected for any reason.

@property (nonatomic) BOOL disconnectSoundEnabled
Discussion

A BOOL indicating if a sound should be played when a connection is disconnected for any reason.

The default value is YES. See the Twilio Client iOS Usage Guide for more information on sounds.

Declared In
TCDevice.h

incomingSoundEnabled

A BOOL indicating if a sound should be played for an incoming connection.

@property (nonatomic) BOOL incomingSoundEnabled
Discussion

A BOOL indicating if a sound should be played for an incoming connection.

The default value is YES. See the Twilio Client iOS Usage Guide for more information on sounds.

Declared In
TCDevice.h

outgoingSoundEnabled

A BOOL indicating if a sound should be played for an outgoing connection.

@property (nonatomic) BOOL outgoingSoundEnabled
Discussion

A BOOL indicating if a sound should be played for an outgoing connection.

The default value is YES. See the Twilio Client iOS Usage Guide for more information on sounds.

Declared In
TCDevice.h

state

Current status of the TCDevice.

@property (nonatomic, readonly) TCDeviceState state
Discussion

Current status of the TCDevice.

State changes will cause relevant methods to be called in TCDeviceDelegate and will include any NSErrors that occur.

Declared In
TCDevice.h

Instance Methods

connect:delegate:

Create an outgoing connection.

- (TCConnection *)connect:(NSDictionary *)parameters delegate:(id<TCConnectionDelegate>)delegate
Parameters
Name Description
parameters

An optional dictionary containing parameters for the outgoing connection that get passed to your Twilio Application. These parameters are merged with any parameters supplied in the Capability Token (e.g. the dictionary retrived with the TCDeviceCapabilityApplicationParametersKey against the capabilities property). If there are any key collisions with the two dictionaries, the value(s) from TCDeviceCapabilityApplicationParametersKey dictionary will take precedence.

delegate

An optional delegate object to receive callbacks when state changes occur to the TCConnection object.

Return Value

A TCConnection object representing the new outgoing connection. If TCConnection is nil, the connection could not be initialized.

Discussion

Create an outgoing connection.

Declared In
TCDevice.h

disconnectAll

Disconnect all current connections associated with the receiver.

- (void)disconnectAll
Return Value

None

Discussion

Disconnect all current connections associated with the receiver.

This a convenience routine that disconnects all current incoming and outgoing connections.

Declared In
TCDevice.h

initWithCapabilityToken:delegate:

Initialize a new TCDevice object. If the incoming capabilities are defined, then the device will automatically begin listening for incoming connections.

- (id)initWithCapabilityToken:(NSString *)capabilityToken delegate:(id<TCDeviceDelegate>)delegate
Parameters
Name Description
capabilityToken

A signed JSON Web Token that defines the features available to the TCDevice. These may be created using the Twilio Helper Libraries included with the SDK or available at http://www.twilio.com . The capabilities are used to begin listening for incoming connections and provide the default parameters used for establishing outgoing connections. Please visit http://www.twilio.com/docs/client/capability-tokens for more information.

delegate

The delegate object which will receive events from a TCDevice object.

Return Value

The initialized receiver

Discussion

Initialize a new TCDevice object. If the incoming capabilities are defined, then the device will automatically begin listening for incoming connections.

Declared In
TCDevice.h

listen

Start TCDevice to listen for incoming connections.

- (void)listen
Return Value

None

Discussion

Start TCDevice to listen for incoming connections.

The TCDevice will automatically listen for incoming connections on method calls to initWithCapabilityToken:delegate: or updateCapabilityToken: if the token allows.

This method only needs to be called if unlisten was previously called.

Declared In
TCDevice.h

unlisten

Stop the device from listening for incoming connections. This could be used for a “silence” mode on the your iOS application, for instance.

- (void)unlisten
Return Value

None

Discussion

Stop the device from listening for incoming connections. This could be used for a “silence” mode on the your iOS application, for instance.

This method will do nothing if the TCDevice is currently not listening, either because of a previous call to unlisten or because the TCDevice has not been granted the incoming capability.

Declared In
TCDevice.h

updateCapabilityToken:

Update the capabilities of the TCDevice.

- (void)updateCapabilityToken:(NSString *)capabilityToken
Parameters
Name Description
capabilityToken

A signed JWT that defines the capability token available to the TCDevice. Please visit http://www.twilio.com/docs/client/capability-tokens for more information on capability tokens.

Return Value

None

Discussion

Update the capabilities of the TCDevice.

There may be circumstances when the defined capabilities have expired. For example, the TCDevice may enter the TCDeviceIncomingStateOffline states because the capabilities have expired. In these cases, the capabilities will need to be updated. If the device is currently listening for incoming connection, it will restart the listening process (if permitted) using these updated capabilities.

Declared In
TCDevice.h