com.digium.respokesdk

Class RespokeClient

java.lang.Object

com.digium.respokesdk.RespokeClient

All Implemented Interfaces:

RespokeSignalingChannel.Listener

public class RespokeClient
extends java.lang.Object
implements RespokeSignalingChannel.Listener

This is a top-level interface to the API. It handles authenticating the app to the API server, receiving server-side app-specific information, keeping track of connection status and presence, accepting callbacks and listeners, and interacting with information the library keeps track of, like groups and endpoints. The client also keeps track of default settings for calls and direct connections as well as automatically reconnecting to the service when network activity is lost.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	RespokeClient.ConnectCompletionListener A listener interface to receive a notification that the connect action has failed
static interface	RespokeClient.GroupHistoriesCompletionListener A listener interface to receive a notification when the request to retrieve the history of messages for a list of groups has completed
static interface	RespokeClient.GroupHistoryCompletionListener A listener interface to receive a notification when the request to retrieve the history of messages for a specific group has completed
static interface	RespokeClient.JoinGroupCompletionListener A listener interface to receive a notification that the task to join the groups has completed
static interface	RespokeClient.Listener A listener interface to notify the receiver of events occurring with the client
static interface	RespokeClient.ResolvePresenceListener A listener interface to ask the receiver to resolve a list of presence values for an endpoint

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	baseURL
static java.lang.String	PROPERTY_LAST_VALID_PUSH_TOKEN
static java.lang.String	PROPERTY_LAST_VALID_PUSH_TOKEN_ID

Constructor Summary

Constructors

Constructor and Description
RespokeClient() The constructor for this class

Method Summary

