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 |
capabilities
Current 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.
delegate
The 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.
disconnectSoundEnabled
A 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.
incomingSoundEnabled
A 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.
outgoingSoundEnabled
A 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.
state
Current 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 NSError
s 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.
disconnectAll
Disconnect 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
listen
Start 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.
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
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.