Interface Channel.Type.Text

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

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)
Objects implementing this interface must also implement:

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

(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

Returns

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

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

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

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 ()

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)

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.

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)

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.

Telepathy Properties

Accessed using the org.freedesktop.Telepathy.Properties interface.
(Permalink)

anonymous — b

True if people may join the channel without other members being made aware of their identity.
(Permalink)

invite-only — b

True if people may not join the channel until they have been invited.
(Permalink)

limit — u

The limit to the number of members, if limited is true.
(Permalink)

limited — b

True if there is a limit to the number of channel members.
(Permalink)

moderated — b

True if channel membership is not sufficient to allow participation.
(Permalink)

name — s

A human-visible name for the channel, if it differs from the channel's TargetID.
(Permalink)

description — s

A human-readable description of the channel's overall purpose.
(Permalink)

password — s

The password required to enter the channel if password-required is true.
(Permalink)

password-required — b

True if a password must be provided to enter the channel.
(Permalink)

persistent — b

True if the channel will remain in existence on the server after all members have left it.
(Permalink)

private — b

True if the channel is not visible to non-members.
(Permalink)

subject — s

A human-readable description of the current subject of conversation in the channel, similar to /topic in IRC.
(Permalink)

subject-contact — u (Contact_Handle)

A contact handle representing who last modified the subject, or 0 if it isn't known.
(Permalink)

subject-timestamp — u (Unix_Timestamp)

A unix timestamp indicating when the subject was last modified.

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

  • 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)

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.