Modifier and Type	Method and Description
void	callCreated(RespokeCall call) Receive a notification from the signaling channel that a call has been created
void	callTerminated(RespokeCall call) Receive a notification from the signaling channel that a call has terminated
RespokeCall	callWithID(java.lang.String sessionID) Find a call with the specified session ID
void	connect(java.lang.String tokenID, java.lang.Object initialPresence, android.content.Context context, RespokeClient.ConnectCompletionListener completionListener) Connect to the Respoke infrastructure and authenticate with the specified brokered auth token ID.
void	connect(java.lang.String endpointID, java.lang.String appID, boolean shouldReconnect, java.lang.Object initialPresence, android.content.Context context, RespokeClient.ConnectCompletionListener completionListener) Connect to the Respoke infrastructure and authenticate in development mode using the specified endpoint ID and app ID.
void	directConnectionAvailable(RespokeDirectConnection directConnection, RespokeEndpoint endpoint) This event is fired when the logged-in endpoint is receiving a request to open a direct connection to another endpoint.
void	disconnect() Disconnect from the Respoke infrastructure, leave all groups, invalidate the token, and disconnect the websocket.
RespokeConnection	getConnection(java.lang.String connectionID, java.lang.String endpointID, boolean skipCreate) Find a Connection by id and return it.
RespokeEndpoint	getEndpoint(java.lang.String endpointIDToFind, boolean skipCreate) Find an endpoint by id and return it.
java.lang.String	getEndpointID() Return the Endpoint ID of this client
RespokeGroup	getGroup(java.lang.String groupIDToFind) Returns the group with the specified ID
void	getGroupHistories(java.util.List<java.lang.String> groupIds, java.lang.Integer maxMessages, RespokeClient.GroupHistoriesCompletionListener completionListener) Retrieve the history of messages that have been persisted for 1 or more groups.
void	getGroupHistories(java.util.List<java.lang.String> groupIds, RespokeClient.GroupHistoriesCompletionListener completionListener) Retrieve the history of messages that have been persisted for 1 or more groups.
void	getGroupHistory(java.lang.String groupId, java.lang.Integer maxMessages, java.util.Date before, RespokeClient.GroupHistoryCompletionListener completionListener) Retrieve the history of messages that have been persisted for a specific group.
void	getGroupHistory(java.lang.String groupId, java.lang.Integer maxMessages, RespokeClient.GroupHistoryCompletionListener completionListener) Retrieve the history of messages that have been persisted for a specific group.
void	getGroupHistory(java.lang.String groupId, RespokeClient.GroupHistoryCompletionListener completionListener) Retrieve the history of messages that have been persisted for a specific group.
java.lang.Object	getPresence() Get the current presence of this client
RespokeClient.ResolvePresenceListener	getResolvePresenceListener() Get the current receiver for the ResolvePresenceListener interface
boolean	isConnected() Check whether this client is connected to the backend infrastructure.
RespokeCall	joinConference(RespokeCall.Listener callListener, android.content.Context context, java.lang.String conferenceID) Initiate a call to a conference.
void	joinGroups(java.util.ArrayList<java.lang.String> groupIDList, RespokeClient.JoinGroupCompletionListener completionListener) Join a list of Groups and begin keeping track of them.
void	onConnect(RespokeSignalingChannel sender, java.lang.String endpointID, java.lang.String connectionID) Receive a notification from the signaling channel that it has connected to the cloud infrastructure
void	onDisconnect(RespokeSignalingChannel sender) Receive a notification from the signaling channel that it has disconnected to the cloud infrastructure
void	onError(java.lang.String errorMessage, RespokeSignalingChannel sender) Receive a notification from the signaling channel that an error has occurred
void	onGroupMessage(java.lang.String message, java.lang.String groupID, java.lang.String endpointID, RespokeSignalingChannel sender, java.util.Date timestamp) Receive a notification that a group message was received
void	onIncomingCall(org.json.JSONObject sdp, java.lang.String sessionID, java.lang.String connectionID, java.lang.String endpointID, java.lang.String fromType, java.util.Date timestamp, RespokeSignalingChannel sender) Receive a notification from the signaling channel that a remote endpoint is attempting to start a call
void	onIncomingDirectConnection(org.json.JSONObject sdp, java.lang.String sessionID, java.lang.String connectionID, java.lang.String endpointID, java.util.Date timestamp, RespokeSignalingChannel sender) Receive a notification from the signaling channel that a remote endpoint is attempting to start a direct connection
void	onJoinGroup(java.lang.String groupID, java.lang.String endpointID, java.lang.String connectionID, RespokeSignalingChannel sender) Receive a notification from the signaling channel that an endpoint has joined this group.
void	onLeaveGroup(java.lang.String groupID, java.lang.String endpointID, java.lang.String connectionID, RespokeSignalingChannel sender) Receive a notification from the signaling channel that an endpoint has left this group.
void	onMessage(java.lang.String message, java.util.Date timestamp, java.lang.String fromEndpointID, java.lang.String toEndpointID, RespokeSignalingChannel sender) Receive a notification from the signaling channel that a message has been sent to this group
void	onPresence(java.lang.Object presence, java.lang.String connectionID, java.lang.String endpointID, RespokeSignalingChannel sender) Receive a notification that a presence change message was received
void	registerPushServicesWithToken(java.lang.String token) Register the client to receive push notifications when the socket is not active
void	setListener(RespokeClient.Listener listener) Set a receiver for the Listener interface
void	setPresence(java.lang.Object newPresence, Respoke.TaskCompletionListener completionListener) Set the presence on the client session
void	setResolvePresenceListener(RespokeClient.ResolvePresenceListener listener) Set a receiver for the ResolvePresenceListener interface
void	unregisterFromPushServices(Respoke.TaskCompletionListener completionListener) Unregister this client from the push service so that no more notifications will be received for this endpoint ID

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_LAST_VALID_PUSH_TOKEN

public static final java.lang.String PROPERTY_LAST_VALID_PUSH_TOKEN

See Also:

Constant Field Values

PROPERTY_LAST_VALID_PUSH_TOKEN_ID

public static final java.lang.String PROPERTY_LAST_VALID_PUSH_TOKEN_ID

See Also:

Constant Field Values

baseURL

public java.lang.String baseURL

Constructor Detail

RespokeClient

public RespokeClient()

The constructor for this class

Method Detail

setListener

public void setListener(RespokeClient.Listener listener)

Set a receiver for the Listener interface

Parameters:

listener - The new receiver for events from the Listener interface for this client instance

setResolvePresenceListener

public void setResolvePresenceListener(RespokeClient.ResolvePresenceListener listener)

Set a receiver for the ResolvePresenceListener interface

Parameters:

listener - The new receiver for events from the ResolvePresenceListener interface for this client instance

getResolvePresenceListener

public RespokeClient.ResolvePresenceListener getResolvePresenceListener()

Get the current receiver for the ResolvePresenceListener interface

Returns:

The current receiver for the ResolvePresenceListener interface

connect

