A Text channel sends and receives text messages, such as instant messages. Each Text channel represents communication with a contact or group of contacts (e.g. a "chat room").
Channels for text chat are usually ensured (see Section 6.1 ― Requesting Channels) with the channel type Channel_Type_Text. For one-to-one chats, the target handle is a contact (Handle_Type_Contact). For named chatrooms (e.g. Jabber multi-user-chats, IRC chatrooms) the target handle is a room (Handle_Type_Room); these channels should support the Group interface.
Some protocols (e.g. MSN) support transient, unnamed chatrooms that are just defined by their members. These chatrooms are represented by an anonymous channel (Handle_Type_None) and implement the Group interface. On some protocols, i.e. ones where all chats are simply transient chatrooms, setting up a channel for a one-to-one chat with a contact may result in this type of channel; with the target contact simply a member.
A summary of the various text channels is given in Table 6-4.
| Channel Function | Example Usage | Required Handle Type | Required Interfaces | Notes |
|---|---|---|---|---|
| One-to-One Chat | XMPP 1-1 chat, IRC private messages | Handle_Type_Contact | Requests for this sort of channel may be upgraded to a transient chatroom. | |
| Named Chatroom | XMPP MUC, IRC chatroom | Handle_Type_Room | Group | |
| Transient Chatroom | MSN conversation | Handle_Type_None | Group | Appears as an anonymous channel. |
The Group interface present on chatroom-like channels is the same as that used for ContactLists, and is described in detail in Section 6.4 ― Contact Groups.
When the user wishes to part from a conversation, the channel's Close method should be called. The channel will be closed when the channel emits the Closed signal. Be aware that if there are still pending messages on the channel when it closes, a new, identical channel will be created by the connection (heralded by the NewChannel signal). This is to prevent message loss due to a possible race. For one-to-one chats, this is identical to when a remote user sends you a message.
To prevent any possible message loss, closing a channel with pending messages using the Close method will cause a new, identical channel to respawn that is the continuation of the original channel.
Occasionally this behaviour is undesireable/problematic. For example, when a particular text channel keeps crashing/causing errors in the message renderer. Closing the channel will cause it to respawn with the offending messages. In this case the Destroy method of the Destroyable interface can be used to ensure a channel is not respawned, dropping any pending messages on the channel.
Sending and receiving text messages in Empathy is documented in Chapter 8 ― Text Messaging.
Some channels (usually chatrooms) require a password to be able to join them. Telepathy exposes this via the Password interface.
Once a channel has been set up, and the interfaces retrieved, clients should check for the presence of the Password interface and if it exists call the GetPasswordFlags method. Telepathy currently has one flag: Channel_Password_Flags_Provide. If this flag is set, a password must be provided before the channel can be completely set up. Call the ProvidePassword method. If this returns true, then channel setup can continue.
Named Multi-user Chat (MUC) channels are represented by the Handle_Type_Room handle type. Like with contact identifiers, a room identifier depends on the protocol being used. Table 6-5 presents some example identifiers for various protocols.