Methods
AcknowledgePendingMessages | (au: IDs) | → | nothing | |
GetMessageTypes | () | → | au: Available_Types | |
ListPendingMessages | (b: Clear) | → | a(uuuuus): Pending_Messages | |
Send | (u: Type, s: Text) | → | nothing |
Signals
LostMessage | () | |
Received | (u: ID, u: Timestamp, u: Sender, u: Type, u: Flags, s: Text) | |
SendError | (u: Error, u: Timestamp, u: Type, s: Text) | |
Sent | (u: Timestamp, u: Type, s: Text) |
Telepathy Properties
anonymous | b |
invite-only | b |
limit | u |
limited | b |
moderated | b |
name | s |
description | s |
password | s |
password-required | b |
persistent | b |
private | b |
subject | s |
subject-contact | u (Contact_Handle) |
subject-timestamp | u (Unix_Timestamp) |
Types
Message_ID | Simple Type | u | |
Channel_Text_Send_Error | Enum | u | |
Channel_Text_Message_Type | Enum | u | |
Channel_Text_Message_Flags | Flags | u | |
Pending_Text_Message | Struct | (uuuuus) |
Description
A channel type for sending and receiving messages in plain text, with no formatting. In future specifications, channels for sending and receiving messages that can be reduced to plain text (i.e. formatted text) should also have this type.
When a message is received, an identifier is assigned and a Received signal emitted, and the message placed in a pending queue which can be inspected with ListPendingMessages. A client which has handled the message by showing it to the user (or equivalent) should acknowledge the receipt using the AcknowledgePendingMessages method, and the message will then be removed from the pending queue. Numeric identifiers for received messages may be reused over the lifetime of the channel.
Each message has an associated 'type' value, which should be one of the values allowed by Channel_Text_Message_Type.
Each message also has a flags value, which is a bitwise OR of the flags given in Channel_Text_Message_Flags.
Sending messages can be requested using the Send method, which will return successfully and emit the Sent signal when the message has been delivered to the server, or return an error with no signal emission if there is a failure. If a message is sent but delivery of the message later fails, this is indicated with the SendError signal.
On protocols where additional contacts cannot be invited into a one-to-one chat, or where a one-to-one chat is just a series of individual personal messages rather than being represented by some object on the server (i.e. most protocols), one-to-one chats should be represented by a Text channel with Handle_Type CONTACT.
Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text channels with Handle_Type ROOM and the Group interface; they should usually also have the Properties interface.
Unnamed, transient chat rooms defined only by their members (e.g. on MSN) are expected to be represented by Text channels with handle type 0, handle 0, the Group interface, and optionally the Properties interface.
On protocols where a conversation with a user is actually just a nameless chat room starting with exactly two members, to which more members can be invited, calling RequestChannel with type Text and handle type CONTACT should continue to succeed, but may return a channel with handle type 0, handle 0, the group interface, and the local and remote contacts in its members.
If a channel of type Text is closed while it has pending messages, the connection manager MUST allow this, but SHOULD open a new, identical channel to deliver those messages, signalling it as a new channel with the NewChannel signal (with the suppress_handler parameter set to FALSE).
If messages were sent on the old channel but the Sentsignal has not yet been emitted for those messages, the new channel SHOULD emit Sent for those messages when appropriate - it behaves like a continuation of the old channel.
Rationale:
In effect, this turns this situation, in which a client is likely to lose messages:
- UI window is closed
- message arrives
- text channel emits Received
- UI calls Close on text channel before it has seen the Received signal
- text channel emits Closed and closes
into something nearly equivalent to this situation, which is fine:
- UI window is closed
- UI calls Close on text channel
- text channel emits Closed and closes
- message arrives
- new text channel is created, connection emits NewChannel
- (the same or a different) UI handles it
suppress_handler must be set to FALSE so the replacement channel will be handled by something.
As a result, Text channels SHOULD implement Channel.Interface.Destroyable.
Rationale:
This "respawning" behaviour becomes problematic if there is no suitable handler for Text channels, or if a particular message repeatedly crashes the Text channel handler; a channel dispatcher can't just Close() the channel in these situations, because it will come back.
In these situations, the channel dispatcher needs a last-resort way to destroy the channel and stop it respawning. It could either acknowledge the messages itself, or use the Destroyable interface; the Destroyable interface has the advantage that it's not channel-type-dependent, so the channel dispatcher only has to understand one extra interface, however many channel types eventually need a distinction between Close and Destroy.
Methods
AcknowledgePendingMessages (au: IDs) → nothing
Parameters
- IDs — au (Message_ID_List)
Possible Errors
- Invalid Argument
GetMessageTypes () → au: Available_Types
Returns
- Available_Types — au (Channel_Text_Message_Type_List)
ListPendingMessages (b: Clear) → a(uuuuus): Pending_Messages
Parameters
- Clear — b
Returns
- Pending_Messages — a(uuuuus) (Pending_Text_Message_List)
- a numeric identifier
- a Unix timestamp indicating when the message was received
- the contact handle for the contact who sent the message
- the message type, taken from ChannelTextMessageType
- the bitwise-OR of the message flags from ChannelTextMessageFlags
- the text of the message
Send (u: Type, s: Text) → nothing
Parameters
- Type — u (Channel_Text_Message_Type)
- Text — s
Request that a message be sent on this channel. When the message has been submitted for delivery, this method will return and the Sent signal will be emitted. If the message cannot be submitted for delivery, the method returns an error and no signal is emitted.
This method SHOULD return before the Sent signal is emitted.
Rationale:
When a Text channel implements the Messages interface, that "SHOULD" becomes a "MUST".
Possible Errors
- Disconnected
- Network Error
- Invalid Argument
- Permission Denied
Rationale:
Signals
LostMessage ()
Received (u: ID, u: Timestamp, u: Sender, u: Type, u: Flags, s: Text)
Parameters
- ID — u
- Timestamp — u (Unix_Timestamp)
- Sender — u (Contact_Handle)
- Type — u (Channel_Text_Message_Type)
- Flags — u (Channel_Text_Message_Flags)
- Text — s
SendError (u: Error, u: Timestamp, u: Type, s: Text)
Parameters
- Error — u (Channel_Text_Send_Error)
- Timestamp — u (Unix_Timestamp)
- Type — u (Channel_Text_Message_Type)
- Text — s
Sent (u: Timestamp, u: Type, s: Text)
Parameters
- Timestamp — u (Unix_Timestamp)
- Type — u (Channel_Text_Message_Type)
- Text — s
Signals that a message has been submitted for sending.
Telepathy Properties
anonymous — b
name — s
persistent — b
subject — s
subject-contact — u (Contact_Handle)
subject-timestamp — u (Unix_Timestamp)
Types
Message_ID — u
Channel_Text_Send_Error — u
- Unknown (0)
- Offline (1)
- Invalid_Contact (2)
- Permission_Denied (3)
- Too_Long (4)
- Not_Implemented (5)
Channel_Text_Message_Type — u
- Normal (0)
- Action (1)
- Notice (2)
- Auto_Reply (3)
- Delivery_Report (4)
Channel_Text_Message_Flags — u
- Truncated (1)
- Non_Text_Content (2)
- Scrollback (4)
- Rescued (8)
The incoming message contained non-text content which cannot be represented by this interface, but has been signalled in the Messages interface.
Connection managers SHOULD only set this flag if the non-text content appears to be relatively significant (exactly how significant is up to the implementor). The intention is that if this flag is set, clients using this interface SHOULD inform the user that part of the message was not understood.
The incoming message was part of a replay of message history.
Rationale:
In XMPP multi-user chat, a few past messages are replayed when you join a chatroom. A sufficiently capable IRC connection manager could also set this flag on historical messages when connected to a proxy like bip or irssi-proxy. The existence of this flag allows loggers and UIs to use better heuristics when eliminating duplicates (a simple implementation made possible by this flag would be to avoid logging scrollback at all).
The incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing an identical channel (the channel in which the message now appears) to open.
Rationale:
This means that a logger (which should already have seen the message in the previous channel) is able to recognise and ignore these replayed messages.
Pending_Text_Message — (uuuuus)
- Identifier — u (Message_ID)
- Unix_Timestamp — u (Unix_Timestamp)
- Sender — u (Contact_Handle)
- Message_Type — u (Channel_Text_Message_Type)
- Flags — u (Channel_Text_Message_Flags)
- Text — s