diff options
Diffstat (limited to 'qt4/spec/Channel_Type_Text.xml')
| -rw-r--r-- | qt4/spec/Channel_Type_Text.xml | 669 |
1 files changed, 669 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Type_Text.xml b/qt4/spec/Channel_Type_Text.xml new file mode 100644 index 000000000..0cd4d5bb2 --- /dev/null +++ b/qt4/spec/Channel_Type_Text.xml @@ -0,0 +1,669 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> + <tp:changed version="0.21.5">The Messages interface is now + mandatory</tp:changed> + + <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List"> + <tp:docstring> + 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). + </tp:docstring> + </tp:simple-type> + + <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> + <tp:deprecated version="0.21.5">New APIs should use + an array of <tp:type>Message_Part</tp:type> instead.</tp:deprecated> + <tp:docstring>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 + <tp:member-ref>ListPendingMessages</tp:member-ref>. The arguments of + the <tp:member-ref>Received</tp:member-ref> signal also match this + struct's signature.</tp:docstring> + <tp:member type="u" tp:type="Message_ID" name="Identifier"/> + <tp:member type="u" tp:type="Unix_Timestamp" name="Unix_Timestamp"/> + <tp:member type="u" tp:type="Contact_Handle" name="Sender"/> + <tp:member type="u" tp:type="Channel_Text_Message_Type" + name="Message_Type"/> + <tp:member type="u" tp:type="Channel_Text_Message_Flags" name="Flags"/> + <tp:member type="s" name="Text"/> + </tp:struct> + + <method name="AcknowledgePendingMessages" + tp:name-for-bindings="Acknowledge_Pending_Messages"> + <arg direction="in" name="IDs" type="au" tp:type="Message_ID[]"> + <tp:docstring> + The IDs of the messages to acknowledge + </tp:docstring> + </arg> + <tp:docstring> + 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. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A given message ID was not found, so no action was taken + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetMessageTypes" tp:name-for-bindings="Get_Message_Types"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageTypes</tp:dbus-ref> is preferred. + </tp:deprecated> + <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]" + name="Available_Types"> + <tp:docstring> + An array of integer message types (ChannelTextMessageType) + </tp:docstring> + </arg> + <tp:docstring> + Return an array indicating which types of message may be sent on this + channel. + </tp:docstring> + </method> + + <method name="ListPendingMessages" + tp:name-for-bindings="List_Pending_Messages"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> is preferred. + </tp:deprecated> + <arg direction="in" name="Clear" type="b"> + <tp:docstring> + If true, behave as if + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also + been called. + </tp:docstring> + <tp:deprecated version="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.</tp:deprecated> + </arg> + <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]" + name="Pending_Messages"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs representing the pending queue. Each contains: + <ul> + <li>a numeric identifier</li> + <li>a Unix timestamp indicating when the message was received</li> + <li>the contact handle for the contact who sent the message</li> + <li>the message type, taken from ChannelTextMessageType</li> + <li>the bitwise-OR of the message flags from ChannelTextMessageFlags</li> + <li>the text of the message</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + List the messages currently in the pending queue, and optionally + remove then all. + </tp:docstring> + </method> + + <signal name="LostMessage" tp:name-for-bindings="Lost_Message"> + <tp:deprecated version="0.21.5">In practice, this signal + was not emitted, and does not have useful semantics.</tp:deprecated> + <tp:docstring> + 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. + </tp:docstring> + </signal> + + <signal name="Received" tp:name-for-bindings="Received"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal is more informative. + </tp:deprecated> + <arg name="ID" type="u"> + <tp:docstring> + A numeric identifier for acknowledging the message + </tp:docstring> + </arg> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A Unix timestamp indicating when the message was received + </tp:docstring> + </arg> + <arg name="Sender" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the contact who sent the message + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The type of the message (normal, action, notice, etc.) + </tp:docstring> + </arg> + <arg name="Flags" type="u" tp:type="Channel_Text_Message_Flags"> + <tp:docstring> + A bitwise OR of the message flags + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + The text of the message + </tp:docstring> + </arg> + <tp:docstring> + 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 + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method. + </tp:docstring> + </signal> + + <method name="Send" tp:name-for-bindings="Send"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> method is more flexible. + </tp:deprecated> + <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + An integer indicating the type of the message + </tp:docstring> + </arg> + <arg direction="in" name="Text" type="s"> + <tp:docstring> + The message to send + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that a message be sent on this channel. When the message has + been submitted for delivery, this method will return and the + <tp:member-ref>Sent</tp:member-ref> signal will be emitted. If the + message cannot be submitted for delivery, the method returns an error + and no signal is emitted.</p> + + <p>This method SHOULD return before the Sent signal is + emitted.</p> + + <tp:rationale> + <p>When a Text channel implements the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface, that "SHOULD" becomes a "MUST".</p> + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:enum name="Channel_Text_Send_Error" type="u"> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + An unknown error occurred + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring> + The requested contact was offline + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invalid_Contact" value="2"> + <tp:docstring> + The requested contact is not valid + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Permission_Denied" value="3"> + <tp:docstring> + The user does not have permission to speak on this channel + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Too_Long" value="4"> + <tp:docstring> + The outgoing message was too long and was rejected by the server + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Implemented" value="5"> + <tp:docstring> + The channel doesn't support sending text messages to the requested + contact + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="SendError" tp:name-for-bindings="Send_Error"> + <tp:deprecated version="0.21.5">Delivery reporting is now + provided by the <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface. + </tp:deprecated> + <arg name="Error" type="u" tp:type="Channel_Text_Send_Error"> + <tp:docstring> + The error that occurred + </tp:docstring> + </arg> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + The Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The message type + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + The text of the message + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that an outgoing message has failed to send. The error + will be one of the values from ChannelTextSendError.</p> + + <p>This signal should only be emitted for messages for which + <tp:member-ref>Sent</tp:member-ref> has already been emitted and + <tp:member-ref>Send</tp:member-ref> has already returned success.</p> + </tp:docstring> + <tp:changed version="0.17.3">older spec versions claimed that SendError + was emitted <em>instead of</em> Sent, rather than <em>in addition + to</em> Sent. However, the 0.17.3+ semantics were what we'd always + actually implemented.</tp:changed> + </signal> + + <signal name="Sent" tp:name-for-bindings="Sent"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageSent</tp:dbus-ref> signal is more informative. + </tp:deprecated> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The message type (normal, action, notice, etc) from + ChannelTextMessageType + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + 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 <tp:member-ref>Send</tp:member-ref>. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that a message has been submitted for sending.</p> + </tp:docstring> + </signal> + + <tp:enum name="Channel_Text_Message_Type" type="u" + array-name="Channel_Text_Message_Type_List"> + <tp:docstring> + The type of message. + </tp:docstring> + + <tp:enumvalue suffix="Normal" value="0"> + <tp:docstring> + An ordinary chat message. Unknown types SHOULD be treated like this. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Action" value="1"> + <tp:docstring> + 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". + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Notice" value="2"> + <tp:docstring> + A one-off or automated message not necessarily expecting a reply + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Auto_Reply" value="3"> + <tp:docstring> + An automatically-generated reply message. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Delivery_Report" value="4"> + <tp:docstring> + A delivery report. This message type MUST NOT appear unless the + channel supports the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface; see <tp:type>Message_Part</tp:type> for the format that + delivery reports must take. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface has an extensible data structure + including separate booleans for most of these flags. + </tp:deprecated> + <tp:flag suffix="Truncated" value="1"> + <tp:docstring> + The incoming message was truncated to a shorter length by the + server or the connection manager. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Non_Text_Content" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message contained non-text content which cannot be + represented by this interface, but has been signalled + in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface.</p> + + <p>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.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Scrollback" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message was part of a replay of message history.</p> + + <tp:rationale> + <p>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).</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Rescued" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message has been seen in a previous channel during + the lifetime of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, but + had not been acknowledged + when that channel closed, causing an identical channel (the + channel in which the message now appears) to open.</p> + + <tp:rationale> + <p>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.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:property name="anonymous" type="b"> + <tp:docstring> + True if people may join the channel without other members being made + aware of their identity. + </tp:docstring> + </tp:property> + <tp:property name="invite-only" type="b"> + <tp:docstring> + True if people may not join the channel until they have been invited. + </tp:docstring> + </tp:property> + <tp:property name="limit" type="u"> + <tp:docstring> + The limit to the number of members, if limited is true. + </tp:docstring> + </tp:property> + <tp:property name="limited" type="b"> + <tp:docstring> + True if there is a limit to the number of channel members. + </tp:docstring> + </tp:property> + <tp:property name="moderated" type="b"> + <tp:docstring> + True if channel membership is not sufficient to allow participation. + </tp:docstring> + </tp:property> + <tp:property name="name" type="s"> + <tp:docstring> + A human-visible name for the channel, if it differs from the channel's + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>. + </tp:docstring> + </tp:property> + <tp:property name="description" type="s"> + <tp:docstring> + A human-readable description of the channel's overall purpose. + </tp:docstring> + </tp:property> + <tp:property name="password" type="s"> + <tp:docstring> + The password required to enter the channel if password-required is true. + </tp:docstring> + </tp:property> + <tp:property name="password-required" type="b"> + <tp:docstring> + True if a password must be provided to enter the channel. + </tp:docstring> + </tp:property> + <tp:property name="persistent" type="b"> + <tp:docstring> + True if the channel will remain in existence on the server after all + members have left it. + </tp:docstring> + </tp:property> + <tp:property name="private" type="b"> + <tp:docstring> + True if the channel is not visible to non-members. + </tp:docstring> + </tp:property> + <tp:property name="subject" type="s"> + <tp:docstring> + A human-readable description of the current subject of conversation in + the channel, similar to /topic in IRC. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + <tp:property name="subject-contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle representing who last modified the subject, or 0 + if it isn't known. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A unix timestamp indicating when the subject was last modified. + This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + + <p>Most of the methods and signals on this interface are deprecated, + since they only support plain-text messages with limited metadata. + See the mandatory <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages</tp:dbus-ref> + interface for the modern equivalents.</p> + + <p>When a message is received, an identifier is assigned and a + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal emitted, and the message + is placed in a pending queue represented by the + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> property. + When the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + 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 <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> + 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.</p> + + <p>Sending messages can be requested using the + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> 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.</p> + + <p>Simple one-to-one chats (such as streams of private messages in + XMPP or IRC) should be represented by a Text channel whose + <tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> + is <tp:type>Handle_Type</tp:type>_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.</p> + + <p>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 <tp:type>Handle_Type</tp:type>_Room and the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + 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 + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>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 Handle_Type_None (and hence TargetHandle 0), the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface, and optionally the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>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 Handle_Type_Contact. If a third participant + joins or is invited, this SHOULD be represented by signalling + a new <tp:dbus-ref + namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> channel + with the one-to-one channel in its <tp:dbus-ref + namespace="ofdT.Channel.Interface.Conference" + >InitialChannels</tp:dbus-ref>, 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.</p> + + <tp:rationale> + <p>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.</p> + </tp:rationale> + + <p>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 + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + 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.</p> + + <tp:rationale> + <p>In effect, this turns this situation, in which a client + is likely to lose messages:</p> + + <ul> + <li>UI window is closed</li> + <li>message arrives</li> + <li>text channel emits Received</li> + <li>UI calls Close on text channel before it has seen the + Received signal</li> + <li>text channel emits Closed and closes</li> + </ul> + + <p>into something nearly equivalent to this situation, which is + fine:</p> + + <ul> + <li>UI window is closed</li> + <li>UI calls Close on text channel</li> + <li>text channel emits Closed and closes</li> + <li>message arrives</li> + <li>new text channel is created, connection emits NewChannels</li> + <li>(the same or a different) UI handles it</li> + </ul> + + <p>Requested must be set to FALSE so the replacement channel + will be handled by something.</p> + + <p>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.</p> + </tp:rationale> + + <p>As a result, Text channels SHOULD implement <tp:dbus-ref + namespace="ofdT">Channel.Interface.Destroyable</tp:dbus-ref>.</p> + + <tp:rationale> + <p>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.</p> + + <p>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.</p> + </tp:rationale> + + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |