public final class Channel
extends java.lang.Object
implements android.os.Parcelable
To obtain a Channel call Channels.createChannel(java.lang.String, com.twilio.chat.Channel.ChannelType, com.twilio.chat.CallbackListener<com.twilio.chat.Channel>)
, Channels.getChannel(java.lang.String, com.twilio.chat.CallbackListener<com.twilio.chat.Channel>)
or
get it from collections returned by Channels#getPublicChannels
and
Channels#getUserChannels
.
Channel is a relatively heavy-weight object. It receives state updates from the back-end in real time.
Modifier and Type | Class and Description |
---|---|
static class |
Channel.ChannelStatus
This enum represents the various states of the member with respect to
this channel.
|
static class |
Channel.ChannelType
Enumeration indicating the channel's visibility.
|
static class |
Channel.SynchronizationStatus
Enumeration indicating synchronization status for channel.
|
static class |
Channel.UpdateReason |
Modifier and Type | Field and Description |
---|---|
static android.os.Parcelable.Creator<Channel> |
CREATOR
This is a
Parcelable -related method. |
Modifier and Type | Method and Description |
---|---|
void |
addListener(ChannelListener listener)
Add a new
ChannelListener for this Channel. |
void |
declineInvitation(StatusListener listener)
Decline an invite to this channel.
|
int |
describeContents()
This is a
Parcelable -related method. |
void |
destroy(StatusListener listener)
Destroy the current channel.
|
void |
dispose()
Dispose Channel object, freeing all allocated resources.
|
org.json.JSONObject |
getAttributes()
Get custom attributes associated with the Channel.
|
java.lang.String |
getCreatedBy()
Get creator of the channel.
|
java.lang.String |
getDateCreated()
Get creation date of the channel as
an ISO 8601 string.
|
java.util.Date |
getDateCreatedAsDate()
Get creation date of the channel.
|
java.lang.String |
getDateUpdated()
Get update date of the channel as
an ISO 8601 string.
|
java.util.Date |
getDateUpdatedAsDate()
Get update date of the channel.
|
java.lang.String |
getFriendlyName()
Get friendly name of the channel.
|
Members |
getMembers()
Get members object that allows access to members roster in the channel.
|
void |
getMembersCount(CallbackListener<java.lang.Long> listener)
Get total number of members in the channel roster.
|
Messages |
getMessages()
Get messages object that allows access to messages in the channel.
|
void |
getMessagesCount(CallbackListener<java.lang.Long> listener)
Get total number of messages in the channel.
|
java.lang.String |
getSid()
Get unique identifier for this channel.
|
Channel.ChannelStatus |
getStatus()
Get the current user's participation status on this channel.
|
Channel.SynchronizationStatus |
getSynchronizationStatus()
Get the current synchronization status for channel.
|
Channel.ChannelType |
getType()
Get channel type.
|
void |
getUnconsumedMessagesCount(CallbackListener<java.lang.Long> listener)
Get number of unconsumed messages in the channel.
|
java.lang.String |
getUniqueName()
Get unique name of the channel.
|
void |
join(StatusListener listener)
Join the current user to this channel.
|
void |
leave(StatusListener listener)
Leave this channel.
|
void |
removeAllListeners()
Remove all ChannelListeners for this Channel.
|
void |
removeListener(ChannelListener listener)
Remove ChannelListener for this Channel.
|
void |
setAttributes(org.json.JSONObject updatedAttributes,
StatusListener listener)
Update the attribute data for this channel.
|
void |
setFriendlyName(java.lang.String friendlyName,
StatusListener listener)
Update the friendly name for this channel.
|
void |
setType(Channel.ChannelType type,
StatusListener listener) |
void |
setUniqueName(java.lang.String uniqueName,
StatusListener listener)
Update the unique name for this channel.
|
void |
typing()
Indicate that Member is typing in this channel.
|
void |
writeToParcel(android.os.Parcel dest,
int flags)
This is a
Parcelable -related method. |
public static final android.os.Parcelable.Creator<Channel> CREATOR
Parcelable
-related method. You do not need to call it.public java.lang.String getSid()
This identifier can be used to get this Channel again using Channels.getChannel(java.lang.String, com.twilio.chat.CallbackListener<com.twilio.chat.Channel>)
.
The channel sid is persistent and globally unique.
public java.lang.String getFriendlyName()
Friendly name is a free-form text string, it is not unique and can be used for example in the UI.
setFriendlyName(java.lang.String, com.twilio.chat.StatusListener)
public void setFriendlyName(java.lang.String friendlyName, StatusListener listener)
friendlyName
- New friendly name.listener
- Listener that will receive callback with the result.getFriendlyName()
public Channel.ChannelType getType()
Channel.ChannelType
for more information.public void setType(Channel.ChannelType type, StatusListener listener)
public java.lang.String getUniqueName()
Unique name is similar to sid but can be specified by the user.
setUniqueName(java.lang.String, com.twilio.chat.StatusListener)
public void setUniqueName(java.lang.String uniqueName, StatusListener listener)
Unique name is unique within Service Instance. You will receive an error if you try to set a name that is not unique.
uniqueName
- New unique name for this channel.listener
- Listener that will receive callback with the result.getUniqueName()
public org.json.JSONObject getAttributes() throws org.json.JSONException
Attributes are stored as a JSON format object, of arbitrary internal structure. Channel attributes are limited in size to 32Kb.
org.json.JSONException
- Attributes could not be parsed as JSON.setAttributes(org.json.JSONObject, com.twilio.chat.StatusListener)
public void setAttributes(org.json.JSONObject updatedAttributes, StatusListener listener)
Attributes are stored as a JSON format object, of arbitrary internal structure. Channel attributes are limited in size to 32Kb.
Passing null attributes will reset channel attributes string to empty.
updatedAttributes
- attributes to change.listener
- Listener that will receive callback with the result.getAttributes()
public Messages getMessages()
You need to synchronize the channel before you call this method unless you just joined the channel, in which case it synchronizes automatically.
#synchronize
,
join(com.twilio.chat.StatusListener)
public Channel.ChannelStatus getStatus()
public void addListener(ChannelListener listener)
ChannelListener
for this Channel.
Channel listeners receive real time updates about changes in the channel state, messages and members.
This listener will be called on the originating thread if it has a Looper, otherwise on the main UI thread.
listener
- A channel listener.removeListener(com.twilio.chat.ChannelListener)
,
removeAllListeners()
public void removeListener(ChannelListener listener)
listener
- Listener to remove.addListener(com.twilio.chat.ChannelListener)
,
removeAllListeners()
public void removeAllListeners()
public Members getMembers()
You need to synchronize the channel before you call this method unless you just joined the channel, in which case it synchronizes automatically.
#synchronize
,
join(com.twilio.chat.StatusListener)
public void join(StatusListener listener)
listener
- Listener that will receive callback with the result.leave(com.twilio.chat.StatusListener)
,
declineInvitation(com.twilio.chat.StatusListener)
public void leave(StatusListener listener)
listener
- Listener that will receive callback with the result.join(com.twilio.chat.StatusListener)
,
declineInvitation(com.twilio.chat.StatusListener)
public void destroy(StatusListener listener)
Note: this will delete the Channel and all associated metadata from the service instance. Members in the channel and all channel messages will be lost.
There is no undo for this operation!
listener
- Listener that will receive callback with the result.dispose()
public void declineInvitation(StatusListener listener)
If your user is invited to the channel, he can choose to either join(com.twilio.chat.StatusListener)
the channel to
accept the invitation or declineInvitation(com.twilio.chat.StatusListener)
to decline.
listener
- Listener that will receive callback with the result.join(com.twilio.chat.StatusListener)
,
leave(com.twilio.chat.StatusListener)
public void typing()
You should call this method to indicate that a local user is entering a message into
current channel. The typing state is forwarded to users subscribed to this
channel through ChannelListener.onTypingStarted(com.twilio.chat.Member)
and
ChannelListener.onTypingEnded(com.twilio.chat.Member)
callbacks.
After approximately 5 seconds after the last typing()
call the SDK will emit
ChannelListener.onTypingEnded(com.twilio.chat.Member)
signal.
One common way to implement this indicator is to call typing()
repeatedly in response
to key input events.
public Channel.SynchronizationStatus getSynchronizationStatus()
#synchronize
public java.lang.String getDateCreated()
public java.util.Date getDateCreatedAsDate()
public java.lang.String getCreatedBy()
public java.lang.String getDateUpdated()
public java.util.Date getDateUpdatedAsDate()
public void getMessagesCount(CallbackListener<java.lang.Long> listener)
This function performs an async call to service to obtain up-to-date message count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.
listener
- Listener to receive results of the query.getUnconsumedMessagesCount(com.twilio.chat.CallbackListener<java.lang.Long>)
public void getUnconsumedMessagesCount(CallbackListener<java.lang.Long> listener)
This function performs an async call to service to obtain up-to-date message count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.
listener
- Listener to receive results of the query.getMessagesCount(com.twilio.chat.CallbackListener<java.lang.Long>)
public void getMembersCount(CallbackListener<java.lang.Long> listener)
This function performs an async call to service to obtain up-to-date member count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.
listener
- Listener to receive results of the query.public int describeContents()
Parcelable
-related method. You do not need to call it.describeContents
in interface android.os.Parcelable
public void writeToParcel(android.os.Parcel dest, int flags)
Parcelable
-related method. You do not need to call it.writeToParcel
in interface android.os.Parcelable
public void dispose()
Note: this does NOT delete the Channel from the service instance.
destroy(com.twilio.chat.StatusListener)