public void connect(java.lang.String endpointID,
                    java.lang.String appID,
                    boolean shouldReconnect,
                    java.lang.Object initialPresence,
                    android.content.Context context,
                    RespokeClient.ConnectCompletionListener completionListener)

Connect to the Respoke infrastructure and authenticate in development mode using the specified endpoint ID and app ID. Attempt to obtain an authentication token automatically from the Respoke infrastructure.

Parameters:

endpointID - The endpoint ID to use when connecting

appID - Your Application ID

shouldReconnect - Whether or not to automatically reconnect to the Respoke service when a disconnect occurs.

initialPresence - The optional initial presence value to set for this client

context - An application context with which to access system resources

completionListener - A listener to be called when an error occurs, passing a string describing the error

connect

public void connect(java.lang.String tokenID,
                    java.lang.Object initialPresence,
                    android.content.Context context,
                    RespokeClient.ConnectCompletionListener completionListener)

Connect to the Respoke infrastructure and authenticate with the specified brokered auth token ID.

Parameters:

tokenID - The token ID to use when connecting

initialPresence - The optional initial presence value to set for this client

context - An application context with which to access system resources

completionListener - A listener to be called when an error occurs, passing a string describing the error

disconnect

public void disconnect()

Disconnect from the Respoke infrastructure, leave all groups, invalidate the token, and disconnect the websocket.

isConnected

public boolean isConnected()

Check whether this client is connected to the backend infrastructure.

Returns:

True if connected

joinGroups

public void joinGroups(java.util.ArrayList<java.lang.String> groupIDList,
                       RespokeClient.JoinGroupCompletionListener completionListener)

Join a list of Groups and begin keeping track of them.

Parameters:

groupIDList - An array of IDs of the groups to join

completionListener - A listener to receive a notification of the success or failure of the asynchronous operation

getConnection

public RespokeConnection getConnection(java.lang.String connectionID,
                                       java.lang.String endpointID,
                                       boolean skipCreate)

Find a Connection by id and return it. In most cases, if we don't find it we will create it. This is useful in the case of dynamic endpoints where groups are not in use. Set skipCreate=true to return null if the Connection is not already known.

Parameters:

connectionID - The ID of the connection to return

endpointID - The ID of the endpoint to which this connection belongs

skipCreate - If true, return null if the connection is not already known

Returns:

The connection whose ID was specified

joinConference

public RespokeCall joinConference(RespokeCall.Listener callListener,
                                  android.content.Context context,
                                  java.lang.String conferenceID)

Initiate a call to a conference.

Parameters:

callListener - A listener to receive notifications about the new call

context - An application context with which to access system resources

conferenceID - The ID of the conference to call

Returns:

A reference to the new RespokeCall object representing this call

getEndpoint

public RespokeEndpoint getEndpoint(java.lang.String endpointIDToFind,
                                   boolean skipCreate)

Find an endpoint by id and return it. In most cases, if we don't find it we will create it. This is useful in the case of dynamic endpoints where groups are not in use. Set skipCreate=true to return null if the Endpoint is not already known.

Parameters:

endpointIDToFind - The ID of the endpoint to return

skipCreate - If true, return null if the connection is not already known

Returns:

The endpoint whose ID was specified

getGroup

public RespokeGroup getGroup(java.lang.String groupIDToFind)

Returns the group with the specified ID

Parameters:

groupIDToFind - The ID of the group to find

Returns:

The group with specified ID, or null if it was not found

getGroupHistories

public void getGroupHistories(java.util.List<java.lang.String> groupIds,
                              RespokeClient.GroupHistoriesCompletionListener completionListener)

Retrieve the history of messages that have been persisted for 1 or more groups. Only those messages that have been marked to be persisted when sent will show up in the history. Only the most recent message in each group will be retrieved - to pull more messages, use the other method signature that allows `maxMessages` to be specified.

Parameters:

groupIds - The groups to pull history for

completionListener - The callback called when this async operation has completed

getGroupHistories

public void getGroupHistories(java.util.List<java.lang.String> groupIds,
                              java.lang.Integer maxMessages,
                              RespokeClient.GroupHistoriesCompletionListener completionListener)

Retrieve the history of messages that have been persisted for 1 or more groups. Only those messages that have been marked to be persisted when sent will show up in the history.

Parameters:

groupIds - The groups to pull history for

maxMessages - The maximum number of messages per group to pull. Must be >= 1

