Get Started

Device Class Reference

Overview

  • Package: com.twilio.client
  • Subclass of: Object
  • Implemented interfaces: Parcelable

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

A Device is the primary entry point for Twilio Client. An Android application should initialize a Device using the Twilio.createDevice() factory method with a Capability Token to talk to Twilio services.

A Capability Token is a JSON Web Token (JWT) that specifies what the Device may do with respect to the Twilio Application, such as whether it can make outgoing calls, how long the token and the Device are valid before needing to be refreshed, and so on.

Please visit http://www.twilio.com/docs/client/capability-tokens for more information.

Nested Classes

Tasks

Name Description Type
EXTRA_DEVICE Key into an Intent's extras data that points to a Device object. Field
EXTRA_CONNECTION Key into an Intent's extras data that points to a Connection object. Field
release Shuts down and releases the Device. Instance method
listen Start listening for incoming connections. Instance method
unlisten Stop listening for incoming connections. Instance method
getCapabilityToken Retrieves the capability token originally passed to Twilio.createDevice(). Instance method
updateCapabilityToken Updates the capabilities of the Device. Instance method
connect Creates a new connection to the Twilio application specified in the capability token of the Device. Instance method
disconnectAll Disconnects all current connections associated with this Device. Instance method
getCapabilities Current capabilities of the Device. Instance method
getState Retrieves the current state of the device. Instance method
setDeviceListener Sets a new DeviceListener object to respond to device events. Instance method
setIncomingIntent Sets a PendingIntent that will be sent when an incoming connection is received. Instance method
setIncomingSoundEnabled Set whether a sound should be played for an incoming connection. Instance method
isIncomingSoundEnabled Return whether a sound should be played for an incoming connection. Instance method
setOutgoingSoundEnabled Set whether a sound should be played for an outgoing connection. Instance method
isOutgoingSoundEnabled Return whether a sound should be played for an outgoing connection. Instance method
setDisconnectSoundEnabled Set whether a sound should be played when a connection is disconnected either normally or due to an error. Instance method
isDisconnectSoundEnabled Return whether a sound should be played when a connection is disconnected either normally or due to an error. Instance method

Fields

EXTRA_DEVICE

Key into an Intent's extras data that points to a Device object.

EXTRA_CONNECTION

Key into an Intent's extras data that points to a Connection object.

Methods

void release()

Shuts down and releases the Device.

Since you can't be certain of when the garbage collector will run, this will terminate all connections and release resources immediately.

Return Value

None


void listen()

Start listening for incoming connections.

The Device will automatically listen for incoming connections on calls to Twilio.createDevice() or .updateCapabilityToken() if the token allows.

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

Return Value

None


void unlisten()

Stop listening for incoming connections.

This could be used for a "silence" mode on the your Android application, for instance.

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

Return Value

None


String getCapabilityToken()

Retrieves the capability token originally passed to Twilio.createDevice().

Return Value

An opaque capability token string


void updateCapabilityToken(String inCapabilityToken)

Updates the capabilities of the Device.

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

Existing connections are not affected by updating the capability token.

Parameters
Name Description
inCapabilityToken The new capability token string.
Return Value

None


Connection connect(Map<> inParameters, ConnectionListener inListener)

Creates a new connection to the Twilio application specified in the capability token of the Device.

Parameters are passed to the application unmodified.

Parameters
Name Description
inParameters An optional Map 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. If there are any key collisions with the two Maps, the value(s) from the @{link Capability Map will take precedence.
inListener A ConnectionListener delegate object to respond to connection events
Return Value

A new Connection handle, or null if the connection could not be created


void disconnectAll()

Disconnects all current connections associated with this Device.

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

Return Value

None


Map<> getCapabilities()

Current capabilities of the Device.

The keys are defined by the Capability enum.

Return Value

A key/value mapping of capabilities

State getState()

Retrieves the current state of the device.

Return Value

The device state, as a State enum value


void setDeviceListener(DeviceListener inListener)

Sets a new DeviceListener object to respond to device events.

Parameters
Name Description
inListener A DeviceListener, or null
Return Value

None


void setIncomingIntent(PendingIntent inIntent)

Sets a PendingIntent that will be sent when an incoming connection is received.

The PendingIntent passed may be a reference to an Activity, Service, or BroadcastReceiver. When your component receives the intent, you should choose to accept, ignore, or reject the new connection.

When the Intent is received in your application, you can retrieve the Device and Connection objects related to the incoming connection by looking in the extras contained within the intent, using the keys Device and Device, which both implement the Parcelable interface.

When this occurs, you should assign an appropriate ConnectionListener on the Connection to properly respond to events.

Pending incoming connections may be received at any time, including while another connection is active. This intent will be invoked once for each connection, and your code should handle this situation appropriately. A single pending connection can be accepted as long as no other connections are active; all other currently pending incoming connections will be automatically rejected by the library until the active connection is terminated.

Parameters
Name Description
inIntent A PendingIntent to call when an incoming connecion is received
Return Value

None


void setIncomingSoundEnabled(boolean enabled)

Set whether a sound should be played for an incoming connection.

By default, .isIncomingSoundEnabled() is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Parameters
Name Description
enabled true to enable, false to disable
Return Value

None


boolean isIncomingSoundEnabled()

Return whether a sound should be played for an incoming connection.

The default value is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Return Value

None


void setOutgoingSoundEnabled(boolean enabled)

Set whether a sound should be played for an outgoing connection.

By default, .isOutgoingSoundEnabled() is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Parameters
Name Description
enabled true to enable, false to disable
Return Value

None


boolean isOutgoingSoundEnabled()

Return whether a sound should be played for an outgoing connection.

The default value is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Return Value

None


void setDisconnectSoundEnabled(boolean enabled)

Set whether a sound should be played when a connection is disconnected either normally or due to an error.

The disconnected sound will not be played if the connection is ignored or rejected.

By default, .isDisconnectSoundEnabled() is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Parameters
Name Description
enabled true to enable, false to disable

Return Value

None


boolean isDisconnectSoundEnabled()

Return whether a sound should be played when a connection is disconnected either normally or due to an error.

The disconnected sound will not be played if the connection is ignored or rejected.

The default value is true. See the Twilio Client Android Getting Started guide for more information on sounds.

Return Value

None