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.
| 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 |
capabilitiesCurrent capabilities of the TCDevice. The keys are defined by the “Device capability keys” constants.
@property (nonatomic, readonly) NSDictionary *capabilities
Current capabilities of the TCDevice. The keys are defined by the “Device capability keys” constants.
delegateThe delegate object which will receive events from a TCDevice object.
@property (nonatomic, assign) id<TCDeviceDelegate> delegate
The delegate object which will receive events from a TCDevice object.
disconnectSoundEnabledA BOOL indicating if a sound should be played when a connection is disconnected for any reason.
@property (nonatomic) BOOL disconnectSoundEnabled
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.
incomingSoundEnabledA BOOL indicating if a sound should be played for an incoming connection.
@property (nonatomic) BOOL incomingSoundEnabled
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.
outgoingSoundEnabledA BOOL indicating if a sound should be played for an outgoing connection.
@property (nonatomic) BOOL outgoingSoundEnabled
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.
stateCurrent status of the TCDevice.
@property (nonatomic, readonly) TCDeviceState state
Current status of the TCDevice.
State changes will cause relevant methods to be called in TCDeviceDelegate and will include any NSErrors that occur.
connect:delegate:Create an outgoing connection.
- (TCConnection *)connect:(NSDictionary *)parameters delegate:(id<TCConnectionDelegate>)delegate
| 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. |
A TCConnection object representing the new outgoing connection. If the return value is nil, the connection could not be initialized.
Create an outgoing connection.
disconnectAllDisconnect all current connections associated with the receiver.
- (void)disconnectAll
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
| 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. |
The initialized receiver.
Initialize a new TCDevice object. If the incoming capabilities are defined, then the device will automatically begin listening for incoming connections.
See Also
listenStart TCDevice to listen for incoming connections.
- (void)listen
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.
unlistenStop the device from listening for incoming connections. This could be used for a “silence” mode on the your iOS application, for instance.
- (void)unlisten
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
| 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. |
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.
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.