2
<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
4
<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
5
<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
6
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
<p>This library is free software; you can redistribute it and/or
8
modify it under the terms of the GNU Lesser General Public
9
License as published by the Free Software Foundation; either
10
version 2.1 of the License, or (at your option) any later version.</p>
12
<p>This library is distributed in the hope that it will be useful,
13
but WITHOUT ANY WARRANTY; without even the implied warranty of
14
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
Library General Public License for more details.</p>
17
<p>You should have received a copy of the GNU Lesser General Public
18
License along with this library; if not, write to the Free Software
19
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</p>
21
<interface name="org.freedesktop.Telepathy.Channel.Type.Text">
22
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
23
<method name="AcknowledgePendingMessages">
24
<arg direction="in" name="ids" type="au">
26
The IDs of the messages to acknowledge
30
Inform the channel that you have handled messages by displaying them to
31
the user (or equivalent), so they can be removed from the pending queue.
34
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
35
A given message ID was not found, so no action was taken
39
<method name="GetMessageTypes">
40
<arg direction="out" type="au">
42
An array of integer message types (ChannelTextMessageType)
46
Return an array indicating which types of message may be sent on this
50
<method name="ListPendingMessages">
51
<arg direction="in" name="clear" type="b">
53
If true, remove all messages from the queue
56
<arg direction="out" type="a(uuuuus)">
58
An array of structs representing the pending queue. Each contains:
60
<li>a numeric identifier</li>
61
<li>a Unix timestamp indicating when the message was received</li>
62
<li>the contact handle for the contact who sent the message</li>
63
<li>the message type, taken from ChannelTextMessageType</li>
64
<li>the bitwise-OR of the message flags from ChannelTextMessageFlags</li>
65
<li>the text of the message</li>
70
List the messages currently in the pending queue, and optionally
74
<signal name="LostMessage">
76
This signal is emitted to indicate that an incoming message was
77
not able to be stored and forwarded by the connection manager
78
due to lack of memory.
81
<signal name="Received">
82
<arg name="id" type="u">
84
A numeric identifier for acknowledging the message
87
<arg name="timestamp" type="u">
89
A Unix timestamp indicating when the message was received
92
<arg name="sender" type="u">
94
The handle of the contact who sent the message
97
<arg name="type" type="u">
99
The type of the message (normal, action, notice, etc), from
100
ChannelTextMessageType
103
<arg name="flags" type="u">
105
A bitwise OR of the message flags as defined by ChannelTextMessageFlags
108
<arg name="text" type="s">
110
The text of the message
114
Signals that a message with the given id, timestamp, sender, type
115
and text has been received on this channel. Applications that catch
116
this signal and reliably inform the user of the message should
117
acknowledge that they have dealt with the message with the
118
AcknowledgePendingMessage method.
122
<arg direction="in" name="type" type="u">
124
An integer indicating the type of the message, from
125
ChannelTextMessageType
128
<arg direction="in" name="text" type="s">
134
Request that a message be sent on this channel. The Sent signal will be
135
emitted when the message has been sent, and this method will return.
138
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
139
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
140
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
141
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
142
</tp:possible-errors>
144
<tp:enum name="Channel_Text_Send_Error">
145
<tp:enumvalue suffix="Unknown" value="0">
147
An unknown error occurred
150
<tp:enumvalue suffix="Offline" value="1">
152
The requested contact was offline
155
<tp:enumvalue suffix="Invalid_Contact" value="2">
157
The requested contact is not valid
160
<tp:enumvalue suffix="Permission_Denied" value="3">
162
The user does not have permission to speak on this channel
165
<tp:enumvalue suffix="Too_Long" value="4">
167
The outgoing message was too long and was rejected by the server
170
<tp:enumvalue suffix="Not_Implemented" value="5">
172
The channel doesn't support sending text messages to the requested
177
<signal name="SendError">
178
<arg name="error" type="u">
180
One of the values of ChannelTextSendError
183
<arg name="timestamp" type="u">
185
The Unix timestamp indicating when the message was sent
188
<arg name="type" type="u">
190
The message type from ChannelTextMessageType
193
<arg name="text" type="s">
195
The text of the message
199
Signals that an outgoing message has failed to send. The error
200
will be one of the values from ChannelTextSendError.
204
<arg name="timestamp" type="u">
206
Unix timestamp indicating when the message was sent
209
<arg name="type" type="u">
211
The message type (normal, action, notice, etc) from
212
ChannelTextMessageType
215
<arg name="text" type="s">
217
The text of the message
221
Signals that a message has been sent on this channel.
224
<tp:enum name="Channel_Text_Message_Type">
225
<tp:enumvalue suffix="Normal" value="0">
230
<tp:enumvalue suffix="Action" value="1">
232
An action which might be presented to the user as
233
"* <sender> <action>"
236
<tp:enumvalue suffix="Notice" value="2">
238
A one-off or automated message not necessarily expecting a reply
241
<tp:enumvalue suffix="Auto_Reply" value="3">
243
An automatically-generated reply message
247
<tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag">
248
<tp:flag suffix="Truncated" value="1">
250
The incoming message was truncated to a shorter length by the
251
server or the connection manager.
255
<tp:property name="anonymous" type="b">
257
True if people may join the channel without other members being made
258
aware of their identity.
261
<tp:property name="invite-only" type="b">
263
True if people may not join the channel until they have been invited.
266
<tp:property name="limit" type="u">
268
The limit to the number of members, if limited is true.
271
<tp:property name="limited" type="b">
273
True if there is a limit to the number of channel members.
276
<tp:property name="moderated" type="b">
278
True if channel membership is not sufficient to allow participation.
281
<tp:property name="name" type="s">
283
A human-visible name for the channel, if it differs from the string
284
version of the channel's handle.
287
<tp:property name="description" type="s">
289
A human-readable description of the channel's overall purpose.
292
<tp:property name="password" type="s">
294
The password required to enter the channel if password-required is true.
297
<tp:property name="password-required" type="b">
299
True if a password must be provided to enter the channel.
302
<tp:property name="persistent" type="b">
304
True if the channel will remain in existence on the server after all
305
members have left it.
308
<tp:property name="private" type="b">
310
True if the channel is not visible to non-members.
313
<tp:property name="subject" type="s">
315
A human-readable description of the current subject of conversation in
316
the channel, similar to /topic in IRC.
319
<tp:property name="subject-contact" type="u">
321
A contact handle representing who last modified the subject.
324
<tp:property name="subject-timestamp" type="u">
326
A unix timestamp indicating when the subject was last modified.
329
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
330
<p>A channel type for sending and receiving messages in plain text, with no
333
<p>When a message is received, an identifier is assigned and a Received signal
334
emitted, and the message placed in a pending queue which can be inspected
335
with ListPendingMessages. A client which has handled the message by showing
336
it to the user (or equivalent) should acknowledge the receipt using the
337
AcknowledgePendingMessage method, and the message will then be removed from
338
the pending queue. Numeric identifiers for received messages may be reused
339
over the lifetime of the channel.</p>
341
<p>Each message has an associated 'type' value, which should be one of the
342
values allowed by ChannelTextMessageType.</p>
344
<p>Each message also has a flags value, which is a bitwise OR of the
345
flags given in ChannelTextMessageFlags.</p>
347
<p>Sending messages can be requested using the Send method, which will return
348
and cause the Sent signal to be emitted when the message has been delivered
349
to the server, or SendError if there is a failure.</p>
353
<!-- vim:set sw=2 sts=2 et ft=xml: -->