completionListener - The callback called when this async operation has completed

getGroupHistory

public void getGroupHistory(java.lang.String groupId,
                            RespokeClient.GroupHistoryCompletionListener completionListener)

Retrieve the history of messages that have been persisted for a specific group. Only those messages that have been marked to be persisted when sent will show up in the history. Only the 50 most recent messages in each group will be retrieved - to change the maximum number of messages pulled, use the other method signature that allows `maxMessages` to be specified. To retrieve messages further back in the history than right now, use the other method signature that allows `before` to be specified.

Parameters:

groupId - The groups to pull history for

completionListener - The callback called when this async operation has completed

getGroupHistory

public void getGroupHistory(java.lang.String groupId,
                            java.lang.Integer maxMessages,
                            RespokeClient.GroupHistoryCompletionListener completionListener)

Retrieve the history of messages that have been persisted for a specific group. Only those messages that have been marked to be persisted when sent will show up in the history. To retrieve messages further back in the history than right now, use the other method signature that allows `before` to be specified.

Parameters:

groupId - The groups to pull history for

maxMessages - The maximum number of messages per group to pull. Must be >= 1

completionListener - The callback called when this async operation has completed

getGroupHistory

public void getGroupHistory(java.lang.String groupId,
                            java.lang.Integer maxMessages,
                            java.util.Date before,
                            RespokeClient.GroupHistoryCompletionListener completionListener)

Retrieve the history of messages that have been persisted for a specific group. Only those messages that have been marked to be persisted when sent will show up in the history.

Parameters:

groupId - The groups to pull history for

maxMessages - The maximum number of messages per group to pull. Must be >= 1

before - Limit messages to those with a timestamp before this value

completionListener - The callback called when this async operation has completed

getEndpointID

public java.lang.String getEndpointID()

Return the Endpoint ID of this client

Returns:

The Endpoint ID of this client

setPresence

public void setPresence(java.lang.Object newPresence,
                        Respoke.TaskCompletionListener completionListener)

Set the presence on the client session

Parameters:

newPresence - The new presence to use

completionListener - A listener to receive the notification on the success or failure of the asynchronous operation

getPresence

public java.lang.Object getPresence()

Get the current presence of this client

Returns:

The current presence value

registerPushServicesWithToken

public void registerPushServicesWithToken(java.lang.String token)

Register the client to receive push notifications when the socket is not active

Parameters:

token - The GCMS token to register

unregisterFromPushServices

public void unregisterFromPushServices(Respoke.TaskCompletionListener completionListener)

Unregister this client from the push service so that no more notifications will be received for this endpoint ID

Parameters:

completionListener - A listener to receive the notification on the success or failure of the asynchronous operation

onConnect

public void onConnect(RespokeSignalingChannel sender,
                      java.lang.String endpointID,
                      java.lang.String connectionID)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that it has connected to the cloud infrastructure

Specified by:

onConnect in interface RespokeSignalingChannel.Listener

Parameters:

sender - The signaling channel that triggered the event

endpointID - The endpointID for this connection, as reported by the server

connectionID - The connectionID for this connection.

onDisconnect

