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:
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:
As a result, Text channels SHOULD implement Channel.Interface.Destroyable.
Rationale:
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:
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:
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:
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