Methods
AcknowledgePendingMessages | (au: IDs) | → | nothing | |
GetMessageTypes | () | → | au: Available_Types | (deprecated) |
ListPendingMessages | (b: Clear) | → | a(uuuuus): Pending_Messages | (deprecated) |
Send | (u: Type, s: Text) | → | nothing | (deprecated) |
Signals
LostMessage | () | (deprecated) |
Received | (u: ID, u: Timestamp, u: Sender, u: Type, u: Flags, s: Text) | (deprecated) |
SendError | (u: Error, u: Timestamp, u: Type, s: Text) | (deprecated) |
Sent | (u: Timestamp, u: Type, s: Text) | (deprecated) |
Types
Message_ID | Simple Type | u | |
Channel_Text_Send_Error | Enum | u | |
Channel_Text_Message_Type | Enum | u | |
Channel_Text_Message_Flags | Flags | u | (deprecated) |
Pending_Text_Message | Struct | (uuuuus) | (deprecated) |
Description
A channel type for sending and receiving messages. This channel type is primarily used for textual messages, but can also be used for formatted text, text with "attachments", or binary messages on some protocols.
Most of the methods and signals on this interface are deprecated, since they only support plain-text messages with limited metadata. See the mandatory Messages interface for the modern equivalents.
When a message is received, an identifier is assigned and a MessageReceived signal emitted, and the message is placed in a pending queue represented by the PendingMessages property. When the Handler for a channel has handled the message by showing it to the user (or equivalent), it should acknowledge the receipt of that message 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.
Sending messages can be requested using the SendMessage method, which will return successfully when the message has been submitted for sending, or return an error with no signal emission if there is an immediate failure. If a message is submitted for sending but delivery of the message later fails, this is indicated by a delivery report, which is received in the same way as an incoming message.
Simple one-to-one chats (such as streams of private messages in XMPP or IRC) should be represented by a Text channel whose TargetHandleType is Contact. The expected way to request such a channel is to set the ChannelType, TargetHandleType, and either TargetHandle or TargetID in a call to EnsureChannel.
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 TargetHandleType = Room and the Group interface. In protocols where a chatroom can be used as a continuation of one or more one-to-one chats, these channels should also have the Conference interface.
Unnamed, transient chat rooms which cannot be rejoined by their unique identifier (e.g. a conversation on MSN which has, or once had, three or more participants) are expected to be represented by Text channels with TargetHandleType = None (and hence TargetHandle = 0), Group interface, and optionally the Conference interface.
On protocols like MSN 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, the initial one-to-one conversation SHOULD be represented with TargetHandleType = Contact. If a third participant joins or is invited, this SHOULD be represented by signalling a new Conference channel with the one-to-one channel in its InitialChannels, migrating the underlying protocol object from the one-to-one channel to the Conference channel, and creating a new protocol-level conversation if the one-to-one channel is re-used. See the Conference interface for more details.
Rationale:
This keeps the presentation of all one-to-one conversations uniform, and makes it easier to hand over a conversation from a 1-1-specific UI to a more elaborate multi-user UI; while it does require UIs to understand Conference to follow the upgrade, UIs that will deal with XMPP need to understand Conference anyway.
If a channel of type Text is closed while it has pending messages, the connection manager MUST allow this, but SHOULD open a new channel to deliver those messages, signalling it as a new channel with the NewChannels signal. The new channel should resemble the old channel, but have Requested = FALSE regardless of its previous value; the InitiatorHandle and InitiatorID should correspond to the sender of one of the pending messages.
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 NewChannels
- (the same or a different) UI handles it
Requested must be set to FALSE so the replacement channel will be handled by something.
In practice, connection managers usually implement this by keeping the same internal object that represented the old channel, adjusting its properties, signalling that it was closed, then immediately re-signalling it as a new channel.
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.
Opaquely-named rejoinable chatrooms (such as Skype rooms) are represented using the properties in the Room2 interface. Instructions and examples of how to request such channels are given in said interface's description.
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.
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