public void onDisconnect(RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that it has disconnected to the cloud infrastructure

Specified by:

onDisconnect in interface RespokeSignalingChannel.Listener

Parameters:

sender - The signaling channel that triggered the event

onIncomingCall

public void onIncomingCall(org.json.JSONObject sdp,
                           java.lang.String sessionID,
                           java.lang.String connectionID,
                           java.lang.String endpointID,
                           java.lang.String fromType,
                           java.util.Date timestamp,
                           RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that a remote endpoint is attempting to start a call

Specified by:

onIncomingCall in interface RespokeSignalingChannel.Listener

Parameters:

sdp - The SDP data for the call

sessionID - The session ID of the call

connectionID - The connectionID that is calling

endpointID - The endpointID that is calling

fromType - Type of the message source.

timestamp - The timestamp when the call was initiated

sender - The signaling channel that triggered the event

onIncomingDirectConnection

public void onIncomingDirectConnection(org.json.JSONObject sdp,
                                       java.lang.String sessionID,
                                       java.lang.String connectionID,
                                       java.lang.String endpointID,
                                       java.util.Date timestamp,
                                       RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that a remote endpoint is attempting to start a direct connection

Specified by:

onIncomingDirectConnection in interface RespokeSignalingChannel.Listener

Parameters:

sdp - The SDP data for the directConnection

sessionID - The session ID of the directConnection

connectionID - The connectionID that is calling

endpointID - The endpointID that is calling

timestamp - The timestamp when the call was initiated

sender - The signaling channel that triggered the event

onError

public void onError(java.lang.String errorMessage,
                    RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that an error has occurred

Specified by:

onError in interface RespokeSignalingChannel.Listener

Parameters:

errorMessage - Error message

sender - The signaling channel that triggered the event

onJoinGroup

public void onJoinGroup(java.lang.String groupID,
                        java.lang.String endpointID,
                        java.lang.String connectionID,
                        RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that an endpoint has joined this group.

Specified by:

onJoinGroup in interface RespokeSignalingChannel.Listener

Parameters:

groupID - The ID of the group triggering the join message

endpointID - The ID of the endpoint that to which the connection belongs

connectionID - The ID of the connection that has joined the group

sender - The signaling channel that triggered the event

onLeaveGroup

public void onLeaveGroup(java.lang.String groupID,
                         java.lang.String endpointID,
                         java.lang.String connectionID,
                         RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that an endpoint has left this group.

Specified by:

onLeaveGroup in interface RespokeSignalingChannel.Listener

Parameters:

groupID - The ID of the group triggering the leave message

endpointID - The ID of the endpoint that to which the connection belongs

connectionID - The ID of the connection that has left the group

sender - The signaling channel that triggered the event

onMessage

public void onMessage(java.lang.String message,
                      java.util.Date timestamp,
                      java.lang.String fromEndpointID,
                      java.lang.String toEndpointID,
                      RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that a message has been sent to this group

Specified by:

onMessage in interface RespokeSignalingChannel.Listener

Parameters:

message - The body of the message

timestamp - The timestamp of the message

fromEndpointID - The ID of the endpoint sending the message

toEndpointID - The ID of the original recipient of the message if being cc'd to self, otherwise null

sender - The signaling channel that triggered the event

onGroupMessage

public void onGroupMessage(java.lang.String message,
                           java.lang.String groupID,
                           java.lang.String endpointID,
                           RespokeSignalingChannel sender,
                           java.util.Date timestamp)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification that a group message was received

Specified by:

onGroupMessage in interface RespokeSignalingChannel.Listener

Parameters:

message - The body of the message

groupID - The ID of the group to which the message was sent

endpointID - The ID of the endpoint that sent the message

sender - The signaling channel that triggered the event

timestamp - The time at which the message was sent

onPresence

public void onPresence(java.lang.Object presence,
                       java.lang.String connectionID,
                       java.lang.String endpointID,
                       RespokeSignalingChannel sender)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification that a presence change message was received

Specified by:

onPresence in interface RespokeSignalingChannel.Listener

Parameters:

presence - The new presence value

connectionID - The connection ID whose presence changed

endpointID - The endpoint ID to which the connection belongs

sender - The signaling channel that triggered the event

callCreated

public void callCreated(RespokeCall call)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that a call has been created

Specified by:

callCreated in interface RespokeSignalingChannel.Listener

Parameters:

call - The RespokeCall instance that was created

callTerminated

public void callTerminated(RespokeCall call)

Description copied from interface: RespokeSignalingChannel.Listener

Receive a notification from the signaling channel that a call has terminated

Specified by:

callTerminated in interface RespokeSignalingChannel.Listener

Parameters:

call - The RespokeCall instance that was terminated

callWithID

public RespokeCall callWithID(java.lang.String sessionID)

Description copied from interface: RespokeSignalingChannel.Listener

Find a call with the specified session ID

Specified by:

callWithID in interface RespokeSignalingChannel.Listener

Parameters:

sessionID - SessionID to find

Returns:

The RespokeCall instance with that sessionID. If not found, will return nil.

directConnectionAvailable

public void directConnectionAvailable(RespokeDirectConnection directConnection,
                                      RespokeEndpoint endpoint)

Description copied from interface: RespokeSignalingChannel.Listener

This event is fired when the logged-in endpoint is receiving a request to open a direct connection to another endpoint. If the user wishes to allow the direct connection, calling 'accept' on the direct connection will allow the connection to be set up.

Specified by:

directConnectionAvailable in interface RespokeSignalingChannel.Listener

Parameters:

directConnection - The direct connection object

endpoint - The remote endpoint