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.
Some older Connection Managers (e.g. older versions of butterfly) with protocols where one-to-one chats are implemented as transient chatrooms may return a chatroom when a one-to-one chat is requested. That is all chats are simply transient chatrooms, and setting up a channel for a one-to-one chat with a contact will result in a chatroom; 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 group chats | 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.
The Conference interface can be used to upgrade a one-to-one chat to a multi-user chat (e.g. inviting a 3rd person) and for creating transient multi-user chats. This is done by requesting a new channel, with the request including the appropriate properties from the Conference interface.
You can request to upgrade a one-to-one conversation to a multi-user chatroom by requesting a channel with a combination of two or more InitialChannels, InitialInviteeHandles and InitialInviteeIDs.
The newly created channel will be the union of all the contacts in all the specified channels, plus all of the individually invited contacts. This information will be provided in the channel's immutable properties, and can be used by user interfaces to automatically upgrade the UI to a group chat. Depending on the protocol, this channel may be automatically created for all of the contacts, or each contact may have to be invited to the new channel individually.
When merging or upgrading channels, the ChannelType must match for all channels.
To request a channel upgrading your existing one-to-one conversation with theo@comic.cat (channel path /.../catchat/escher/theo_comic_cat) to also include sage@comic.cat, the request to CreateChannel would be:
| Channel.ChannelType | Channel.Type.Text |
| Channel.Interface.Conference.InitialChannels | [ /.../catchat/escher/theo_comic_cat ] |
| Channel.Interface.Conference.InitialInviteeIDs | [ sage@comic.cat ] |
To request merging two one-to-one conversations, for example /.../catchat/escher/theo_comic_cat and /.../catchat/escher/sage_comic_cat, the request to CreateChannel would be:
| Channel.ChannelType | Channel.Type.Text |
| Channel.Interface.Conference.InitialChannels | [ /.../catchat/escher/theo_comic_cat, /.../catchat/escher/sage_comic_cat ] |
To create a transient chatroom (e.g. an anonymous XMPP MUC or an MSN chat) with two other contacts, cameo@egg.cat and rocket@pocketdog.cat, the request to CreateChannel would be:
| Channel.ChannelType | Channel.Type.Text |
| Channel.Interface.Conference.InitialInviteeIDs | [ cameo@egg.cat, rocket@pocketdog.cat ] |
For protocols that support named chatrooms, you can also use EnsureChannel to ensure a chatroom that includes the members of other channels, or named invitees.
| Channel.ChannelType | Channel.Type.Text |
| Channel.TargetHandleType | Target_Handle_Room |
| Channel.TargetID | #catnap |
| Channel.Interface.Conference.InitialInviteeIDs | [ escher, cameo, rocket, button ] |
This is functionally equivalent to ensuring the channel and then inviting the other contacts via the Group interface. This functionality is more interesting for protocols/situations where existing channels can be merged into one named channel.
Incoming channels with the InitialChannels property from the can be seen as continuations of those channels, and the client interface can optionally change or merge the display of those channels in its interface.