Interface Channel.Type.Text

Interface Index (Compact) | Summary | Description | Methods | Signals | Types

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)
Changed in 0.21.5. The Messages interface is now mandatory
Changed in UNRELEASED. This interface used to have a bunch of clunky Telepathy.Properties. They have been removed in favour of D-Bus properties on the Room2, Subject2 and RoomConfig1 interfaces.
Objects implementing this interface must also implement:

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

(Permalink)

AcknowledgePendingMessages (au: IDs) → nothing

Parameters

Inform the channel that you have handled messages by displaying them to the user (or equivalent), so they can be removed from the pending queue.

Possible Errors

(Permalink)

GetMessageTypes () → au: Available_Types

Deprecated since 0.21.5. Consulting MessageTypes is preferred.

Returns

Return an array indicating which types of message may be sent on this channel.
(Permalink)

ListPendingMessages (b: Clear) → a(uuuuus): Pending_Messages

Deprecated since 0.21.5. Consulting PendingMessages is preferred.

Parameters

  • Clear — b
  • Deprecated since 0.17.3. Setting this to true is NOT RECOMMENDED for clients that have some sort of persistent message storage - clients SHOULD only acknowledge messages after they have actually stored them, which is impossible if this flag is true.
    If true, behave as if AcknowledgePendingMessages had also been called.

Returns

  • Pending_Messages — a(uuuuus) (Pending_Text_Message_List)
  • An array of structs representing the pending queue. Each contains:
    • 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
List the messages currently in the pending queue, and optionally remove then all.
(Permalink)

Send (u: Type, s: Text) → nothing

Deprecated since 0.21.5. The SendMessage method is more flexible.

Parameters

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
  • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
  • Raised when there is an error reading from or writing to the network.
  • Invalid Argument
  • Raised when one of the provided arguments is invalid.
  • Permission Denied
  • The user is not permitted to perform the requested operation.

Signals

(Permalink)

LostMessage ()

Deprecated since 0.21.5. In practice, this signal was not emitted, and does not have useful semantics.
This signal is emitted to indicate that an incoming message was not able to be stored and forwarded by the connection manager due to lack of memory.
(Permalink)

Received (u: ID, u: Timestamp, u: Sender, u: Type, u: Flags, s: Text)

Deprecated since 0.21.5. The MessageReceived signal is more informative.

Parameters

  • ID — u
  • A numeric identifier for acknowledging the message
  • Timestamp — u (Unix_Timestamp)
  • A Unix timestamp indicating when the message was received
  • Sender — u (Contact_Handle)
  • The handle of the contact who sent the message
  • Type — u (Channel_Text_Message_Type)
  • The type of the message (normal, action, notice, etc.)
  • Flags — u (Channel_Text_Message_Flags)
  • A bitwise OR of the message flags
  • Text — s
  • The text of the message
Signals that a message with the given id, timestamp, sender, type and text has been received on this channel. Applications that catch this signal and reliably inform the user of the message should acknowledge that they have dealt with the message with the AcknowledgePendingMessages method.
(Permalink)

SendError (u: Error, u: Timestamp, u: Type, s: Text)

Changed in 0.17.3. older spec versions claimed that SendError was emitted instead of Sent, rather than in addition to Sent. However, the 0.17.3+ semantics were what we'd always actually implemented.
Deprecated since 0.21.5. Delivery reporting is now provided by the Messages interface.

Parameters

Signals that an outgoing message has failed to send. The error will be one of the values from ChannelTextSendError.

This signal should only be emitted for messages for which Sent has already been emitted and Send has already returned success.

(Permalink)

Sent (u: Timestamp, u: Type, s: Text)

Deprecated since 0.21.5. The MessageSent signal is more informative.

Parameters

  • Timestamp — u (Unix_Timestamp)
  • Unix timestamp indicating when the message was sent
  • Type — u (Channel_Text_Message_Type)
  • The message type (normal, action, notice, etc) from ChannelTextMessageType
  • Text — s
  • The text of the message. If the message was, or will be, altered during transmission, this argument SHOULD reflect what other contacts will receive rather than being a copy of the argument to Send.

Signals that a message has been submitted for sending.

Types

Simple Type (Permalink)

Message_ID — u

A unique-per-channel identifier for an incoming message. These SHOULD be allocated in a way that minimizes collisions (in particular, message IDs SHOULD NOT be re-used until all of the 32-bit integer space has already been used).
Enum (Permalink)

Channel_Text_Send_Error — u

  • Unknown (0)
  • An unknown error occurred
  • Offline (1)
  • The requested contact was offline
  • Invalid_Contact (2)
  • The requested contact is not valid
  • Permission_Denied (3)
  • The user does not have permission to speak on this channel
  • Too_Long (4)
  • The outgoing message was too long and was rejected by the server
  • Not_Implemented (5)
  • The channel doesn't support sending text messages to the requested contact
Enum (Permalink)

Channel_Text_Message_Type — u

The type of message.
  • Normal (0)
  • An ordinary chat message. Unknown types SHOULD be treated like this.
  • Action (1)
  • An action which might be presented to the user as "* <sender> <action>", such as an IRC CTCP ACTION (typically selected by the "/me" command). For example, the text of the message might be "drinks more coffee".
  • Notice (2)
  • A one-off or automated message not necessarily expecting a reply
  • Auto_Reply (3)
  • An automatically-generated reply message.
  • Delivery_Report (4)
  • A delivery report. This message type MUST NOT appear unless the channel supports the Messages interface; see Message_Part for the format that delivery reports must take.
Flags (Permalink)

Channel_Text_Message_Flags — u

Deprecated since 0.21.5. The Messages interface has an extensible data structure including separate booleans for most of these flags.
  • Truncated (1)
  • The incoming message was truncated to a shorter length by the server or the connection manager.
  • Non_Text_Content (2)
  • 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.

  • Scrollback (4)
  • 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).

  • Rescued (8)
  • 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.

Struct (Permalink)

Pending_Text_Message — (uuuuus)

Deprecated since 0.21.5. New APIs should use an array of Message_Part instead.
A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) representing a pending text message, as returned by ListPendingMessages. The arguments of the Received signal also match this struct's signature.