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.

---

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.

---

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.

---

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.

---

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.

---

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.

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 retrieved 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 the return value is nil, the connection could not be initialized.

Discussion

Create an outgoing connection.

---

disconnectAll

Disconnect all current connections associated with the receiver.

- (void)disconnectAll

Discussion

Disconnect all current connections associated with the receiver.

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

---

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.

See Also

– updateCapabilityToken:

---

listen

Start TCDevice to listen for incoming connections.

- (void)listen

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.

---

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

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.

---

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.

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.