diff options
Diffstat (limited to 'spec')
23 files changed, 1753 insertions, 1123 deletions
diff --git a/spec/Channel.xml b/spec/Channel.xml index 79ab0996..3b7c43c9 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -28,16 +28,22 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed. - - Possible Errors: - - * Disconnected - * NetworkError - * NotImplemented - this channel may never be closed, e.g. a contact - list - * NotAvailable - this channel is not currently in a state where - it can be closed, e.g. a non-empty user-defined contact group </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.NotImplemented"> + <tp:docstring> + This channel may never be closed, e.g. a contact list + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This channel is not currently in a state where it can be closed, + e.g. a non-empty user-defined contact group + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <signal name="Closed"> <tp:docstring> @@ -48,14 +54,26 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <method name="GetChannelType"> - <arg direction="out" type="s"/> + <arg direction="out" type="s"> + <tp:docstring>The interface name</tp:docstring> + </arg> <tp:docstring> Returns the interface name for the type of this channel. </tp:docstring> </method> <method name="GetHandle"> - <arg direction="out" type="u"/> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + The handle type, or zero if this channel does not correspond to any + particular handle + </tp:docstring> + </arg> + <arg direction="out" type="u"> + <tp:docstring> + The handle, or zero if this channel does not correspond to any + particular handle + </tp:docstring> + </arg> <tp:docstring> Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or @@ -63,16 +81,17 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </method> <method name="GetInterfaces"> - <arg direction="out" type="as"/> + <arg direction="out" type="as"> + <tp:docstring> + An array of the D-Bus interface names + </tp:docstring> + </arg> <tp:docstring> Get the optional interfaces implemented by the channel. - - Returns: - an array of the D-Bus interface names </tp:docstring> </method> <tp:docstring> - All communication in the Telepathy framework is carried out via channel + All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must be implemented by all channel objects, along with one single channel type, such as Channel.Type.ContactList which represents a list of people (such diff --git a/spec/ChannelInterfaceDTMF.xml b/spec/ChannelInterfaceDTMF.xml index c8d0e30d..20bdbccc 100644 --- a/spec/ChannelInterfaceDTMF.xml +++ b/spec/ChannelInterfaceDTMF.xml @@ -22,29 +22,32 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF" tp:name-const="CHANNEL_INTERFACE_DTMF"> <signal name="ReceivedDTMF"> - <arg name="signal" type="u"/> - <arg name="duration" type="u"/> + <arg name="signal" type="u"> + <tp:docstring>A numeric signal number</tp:docstring> + </arg> + <arg name="duration" type="u"> + <tp:docstring>A numeric duration in milliseconds</tp:docstring> + </arg> <tp:docstring> Signals that this channel received a DTMF tone. - - Parameters: - signal - a numeric signal number - duration - a numeric duration in milliseconds </tp:docstring> </signal> <method name="SendDTMF"> - <arg direction="in" name="signal" type="u"/> - <arg direction="in" name="duration" type="u"/> + <arg direction="in" name="signal" type="u"> + <tp:docstring>A numeric signal number</tp:docstring> + </arg> + <arg direction="in" name="duration" type="u"> + <tp:docstring>A numeric duration in milliseconds</tp:docstring> + </arg> <tp:docstring> Requests that a DTMF tone is sent. - - Parameters: - signal - a numeric signal number - duration - a numeric duration in milliseconds - - Possible Errors: - Disconnected, NetworkError, NotAvailable, InvalidArgument </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> </method> <tp:docstring> An interface that gives a Channel the ability to send or receive DTMF diff --git a/spec/ChannelInterfaceGroup.xml b/spec/ChannelInterfaceGroup.xml index 108f2e56..ebeb4f75 100644 --- a/spec/ChannelInterfaceGroup.xml +++ b/spec/ChannelInterfaceGroup.xml @@ -22,109 +22,158 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.Group" tp:name-const="CHANNEL_INTERFACE_GROUP"> <method name="AddMembers"> - <arg direction="in" name="contacts" type="au"/> - <arg direction="in" name="message" type="s"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of contact handles to invite to the channel + </tp:docstring> + </arg> + <arg direction="in" name="message" type="s"> + <tp:docstring> + A string message, which can be blank if desired + </tp:docstring> + </arg> <tp:docstring> Invite all the given contacts into the channel, or accept requests for - channel membership for contacts on the pending local list. A message - may be provided along with the request, which will be sent to the - server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and + channel membership for contacts on the pending local list. + + A message may be provided along with the request, which will be sent + to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this message should be provided. - - Parameters: - contacts - an array of contact handles to invite to the channel - message - a string message, which can be blank if desired - - Possible Errors: - Disconnected, NetworkError, NotAvailable, PermissionDenied, InvalidHandle, - Channel.Full, Channel.InviteOnly, Channel.Banned </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + </tp:possible-errors> </method> <method name="GetAllMembers"> - <arg direction="out" type="au"/> - <arg direction="out" type="au"/> - <arg direction="out" type="au"/> + <arg direction="out" type="au"> + <tp:docstring> + array of handles of current members + </tp:docstring> + </arg> + <arg direction="out" type="au"> + <tp:docstring> + array of handles of local pending members + </tp:docstring> + </arg> + <arg direction="out" type="au"> + <tp:docstring> + array of handles of remote pending members + </tp:docstring> + </arg> <tp:docstring> - Returns arrays all current, local and remote pending channel + Returns arrays of all current, local and remote pending channel members. - - Returns: - array of handles of current members - array of handles of local pending members - array of handles of remote pending members - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <tp:flags name="ChannelGroupFlags"> - <tp:flag name="CHANNEL_GROUP_FLAG_CAN_ADD" value="1"/> - <tp:flag name="CHANNEL_GROUP_FLAG_CAN_REMOVE" value="2"/> - <tp:flag name="CHANNEL_GROUP_FLAG_CAN_RESCIND" value="4"/> - <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_ADD" value="8"/> - <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_REMOVE" value="16"/> - <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT" value="32"/> - <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_REJECT" value="64"/> - <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_RESCIND" value="128"/> - <tp:flag name="CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES" value="256"/> - <tp:flag name="CHANNEL_GROUP_FLAG_ONLY_ONE_GROUP" value="512"/> - </tp:flags> - <method name="GetGroupFlags"> - <arg direction="out" type="u"/> - <tp:docstring> - Returns an integer representing the logical or of flags on this - channel. The user interface can use this to present information about - which operations are currently valid. - - These can be: - 1 - CHANNEL_GROUP_FLAG_CAN_ADD + <tp:flag name="CHANNEL_GROUP_FLAG_CAN_ADD" value="1"> + <tp:docstring> The AddMembers method can be used to add or invite members who are not already in the local pending list (which is always valid). - 2 - CHANNEL_GROUP_FLAG_CAN_REMOVE + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_CAN_REMOVE" value="2"> + <tp:docstring> The RemoveMembers method can be used to remove channel members (removing those on the pending local list is always valid). - 4 - CHANNEL_GROUP_FLAG_CAN_RESCIND + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_CAN_RESCIND" value="4"> + <tp:docstring> The RemoveMembers method can be used on people on the remote pending list. - 8 - CHANNEL_GROUP_FLAG_MESSAGE_ADD + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_ADD" value="8"> + <tp:docstring> A message may be sent to the server when calling AddMembers on contacts who are not currently pending members. - 16 - CHANNEL_GROUP_FLAG_MESSAGE_REMOVE + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_REMOVE" value="16"> + <tp:docstring> A message may be sent to the server when calling RemoveMembers on contacts who are currently channel members. - 32 - CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT" value="32"> + <tp:docstring> A message may be sent to the server when calling AddMembers on contacts who are locally pending. - 64 - CHANNEL_GROUP_FLAG_MESSAGE_REJECT + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_REJECT" value="64"> + <tp:docstring> A message may be sent to the server when calling RemoveMembers on contacts who are locally pending. - 128 - CHANNEL_GROUP_FLAG_MESSAGE_RESCIND + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_MESSAGE_RESCIND" value="128"> + <tp:docstring> A message may be sent to the server when calling RemoveMembers on contacts who are remote pending. - 256 - CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES" value="256"> + <tp:docstring> The members of this group have handles which are specific to this channel, and are not valid as general-purpose handles on the connection. Depending on the channel, it may be possible to call GetHandleOwners to find the owners of these handles, which should be done if you wish to eg subscribe to the contact's presence. - 512 - CHANNEL_GROUP_FLAG_ONLY_ONE_GROUP + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_GROUP_FLAG_ONLY_ONE_GROUP" value="512"> + <tp:docstring> Placing a contact in multiple groups of this type is not allowed and will raise NotAvailable (on services where contacts may only be in one user-defined group, user-defined groups will have this flag). - - Returns: - an integer of flags or'd together - - Possible Errors: - Disconnected, NetworkError + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="GetGroupFlags"> + <arg direction="out" type="u"> + <tp:docstring> + The bitwise OR of zero or more values from ChannelGroupFlags + </tp:docstring> + </arg> + <tp:docstring> + Returns an integer representing the bitwise-OR of flags on this + channel. The user interface can use this to present information about + which operations are currently valid. </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <method name="GetHandleOwners"> - <arg direction="in" name="handles" type="au"/> - <arg direction="out" type="au"/> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + A list of integer handles representing members of the channel + </tp:docstring> + </arg> + <arg direction="out" type="au"> + <tp:docstring> + An array of integer handles representing the owner handles of + the given room members, in the same order, or 0 if the + owner is not available + </tp:docstring> + </arg> <tp:docstring> If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on the channel, then the handles of the group members are specific @@ -132,49 +181,49 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA context such as contact lists. This method allows you to find the owner of the handle if it can be discovered in this channel, or 0 if the owner is not available. - - Parameters: - handles - a list of integer handles representing members of the - channel - - Returns: - an array of integer handles representing the owner handle of - the the given room members, in the same order, or 0 if the - owner is not available - - Possible Errors: - Disconnected, NetworkError, InvalidHandle, InvalidArgument (one - of the given handles is not a member) </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.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + One of the given handles is not a member + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <method name="GetLocalPendingMembers"> <arg direction="out" type="au"/> <tp:docstring> Returns an array of handles representing contacts requesting channel membership and awaiting local approval with AddMembers. - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <method name="GetMembers"> <arg direction="out" type="au"/> <tp:docstring> Returns an array of handles for the members of this channel. - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <method name="GetRemotePendingMembers"> <arg direction="out" type="au"/> <tp:docstring> Returns an array of handles representing contacts who have been invited to the channel and are awaiting remote approval. - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <method name="GetSelfHandle"> <arg direction="out" type="u"/> @@ -185,77 +234,122 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA channels). Note that this is different from the connection GetSelfHandle on some protocols, so the value of this handle should always be used with the methods of this interface. - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <signal name="GroupFlagsChanged"> - <arg name="added" type="u"/> - <arg name="removed" type="u"/> + <arg name="added" type="u"> + <tp:docstring> + A bitwise OR of the flags which have been set + </tp:docstring> + </arg> + <arg name="removed" type="u"> + <tp:docstring> + A bitwise OR of the flags which have been cleared + </tp:docstring> + </arg> <tp:docstring> Emitted when the flags as returned by GetGroupFlags are changed. The user interface should be updated as appropriate. - - Parameters: - added - a logical OR of the flags which have been set - removed - a logical OR of the flags which have been cleared </tp:docstring> </signal> <tp:enum name="ChannelGroupChangeReason"> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_NONE" value="0"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_OFFLINE" value="1"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_KICKED" value="2"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_BUSY" value="3"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_INVITED" value="4"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_BANNED" value="5"/> - <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_ERROR" value="6"/> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_NONE" value="0"> + <tp:docstring> + No reason was provided for this change. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_OFFLINE" value="1"> + <tp:docstring> + The change is due to a user going offline. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_KICKED" value="2"> + <tp:docstring> + The change is due to a kick operation. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_BUSY" value="3"> + <tp:docstring> + The change is due to a busy indication. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_INVITED" value="4"> + <tp:docstring> + The change is due to an invitation. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_BANNED" value="5"> + <tp:docstring> + The change is due to a kick+ban operation. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_ERROR" value="6"> + <tp:docstring> + The change is due to an error occurring. + </tp:docstring> + </tp:enumvalue> </tp:enum> <signal name="MembersChanged"> - <arg name="message" type="s"/> - <arg name="added" type="au"/> - <arg name="removed" type="au"/> - <arg name="local_pending" type="au"/> - <arg name="remote_pending" type="au"/> - <arg name="actor" type="u"/> - <arg name="reason" type="u"/> + <arg name="message" type="s"> + <tp:docstring> + A string message from the server, or blank if not + </tp:docstring> + </arg> + <arg name="added" type="au"> + <tp:docstring> + A list of members added to the channel + </tp:docstring> + </arg> + <arg name="removed" type="au"> + <tp:docstring> + A list of members removed from the channel + </tp:docstring> + </arg> + <arg name="local_pending" type="au"> + <tp:docstring> + A list of members who are pending local approval + </tp:docstring> + </arg> + <arg name="remote_pending" type="au"> + <tp:docstring> + A list of members who are pending remote approval + </tp:docstring> + </arg> + <arg name="actor" type="u"> + <tp:docstring> + The contact handle of the person who made the change, or 0 + if not known + </tp:docstring> + </arg> + <arg name="reason" type="u"> + <tp:docstring> + A reason for the change: one of the values of + ChannelGroupChangeReason + </tp:docstring> + </arg> <tp:docstring> Emitted when contacts join any of the three lists (members, local pending or remote pending). Contacts are listed in the removed list when they leave any of the three lists. There may also be a message from the server regarding this change, which may be displayed to the user if desired. - - The reason value will be one of the following: - 0 - CHANNEL_GROUP_CHANGE_REASON_NONE - No reason was provided for this change. - 1 - CHANNEL_GROUP_CHANGE_REASON_OFFLINE - The change is due to a user going offline. - 2 - CHANNEL_GROUP_CHANGE_REASON_KICKED - The change is due to a kick operation. - 3 - CHANNEL_GROUP_CHANGE_REASON_BUSY - The change is due to a busy indication. - 4 - CHANNEL_GROUP_CHANGE_REASON_INVITED - The change is due to an invitation. - 5 - CHANNEL_GROUP_CHANGE_REASON_BANNED - The change is due to a kick+ban operation. - 6 - CHANNEL_GROUP_CHANGE_REASON_ERROR - The change is due to an error occurring. - - Parameters: - message - a string message from the server, or blank if not - added - a list of members added to the channel - removed - a list of members removed from the channel - local_pending - a list of members who are pending local approval - remote_pending - a list of members who are pending remote approval - actor - the contact handle of the person who made the change, or 0 - if not known - reason - a reason for the change from one of the above values </tp:docstring> </signal> <method name="RemoveMembers"> - <arg direction="in" name="contacts" type="au"/> - <arg direction="in" name="message" type="s"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of contact handles to remove from the channel + </tp:docstring> + </arg> + <arg direction="in" name="message" type="s"> + <tp:docstring> + A string message, which can be blank if desired + </tp:docstring> + </arg> <tp:docstring> Requests the removal of contacts from a channel, reject their request for channel membership on the pending local list, or rescind their @@ -265,17 +359,17 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA CHANNEL_GROUP_FLAG_MESSAGE_REJECT and CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this message should be provided. - - Parameters: - contacts - an array of contact handles to remove from the channel - message - a string message, which can be blank if desired - - Possible Errors: - Disconnected, NetworkError, NotAvailable, PermissionDenied, InvalidHandle </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> </method> <tp:docstring> - Interface for channels which have multiple members, and where the members + Interface for channels which have multiple members, and where the members of the channel can change during its lifetime. Your presence in the channel cannot be presumed by the channel's existence (for example, a channel you may request membership of but your request may not be granted). diff --git a/spec/ChannelInterfaceHold.xml b/spec/ChannelInterfaceHold.xml index 87f82ce7..0a2cc502 100644 --- a/spec/ChannelInterfaceHold.xml +++ b/spec/ChannelInterfaceHold.xml @@ -6,7 +6,7 @@ Copyright (C) 2005, 2006 Nokia Corporation Copyright (C) 2006 INdT </tp:copyright> <tp:license> - This library is free software; you can redistribute it and/or +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. @@ -21,40 +21,43 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <tp:enum name="ChannelHoldState"> - <tp:enumvalue name="CHANNEL_HOLD_STATE_NONE" value="0"/> - <tp:enumvalue name="CHANNEL_HOLD_STATE_SEND_ONLY" value="1"/> - <tp:enumvalue name="CHANNEL_HOLD_STATE_RECV_ONLY" value="2"/> - <tp:enumvalue name="CHANNEL_HOLD_STATE_BOTH" value="3"/> - </tp:enum> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold" tp:name-const="CHANNEL_INTERFACE_HOLD"> - <method name="GetHoldState"> - <arg direction="in" name="member" type="u"/> - <arg direction="out" type="u"/> - <tp:docstring> - Given a member of the channel, return their current hold state. This - can be one of the following values: - 0 - CHANNEL_HOLD_STATE_NONE + <tp:enumvalue name="CHANNEL_HOLD_STATE_NONE" value="0"> Neither the local user and the remote member are on hold, and media is being sent bidirectionally. - 1 - CHANNEL_HOLD_STATE_SEND_ONLY + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_HOLD_STATE_SEND_ONLY" value="1"> The local user has put the remote member on hold, so is sending media but has arranged not to receive any media streams. - 2 - CHANNEL_HOLD_STATE_RECV_ONLY + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_HOLD_STATE_RECV_ONLY" value="2"> The user has been put on hold by the remote member, so is receiving media but has arranged not to send any media streams. - 3 - CHANNEL_HOLD_STATE_BOTH + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_HOLD_STATE_BOTH" value="3"> Both the local user and the remote member have agreed not to send any media streams to each other. - - Parameters: - member - the handle of a member of the channel - - Returns: - state - an integer representing the hold state, as defined above - - Potential Errors: - Disconnected, InvalidHandle + </tp:enumvalue> + </tp:enum> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold" tp:name-const="CHANNEL_INTERFACE_HOLD"> + <method name="GetHoldState"> + <arg direction="in" name="member" type="u"> + <tp:docstring> + The contact handle for a member of the channel + </tp:docstring> + </arg> + <arg direction="out" type="u"> + <tp:docstring> + The member's current hold state as one of the values of + ChannelHoldState + </tp:docstring> + </arg> + <tp:docstring> + Given a member of the channel, return their current hold state. </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> </method> <signal name="HoldStateChanged"> <arg name="member" type="u"/> @@ -72,20 +75,26 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <method name="RequestHold"> - <arg direction="in" name="member" type="u"/> - <arg direction="in" name="hold" type="b"/> + <arg direction="in" name="member" type="u"> + <tp:docstring> + The contact handle for a member of the channel + </tp:docstring> + </arg> + <arg direction="in" name="hold" type="b"> + <tp:docstring> + A boolean indicating whether or not the user should be on hold + </tp:docstring> + </arg> <tp:docstring> Request that a certain member be put on hold (be instructed not to send any media streams to you) or be taken off hold. Success is indicated by the HoldStateChanged signal being emitted. - - Parameters: - member - the integer handle of a member of the channel - hold - an boolean indicating whether or not the user should be on hold - - Potential Errors: - Disconnected, NetworkError, InvalidHandle </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.InvalidHandle"/> + </tp:possible-errors> </method> <tp:docstring> THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. Hold functionality diff --git a/spec/ChannelInterfaceMediaSignalling.xml b/spec/ChannelInterfaceMediaSignalling.xml index 32f890f7..696b8fcb 100644 --- a/spec/ChannelInterfaceMediaSignalling.xml +++ b/spec/ChannelInterfaceMediaSignalling.xml @@ -29,16 +29,20 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </method> <signal name="NewSessionHandler"> - <arg name="session_handler" type="o"/> - <arg name="type" type="s"/> + <arg name="session_handler" type="o"> + <tp:docstring> + Object path of the new MediaSessionHandler object + </tp:docstring> + </arg> + <arg name="type" type="s"> + <tp:docstring> + String indicating type of session, eg "rtp" + </tp:docstring> + </arg> <tp:docstring> Signal that a session handler object has been created. The client should create a session object and create streams for the streams within. - - Parameters: - session_handler - object path of the new MediaSessionHandler object - type - string indicating type of session, eg "rtp" </tp:docstring> </signal> <tp:docstring> diff --git a/spec/ChannelInterfacePassword.xml b/spec/ChannelInterfacePassword.xml index ca82dd46..b150c5ef 100644 --- a/spec/ChannelInterfacePassword.xml +++ b/spec/ChannelInterfacePassword.xml @@ -21,26 +21,30 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <tp:flags name="ChannelPasswordFlags"> - <tp:flag name="CHANNEL_PASSWORD_FLAG_PROVIDE" value="8"/> + <tp:flag name="CHANNEL_PASSWORD_FLAG_PROVIDE" value="8"> + <tp:docstring> + The ProvidePassword method must be called now for the user to join + the channel + </tp:docstring> + </tp:flag> </tp:flags> <interface name="org.freedesktop.Telepathy.Channel.Interface.Password" tp:name-const="CHANNEL_INTERFACE_PASSWORD"> <method name="GetPasswordFlags"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + An integer with the logical OR of all the flags set + (values of ChannelPasswordFlags) + </tp:docstring> + </arg> <tp:docstring> - Returns the logical OR of the flags relevant to the password on this + Returns the bitwise-OR of the flags relevant to the password on this channel. The user interface can use this to present information about which operations are currently valid. - - These can be: - 8 - CHANNEL_PASSWORD_FLAG_PROVIDE - the ProvidePassword method must be called now for the user to join the channel - - Returns: - an integer with the logical OR of all the flags set - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <signal name="PasswordFlagsChanged"> <arg name="added" type="u"/> @@ -55,22 +59,24 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <method name="ProvidePassword"> - <arg direction="in" name="password" type="s"/> - <arg direction="out" type="b"/> + <arg direction="in" name="password" type="s"> + <tp:docstring> + The password + </tp:docstring> + </arg> + <arg direction="out" type="b"> + A boolean indicating whether or not the password was correct + </arg> <tp:docstring> Provide the password so that the channel can be joined. Must be called with the correct password in order for channel joining to proceed if the 'provide' password flag is set. - - Parameters: - password - the password - - Returns: - a boolean indicating whether or not the password was correct - - Possible Errors: - Disconnected, NetworkError, InvalidArgument </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:possible-errors> </method> <tp:docstring> Interface for channels that may have a password set that users need diff --git a/spec/ChannelInterfaceTransfer.xml b/spec/ChannelInterfaceTransfer.xml index c965b622..9dab504d 100644 --- a/spec/ChannelInterfaceTransfer.xml +++ b/spec/ChannelInterfaceTransfer.xml @@ -22,19 +22,27 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.Transfer" tp:name-const="CHANNEL_INTERFACE_TRANSFER"> <method name="Transfer"> - <arg direction="in" name="member" type="u"/> - <arg direction="in" name="destination" type="u"/> + <arg direction="in" name="member" type="u"> + <tp:docstring> + The handle of the member to transfer + </tp:docstring> + </arg> + <arg direction="in" name="destination" type="u"> + <tp:docstring> + The handle of the destination contact + </tp:docstring> + </arg> <tp:docstring> Request that the given channel member instead connects to a different contact ID. - - Parameters: - member - the handle of the member to transfer - destination - the handle of the destination contact - - Possible Errors: - Disconnected, NetworkError, NotAvailable, InvalidHandle, PermissionDenied </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <tp:docstring> An interface for channels where you may request that one of the members diff --git a/spec/ChannelTypeContactSearch.xml b/spec/ChannelTypeContactSearch.xml index e571f22a..51bf069c 100644 --- a/spec/ChannelTypeContactSearch.xml +++ b/spec/ChannelTypeContactSearch.xml @@ -22,8 +22,18 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch" tp:name-const="CHANNEL_TYPE_CONTACT_SEARCH"> <method name="GetSearchKeys"> - <arg direction="out" type="s"/> - <arg direction="out" type="a{s(bg)}"/> + <arg direction="out" type="s"> + <tp:docstring> + A string with any instructions from the server + </tp:docstring> + </arg> + <arg direction="out" type="a{s(bg)}"> + <tp:docstring> + A dictionary mapping string search key names to an array of: + - booleans indicating if the search key is mandatory + - type signature of the value for this search key + </tp:docstring> + </arg> <tp:docstring> Returns any instructions from the server along with a dictionary of search key names to their types, and a boolean indicating if the key is @@ -33,71 +43,68 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA s:last - the desired contact's family name s:nick - the desired contact's nickname s:email - the e-mail address of the desired contact - - Returns: - a string with any instructions from the server - a dictionary mapping string search key names to an array of: - booleans indicating if the search key is mandatory - type signature of the value for this search key - - Possible Errors: - Disconnected, NetworkError, NotAvailable </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.NotAvailable"/> + </tp:possible-errors> </method> <tp:enum name="ChannelContactSearchState"> - <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_BEFORE" value="0"/> - <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_DURING" value="1"/> - <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_AFTER" value="2"/> + <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_BEFORE" value="0"> + <tp:docstring>The search has not started</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_DURING" value="1"> + <tp:docstring>The search is in progress</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_CONTACT_SEARCH_STATE_AFTER" value="2"> + <tp:docstring>The search has been completed</tp:docstring> + </tp:enumvalue> </tp:enum> <method name="GetSearchState"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring>The search state represented as one of the values of + ChannelContactSearchState</tp:docstring> + </arg> <tp:docstring> - Returns the current state of this search channel object. One of the - following values: - 0 - CHANNEL_CONTACT_SEARCH_STATE_BEFORE - the search has not started - 1 - CHANNEL_CONTACT_SEARCH_STATE_DURING - the search is in progress - 2 - CHANNEL_CONTACT_SEARCH_STATE_AFTER - the search has been completed - - Returns: - an integer representing the search state + Returns the current state of this search channel object. </tp:docstring> </method> <method name="Search"> - <arg direction="in" name="terms" type="a{sv}"/> + <arg direction="in" name="terms" type="a{sv}"> + <tp:docstring> + A dictionary mapping search key names to the desired values + </tp:docstring> + </arg> <tp:docstring> Send a request to start a search for contacts on this connection. A valid search request will cause the SearchStateChanged signal to be emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING. - - Parameters: - a dictionary mapping search key names to the desired values - - Possible Errors: - Disconnected, NetworkError, InvalidArgument </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:possible-errors> </method> <signal name="SearchResultReceived"> - <arg name="contact" type="u"/> - <arg name="values" type="a{sv}"/> + <arg name="contact" type="u"> + <tp:docstring>An integer handle for the contact</tp:docstring> + </arg> + <arg name="values" type="a{sv}"> + <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring> + </arg> <tp:docstring> Emitted when a search result is received from the server. - - Parameters: - an integer handle for the contact - a dictionary mapping search key names to values for this contact </tp:docstring> </signal> <signal name="SearchStateChanged"> - <arg name="state" type="u"/> + <arg name="state" type="u"> + <tp:docstring>An integer representing the new search state</tp:docstring> + </arg> <tp:docstring> Emitted when the search state (as returned by the GetSearchState method) changes. - - Parameters: - state - an integer representing the new search state </tp:docstring> </signal> <tp:docstring> diff --git a/spec/ChannelTypeRoomList.xml b/spec/ChannelTypeRoomList.xml index 21c67b1e..5fb203d2 100644 --- a/spec/ChannelTypeRoomList.xml +++ b/spec/ChannelTypeRoomList.xml @@ -22,17 +22,25 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.RoomList" tp:name-const="CHANNEL_TYPE_ROOM_LIST"> <method name="GetListingRooms"> - <arg direction="out" type="b"/> + <arg direction="out" type="b"> + <tp:docstring> + A boolean indicating if room listing is in progress + </tp:docstring> + </arg> <tp:docstring> Check to see if there is already a room list request in progress on this channel. - - Returns: - a boolean indicating if room listing is in progress </tp:docstring> </method> <signal name="GotRooms"> - <arg name="rooms" type="a(usa{sv})"/> + <arg name="rooms" type="a(usa{sv})"> + <tp:docstring> + An array of structs containing: + - an integer room handle + - a string representing the D-Bus interface name of the channel type + - a dictionary mapping string keys to variant boxed information + </tp:docstring> + </arg> <tp:docstring> Emitted when information about rooms on the server becomes available. The array contains the room handle (as can be passed to the @@ -45,12 +53,6 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA u:members - the number of members of the room b:password - true if the room requires a password to enter b:invite-only - true if you cannot join the room, but must be invited - - Parameters: - rooms - an array of structs containing: - an integer room handle - a string representing the D-Bus interface name of the channel type - an dictionary mapping string keys to variant boxed information </tp:docstring> </signal> <method name="ListRooms"> @@ -59,19 +61,21 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA should be emitted when this request is being processed, GotRooms when any room information is received, and ListingRooms when the request is complete. - - Possible Errors: - Disconnected, NetworkError, NotAvailable, PermissionDenied </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <signal name="ListingRooms"> - <arg name="listing" type="b"/> + <arg name="listing" type="b"> + <tp:docstring>A boolean indicating if room listing is in progress</tp:docstring> + </arg> <tp:docstring> Emitted to indicate whether or not room listing request is currently in progress. - - Parameters: - listing - a boolean indicating if room listing is in progress </tp:docstring> </signal> <tp:docstring> diff --git a/spec/ChannelTypeStreamedMedia.xml b/spec/ChannelTypeStreamedMedia.xml index 9726db3c..0e344e3d 100644 --- a/spec/ChannelTypeStreamedMedia.xml +++ b/spec/ChannelTypeStreamedMedia.xml @@ -22,86 +22,101 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia" tp:name-const="CHANNEL_TYPE_STREAMED_MEDIA"> <tp:enum name="MediaStreamType"> - <tp:enumvalue name="MEDIA_STREAM_TYPE_AUDIO" value="0"/> - <tp:enumvalue name="MEDIA_STREAM_TYPE_VIDEO" value="1"/> + <tp:enumvalue name="MEDIA_STREAM_TYPE_AUDIO" value="0"> + An audio stream + <tp:docstring></tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_TYPE_VIDEO" value="1"> + A video stream + <tp:docstring></tp:docstring> + </tp:enumvalue> </tp:enum> <tp:enum name="MediaStreamState"> - <tp:enumvalue name="MEDIA_STREAM_STATE_DISCONNECTED" value="0"/> - <tp:enumvalue name="MEDIA_STREAM_STATE_CONNECTING" value="1"/> - <tp:enumvalue name="MEDIA_STREAM_STATE_CONNECTED" value="2"/> + <tp:enumvalue name="MEDIA_STREAM_STATE_DISCONNECTED" value="0"> + <tp:docstring>The stream is disconnected.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_STATE_CONNECTING" value="1"> + <tp:docstring>The stream is trying to connect.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_STATE_CONNECTED" value="2"> + <tp:docstring>The stream is connected.</tp:docstring> + </tp:enumvalue> </tp:enum> <tp:enum name="MediaStreamDirection"> - <tp:enumvalue name="MEDIA_STREAM_DIRECTION_NONE" value="0"/> - <tp:enumvalue name="MEDIA_STREAM_DIRECTION_SEND" value="1"/> - <tp:enumvalue name="MEDIA_STREAM_DIRECTION_RECEIVE" value="2"/> - <tp:enumvalue name="MEDIA_STREAM_DIRECTION_BIDIRECTIONAL" value="3"/> + <tp:enumvalue name="MEDIA_STREAM_DIRECTION_NONE" value="0"> + <tp:docstring>Media are not being sent or received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_DIRECTION_SEND" value="1"> + <tp:docstring>Media are being sent, but not received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_DIRECTION_RECEIVE" value="2"> + <tp:docstring>Media are being received, but not sent</tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="MEDIA_STREAM_DIRECTION_BIDIRECTIONAL" value="3"> + <tp:docstring>Media are being sent and received</tp:docstring> + </tp:enumvalue> </tp:enum> <tp:flags name="MediaStreamPendingFlags"> - <tp:flag name="MEDIA_STREAM_PENDING_LOCAL_SEND" value="1"/> - <tp:flag name="MEDIA_STREAM_PENDING_REMOTE_SEND" value="2"/> - </tp:flags> - <method name="ListStreams"> - <arg direction="out" type="a(uuuuuu)"/> - <tp:docstring> - Returns an array of structs representing the streams currently active - within this channel. Each stream is identified by an unsigned integer - which is unique for each stream within the channel. - - Stream types are identified by the following values: - MEDIA_STREAM_TYPE_AUDIO = 0 - MEDIA_STREAM_TYPE_VIDEO = 1 - - Stream states are identified by one of the following values: - MEDIA_STREAM_STATE_DISCONNECTED = 0 - The stream is disconnected. - MEDIA_STREAM_STATE_CONNECTING = 1 - The stream is trying to connect. - MEDIA_STREAM_STATE_CONNECTED = 2 - The stream is connected. - - Stream directions are identified by one of the following values: - MEDIA_STREAM_DIRECTION_NONE = 0 - MEDIA_STREAM_DIRECTION_SEND = 1 - MEDIA_STREAM_DIRECTION_RECEIVE = 2 - MEDIA_STREAM_DIRECTION_BIDIRECTIONAL = 3 - - Pending directionality changes are indicated by a bitwise OR of the - following flags: - MEDIA_STREAM_PENDING_LOCAL_SEND = 1 + <tp:flag name="MEDIA_STREAM_PENDING_LOCAL_SEND" value="1"> + <tp:docstring> The local user has been asked to send media by the remote user. Call RequestStreamDirection to indicate whether or not this is acceptable. - MEDIA_STREAM_PENDING_REMOTE_SEND = 2 + </tp:docstring> + </tp:flag> + <tp:flag name="MEDIA_STREAM_PENDING_REMOTE_SEND" value="2"> + <tp:docstring> The remote user has been asked to send media by the local user. The StreamDirectionChanged signal will be emitted when the remote user accepts or rejects this change. - - Returns: - an array of structs containing: - the stream identifier - the contact handle who the stream is with (or 0 if the stream + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="ListStreams"> + <arg direction="out" type="a(uuuuuu)"> + <tp:docstring> + An array of structs containing: + - the stream identifier + - the contact handle who the stream is with (or 0 if the stream represents more than a single member) - the type of the stream - the current stream state - the current direction of the stream - the current pending send flags + - the type of the stream + - the current stream state + - the current direction of the stream + - the current pending send flags + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of structs representing the streams currently active + within this channel. Each stream is identified by an unsigned integer + which is unique for each stream within the channel. </tp:docstring> </method> <method name="RemoveStreams"> - <arg direction="in" name="streams" type="au"/> + <arg direction="in" name="streams" type="au"> + <tp:docstring> + An array of stream identifiers (as defined in ListStreams) + </tp:docstring> + </arg> <tp:docstring> Request that the given streams are removed. - - Parameters: - streams - an array of stream identifiers (as defined in ListStreams) - - Possible Errors: - InvalidArgument (unknown stream identifier) </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + A stream identifier is unknown + </tp:error> + </tp:possible-errors> </method> <method name="RequestStreamDirection"> - <arg direction="in" name="stream_id" type="u"/> - <arg direction="in" name="stream_direction" type="u"/> + <arg direction="in" name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </tp:docstring> + </arg> + <arg direction="in" name="stream_direction" type="u"> + <tp:docstring> + The desired stream direction (a value of MediaStreamDirection) + </tp:docstring> + </arg> <tp:docstring> Request a change in the direction of an existing stream. In particular, this might be useful to stop sending media of a particular type, @@ -117,21 +132,40 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA flag will be set in the StreamDirectionChanged signal, and the signal emitted again without the flag to indicate the resulting direction when the remote end has accepted or rejected the change. - - Parameters: - stream_id - the stream identifier (as defined in ListStreams) - stream_direction - the desired stream direction (as defined in - ListStreams) - - PossibleErrors: - InvalidArgument (unknown stream ID), NotAvailable (the requested - direction is not available on this stream) </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + A stream identifier is unknown + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The requested direction is not available on this stream + </tp:error> + </tp:possible-errors> </method> <method name="RequestStreams"> - <arg direction="in" name="contact_handle" type="u"/> - <arg direction="in" name="types" type="au"/> - <arg direction="out" type="a(uuuuuu)"/> + <arg direction="in" name="contact_handle" type="u"> + <tp:docstring> + A contact handle with whom to establish the streams + </tp:docstring> + </arg> + <arg direction="in" name="types" type="au"> + <tp:docstring> + An array of stream types (values of MediaStreamType) + </tp:docstring> + </arg> + <arg direction="out" type="a(uuuuuu)"> + <tp:docstring> + An array of structs (in the same order as the given stream types) + containing: + - the stream identifier + - the contact handle who the stream is with (or 0 if the stream + represents more than a single member) + - the type of the stream + - the current stream state + - the current direction of the stream + - the current pending send flags + </tp:docstring> + </arg> <tp:docstring> Request that streams be established to exchange the given types of media with the given member. In general this will try and establish a @@ -142,46 +176,51 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA them), the StreamDirectionChanged signal will be emitted with the MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied. - - Parameters: - contact_handle - a contact handle with whom to establish the streams - types - an array of stream types (as defined in ListStreams) - - Returns: - an array of structs (in the same order as the given stream types) - containing: - the stream identifier - the contact handle who the stream is with (or 0 if the stream - represents more than a single member) - the type of the stream - the current stream state - the current direction of the stream - the current pending send flags - - Possible Errors: - InvalidHandle, InvalidArgument (invalid stream type), NotAvailable (if - the contact is not able to do this stream type) </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + A stream type given is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + That contact is not able to do this stream type + </tp:error> + </tp:possible-errors> </method> <signal name="StreamAdded"> - <arg name="stream_id" type="u"/> - <arg name="contact_handle" type="u"/> - <arg name="stream_type" type="u"/> + <arg name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </tp:docstring> + </arg> + <arg name="contact_handle" type="u"> + <tp:docstring> + The contact handle who the stream is with (or 0 if it + represents more than a single member) + </tp:docstring> + </arg> + <arg name="stream_type" type="u"> + <tp:docstring> + The stream type (a value from MediaStreamType) + </tp:docstring> + </arg> <tp:docstring> Emitted when a new stream has been added to this channel. - - Parameters: - stream_id - the stream identifier (as defined in ListStreams) - contact_handle - the contact handle who the stream is with (or 0 if it - represents more than a single member) - stream_type - the stream type (as defined in ListStreams) - stream_direction - the stream direction (as defined in ListStreams) </tp:docstring> </signal> <signal name="StreamDirectionChanged"> - <arg name="stream_id" type="u"/> - <arg name="stream_direction" type="u"/> - <arg name="pending_flags" type="u"/> + <arg name="stream_id" type="u"> + <tp:docstring> + </tp:docstring> + </arg> + <arg name="stream_direction" type="u"> + <tp:docstring> + </tp:docstring> + </arg> + <arg name="pending_flags" type="u"> + <tp:docstring> + </tp:docstring> + </arg> <tp:docstring> Emitted when the direction or pending flags of a stream are changed. If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has @@ -195,9 +234,18 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <signal name="StreamError"> - <arg name="stream_id" type="u"/> - <arg name="errno" type="u"/> - <arg name="message" type="s"/> + <arg name="stream_id" type="u"> + <tp:docstring> + </tp:docstring> + </arg> + <arg name="errno" type="u"> + <tp:docstring> + </tp:docstring> + </arg> + <arg name="message" type="s"> + <tp:docstring> + </tp:docstring> + </arg> <tp:docstring> Emitted when a stream encounters an error. @@ -212,7 +260,10 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <signal name="StreamRemoved"> - <arg name="stream_id" type="u"/> + <arg name="stream_id" type="u"> + <tp:docstring> + </tp:docstring> + </arg> <tp:docstring> Emitted when a stream has been removed from this channel. @@ -221,8 +272,14 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <signal name="StreamStateChanged"> - <arg name="stream_id" type="u"/> - <arg name="stream_state" type="u"/> + <arg name="stream_id" type="u"> + <tp:docstring> + </tp:docstring> + </arg> + <arg name="stream_state" type="u"> + <tp:docstring> + </tp:docstring> + </arg> <tp:docstring> Emitted when a member's stream's state changes. @@ -244,16 +301,24 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA handled by specialised hardware which is controlled directly by the connection manager), the signalling interface can be omitted and this channel type used simply to control the streams. - - This channel type defines two type-specific capability flags (as used in - Connection.Interface.Capabilities): - CHANNEL_MEDIA_CAPABILITY_AUDIO = 1 - The handle is capable of using audio streams within a media channel. - CHANNEL_MEDIA_CAPABILITY_VIDEO = 2 - The handle is capable of using video streams within a media channel. </tp:docstring> - <tp:flag name="CHANNEL_MEDIA_CAPABILITY_AUDIO" value="1"/> - <tp:flag name="CHANNEL_MEDIA_CAPABILITY_VIDEO" value="2"/> + <tp:flags name="ChannelMediaCapability"> + <tp:docstring> + The channel-type-specific capability flags used for + Channel.Type.StreamedMedia in the Connection.Interface.Capabilities + interface. + </tp:docstring> + <tp:flag name="CHANNEL_MEDIA_CAPABILITY_AUDIO" value="1"> + <tp:docstring> + The handle is capable of using audio streams within a media channel. + </tp:docstring> + </tp:flag> + <tp:flag name="CHANNEL_MEDIA_CAPABILITY_VIDEO" value="2"> + <tp:docstring> + The handle is capable of using video streams within a media channel. + </tp:docstring> + </tp:flag> + </tp:flags> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/ChannelTypeText.xml b/spec/ChannelTypeText.xml index 14b5a97b..b6daf907 100644 --- a/spec/ChannelTypeText.xml +++ b/spec/ChannelTypeText.xml @@ -22,46 +22,52 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.Text" tp:name-const="CHANNEL_TYPE_TEXT"> <method name="AcknowledgePendingMessages"> - <arg direction="in" name="ids" type="au"/> + <arg direction="in" name="ids" type="au"> + <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. - - Parameters: - ids - the message to acknowledge - - Possible Errors: - InvalidArgument (a given message ID was not found, no action taken) </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + A given message ID was not found, so no action was taken + </tp:error> + </tp:possible-errors> </method> <method name="GetMessageTypes"> - <arg direction="out" type="au"/> + <arg direction="out" type="au"> + <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. - - Returns: - an array of integer message types as defined above </tp:docstring> </method> <method name="ListPendingMessages"> - <arg direction="in" name="clear" type="b"/> - <arg direction="out" type="a(uuuuus)"/> + <arg direction="in" name="clear" type="b"> + <tp:docstring> + If true, remove all messages from the queue + </tp:docstring> + </arg> + <arg direction="out" type="a(uuuuus)"> + <tp:docstring> + 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 + </tp:docstring> + </arg> <tp:docstring> List the messages currently in the pending queue, and optionally remove then all. - - Parameters: - clear - a boolean indicating whether the queue should be cleared - - Returns: - an array of structs containing: - a numeric identifier - a unix timestamp indicating when the message was received - an integer handle of the contact who sent the message - an integer of the message type - a bitwise OR of the message flags - a string of the text of the message </tp:docstring> </method> <signal name="LostMessage"> @@ -72,102 +78,156 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </signal> <signal name="Received"> - <arg name="id" type="u"/> - <arg name="timestamp" type="u"/> - <arg name="sender" type="u"/> - <arg name="type" type="u"/> - <arg name="flags" type="u"/> - <arg name="text" type="s"/> + <arg name="id" type="u"> + <tp:docstring> + A numeric identifier for acknowledging the message + </tp:docstring> + </arg> + <arg name="timestamp" type="u"> + <tp:docstring> + A Unix timestamp indicating when the message was received + </tp:docstring> + </arg> + <arg name="sender" type="u"> + <tp:docstring> + The handle of the contact who sent the message + </tp:docstring> + </arg> + <arg name="type" type="u"> + <tp:docstring> + The type of the message (normal, action, notice, etc), from + ChannelTextMessageType + </tp:docstring> + </arg> + <arg name="flags" type="u"> + <tp:docstring> + A bitwise OR of the message flags as defined by ChannelTextMessageFlags + </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 AcknowledgePendingMessage method. - - Parameters: - id - a numeric identifier for acknowledging the message - timestamp - a unix timestamp indicating when the message was received - sender - the handle of the contact who sent the message - type - the type of the message (normal, action, notice, etc) - flags - a bitwise OR of the message flags as defined above - text - the text of the message </tp:docstring> </signal> <method name="Send"> - <arg direction="in" name="type" type="u"/> - <arg direction="in" name="text" type="s"/> + <arg direction="in" name="type" type="u"> + <tp:docstring> + An integer indicating the type of the message, from + ChannelTextMessageType + </tp:docstring> + </arg> + <arg direction="in" name="text" type="s"> + <tp:docstring> + The message to send + </tp:docstring> + </arg> <tp:docstring> Request that a message be sent on this channel. The Sent signal will be emitted when the message has been sent, and this method will return. - - Parameters: - type - an integer indicating the type of the message - text - the message to send - - Possible Errors: - Disconnected, NetworkError, InvalidArgument, PermissionDenied </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="ChannelTextSendError"> - <tp:enumvalue name="CHANNEL_SEND_ERROR_UNKNOWN" value="0"/> - <tp:enumvalue name="CHANNEL_SEND_ERROR_OFFLINE" value="1"/> - <tp:enumvalue name="CHANNEL_SEND_ERROR_INVALID_CONTACT" value="2"/> - <tp:enumvalue name="CHANNEL_SEND_ERROR_PERMISSION_DENIED" value="3"/> - <tp:enumvalue name="CHANNEL_SEND_ERROR_TOO_LONG" value="4"/> - <tp:enumvalue name="CHANNEL_SEND_ERROR_NOT_IMPLEMENTED" value="5"/> + <tp:enumvalue name="CHANNEL_SEND_ERROR_UNKNOWN" value="0"> + An unknown error occurred + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_SEND_ERROR_OFFLINE" value="1"> + The requested contact was offline + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_SEND_ERROR_INVALID_CONTACT" value="2"> + The requested contact is not valid + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_SEND_ERROR_PERMISSION_DENIED" value="3"> + The user does not have permission to speak on this channel + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_SEND_ERROR_TOO_LONG" value="4"> + The outgoing message was too long and was rejected by the server + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_SEND_ERROR_NOT_IMPLEMENTED" value="5"> + The channel doesn't support sending text messages to the requested + contact + </tp:enumvalue> </tp:enum> <signal name="SendError"> - <arg name="error" type="u"/> - <arg name="timestamp" type="u"/> - <arg name="type" type="u"/> - <arg name="text" type="s"/> + <arg name="error" type="u"> + <tp:docstring> + One of the values of ChannelTextSendError + </tp:docstring> + </arg> + <arg name="timestamp" type="u"> + <tp:docstring> + The Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="type" type="u"> + <tp:docstring> + The message type from ChannelTextMessageType + </tp:docstring> + </arg> + <arg name="text" type="s"> + <tp:docstring> + The text of the message + </tp:docstring> + </arg> <tp:docstring> Signals that an outgoing message has failed to send. The error - will be one of the following values: - 0 - CHANNEL_TEXT_SEND_ERROR_UNKNOWN - An unknown error occured. - 1 - CHANNEL_TEXT_SEND_ERROR_OFFLINE - The requested contact was offline. - 2 - CHANNEL_TEXT_SEND_ERROR_INVALID_CONTACT - The requested contact is not valid. - 3 - CHANNEL_TEXT_SEND_ERROR_PERMISSION_DENIED - The user does not have permission to speak on this channel. - 4 - CHANNEL_TEXT_SEND_ERROR_TOO_LONG - The outgoing message was too long and was rejected by the - server. - 5 - CHANNEL_TEXT_SEND_ERROR_NOT_IMPLEMENTED - The channel doesn't support sending text messages to requested - contact. - - Parameters: - error - one of the above integer errors - timestamp - the unix timestamp indicating when the message was sent - type - the message the (normal, action, notice, etc) - text - the text of the message + will be one of the values from ChannelTextSendError. </tp:docstring> </signal> <signal name="Sent"> - <arg name="timestamp" type="u"/> - <arg name="type" type="u"/> - <arg name="text" type="s"/> + <arg name="timestamp" type="u"> + <tp:docstring> + Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="type" type="u"> + <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 + </tp:docstring> + </arg> <tp:docstring> Signals that a message has been sent on this channel. - - Parameters: - timestamp - the unix timestamp indicating when the message was sent - type - the message type (normal, action, notice, etc) - text - the text of the message </tp:docstring> </signal> <tp:enum name="ChannelTextMessageType"> - <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_NORMAL" value="0"/> - <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_ACTION" value="1"/> - <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_NOTICE" value="2"/> - <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_AUTO_REPLY" value="3"/> + <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_NORMAL" value="0"> + A standard message + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_ACTION" value="1"> + An action which might be presented to the user as + "* <sender> <action>" + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_NOTICE" value="2"> + A one-off or automated message not necessarily expecting a reply + </tp:enumvalue> + <tp:enumvalue name="CHANNEL_TEXT_MESSAGE_TYPE_AUTO_REPLY" value="3"> + An automatically-generated reply message + </tp:enumvalue> </tp:enum> <tp:flags name="ChannelTextMessageFlags"> - <tp:flag name="CHANNEL_TEXT_MESSAGE_FLAG_TRUNCATED" value="1"/> + <tp:flag name="CHANNEL_TEXT_MESSAGE_FLAG_TRUNCATED" value="1"> + The incoming message was truncated to a shorter length by the + server or the connection manager. + </tp:flag> </tp:flags> <tp:docstring> A channel type for sending and receiving messages in plain text, with no @@ -182,21 +242,10 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA over the lifetime of the channel. Each message has an associated 'type' value, which should be one of the - following: - 0 - CHANNEL_TEXT_MESSAGE_TYPE_NORMAL - a standard message - 1 - CHANNEL_TEXT_MESSAGE_TYPE_ACTION - an action which might be presented to the user as * <sender> <action> - 2 - CHANNEL_TEXT_MESSAGE_TYPE_NOTICE - an one-off or automated message not necessarily expecting a reply - 3 - CHANNEL_TEXT_MESSAGE_TYPE_AUTO_REPLY - an automatically-generated reply message + values allowed by ChannelTextMessageType. Each message also has a flags value, which is a bitwise OR of the - following: - 1 - CHANNEL_TEXT_MESSAGE_FLAG_TRUNCATED - The incoming message was truncated to a shorter length by the - server or the connection manager. + flags given in ChannelTextMessageFlags. Sending messages can be requested using the Send method, which will return and cause the Sent signal to be emitted when the message has been delivered diff --git a/spec/Connection.xml b/spec/Connection.xml index 794d0006..027b6914 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -26,10 +26,12 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals. - - Potential Errors: - NotAvailable (the connection is already connecting or connected) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The connection is already connecting or connected + </tp:error> + </tp:potential-errors> </method> <method name="Disconnect"> <tp:docstring> @@ -39,49 +41,61 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </method> <method name="GetInterfaces"> - <arg direction="out" type="as"/> + <arg direction="out" type="as"> + <tp:docstring> + An array of D-Bus interface names + </tp:docstring> + </arg> <tp:docstring> Get the optional interfaces supported by this connection. - - Returns: - an array of D-Bus interface names </tp:docstring> </method> <method name="GetProtocol"> - <arg direction="out" type="s"/> + <arg direction="out" type="s"> + <tp:docstring> + A string identifier for the protocol + </tp:docstring> + </arg> <tp:docstring> Get the protocol this connection is using. - - Returns: - a string identifier for the protocol </tp:docstring> </method> <method name="GetSelfHandle"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + An integer handle representing the user + </tp:docstring> + </arg> <tp:docstring> Get the handle which represents the user on this connection, which will remain valid for the lifetime of this connection or until the user's identifier changes. This is always a CONTACT type handle. - - Returns: - an integer handle representing the user - - Potential Errors: - Disconnected </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:potential-errors> </method> <method name="GetStatus"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + An integer representing the current status + </tp:docstring> + </arg> <tp:docstring> Get the current status as defined in the StatusChanged signal. - - Returns: - an integer representing the current status </tp:docstring> </method> <method name="HoldHandles"> - <arg direction="in" name="handle_type" type="u"/> - <arg direction="in" name="handles" type="au"/> + <arg direction="in" name="handle_type" type="u"> + <tp:docstring> + An integer handle type (as defined in ConnectionHandleType) + </tp:docstring> + </arg> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + A array of integer handles to hold + </tp:docstring> + </arg> <tp:docstring> Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or @@ -91,97 +105,153 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the ReleaseHandle method is called, or the clients disappear from the bus. - - Parameters: - handle_type - an integer handle type (as defined in RequestHandle) - handle - a array of integer handles to hold - - Potential Errors: - Disconnected, InvalidArgument (the handle type is invalid), - InvalidHandle (the given handle is not valid) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + </tp:potential-errors> </method> <method name="InspectHandles"> - <arg direction="in" name="handle_type" type="u"/> - <arg direction="in" name="handles" type="au"/> - <arg direction="out" type="as"/> + <arg direction="in" name="handle_type" type="u"> + <tp:docstring> + An integer handle type (as defined in ConnectionHandleType) + </tp:docstring> + </arg> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + An array of integer handles of this type + </tp:docstring> + </arg> + <arg direction="out" type="as"> + <tp:docstring> + An array of handle names in the same order as the given numbers + </tp:docstring> + </arg> <tp:docstring> Return a string representation for a number of handles of a given type. - - Parameters: - handle_type - an integer handle type (as defined in RequestHandles) - handles - an array of integer handles of this type - - Returns: - an array of handle names in the same order as the given numbers - - Potential Errors: - Disconnected, InvalidArgument (the given type is not valid), - InvalidHandle (a given handle is not valid on this connection) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + </tp:potential-errors> </method> <method name="ListChannels"> - <arg direction="out" type="a(osuu)"/> + <arg direction="out" type="a(osuu)"> + <tp:docstring> + An array of structs containing: + - a D-Bus object path for the channel object on this service + - a D-Bus interface name representing the channel type + - an integer representing the handle type this channel communicates with, or zero + - an integer handle representing the contact, room or list this channel communicates with, or zero + </tp:docstring> + </arg> <tp:docstring> List all the channels which currently exist on this connection. - - Returns: - an array of structs containing: - a D-Bus object path for the channel object on this service - a D-Bus interface name representing the channel type - an integer representing the handle type this channel communicates with, or zero - an integer handle representing the contact, room or list this channel communicates with, or zero - - Potential Errors: - Disconnected </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:potential-errors> </method> <signal name="NewChannel"> - <arg name="object_path" type="o"/> - <arg name="channel_type" type="s"/> - <arg name="handle_type" type="u"/> - <arg name="handle" type="u"/> - <arg name="suppress_handler" type="b"/> + <arg name="object_path" type="o"> + <tp:docstring> + A D-Bus object path for the channel object on this service + </tp:docstring> + </arg> + <arg name="channel_type" type="s"> + <tp:docstring> + A D-Bus interface name representing the channel type + </tp:docstring> + </arg> + <arg name="handle_type" type="u"> + <tp:docstring> + An integer representing the type of handle this channel communicates with, which is zero if no handle is specified + </tp:docstring> + </arg> + <arg name="handle" type="u"> + <tp:docstring> + A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel + </tp:docstring> + </arg> + <arg name="suppress_handler" type="b"> + <tp:docstring> + A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched + </tp:docstring> + </arg> <tp:docstring> Emitted when a new Channel object is created, either through user request or incoming information from the service. The suppress_handler boolean indicates if the channel was requested by an existing client, or is an incoming communication and needs to have a handler launched. - - Parameters: - object_path - a D-Bus object path for the channel object on this service - channel_type - a D-Bus interface name representing the channel type - handle_type - an integer representing the type of handle this channel communicates with, which is zero if no handle is specified - handle - a handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel - suppress_handler - a boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched </tp:docstring> </signal> <method name="ReleaseHandles"> - <arg direction="in" name="handle_type" type="u"/> - <arg direction="in" name="handles" type="au"/> + <arg direction="in" name="handle_type" type="u"> + <tp:docstring> + An integer handle type (as defined in RequestHandle) + </tp:docstring> + </arg> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + An array of integer handles being held by the client + </tp:docstring> + </arg> <tp:docstring> Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. - - Parameters: - handle_type - an integer handle type (as defined in RequestHandle) - handle - an array of integer handles being held by the client - - Potential Errors: - Disconnected, InvalidArgument (the given handle type is invalid), - InvalidHandle (the given handle is not valid), NotAvailable (the given - handle is not held by this client) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + One of the given handles is not held by this client + </tp:error> + </tp:potential-errors> </method> <method name="RequestChannel"> - <arg direction="in" name="type" type="s"/> - <arg direction="in" name="handle_type" type="u"/> - <arg direction="in" name="handle" type="u"/> - <arg direction="in" name="suppress_handler" type="b"/> - <arg direction="out" type="o"/> + <arg direction="in" name="type" type="s"> + <tp:docstring> + A D-Bus interface name representing base channel type + </tp:docstring> + </arg> + <arg direction="in" name="handle_type" type="u"> + <tp:docstring> + An integer representing the handle type, or zero if no handle is being specified + </tp:docstring> + </arg> + <arg direction="in" name="handle" type="u"> + <tp:docstring> + An integer handle representing a contact, room or list, or zero + </tp:docstring> + </arg> + <arg direction="in" name="suppress_handler" type="b"> + <tp:docstring> + A boolean indicating that the requesting client intends to take responsibility for displaying the channel to the user, so that no other handler needs to be launched + </tp:docstring> + </arg> + <arg direction="out" type="o"> + <tp:docstring> + The D-Bus object path for the channel created or retrieved + </tp:docstring> + </arg> <tp:docstring> Request a channel satisfying the specified type and communicating with the contact, room or list indicated by the given handle. The handle may @@ -190,33 +260,78 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA return an existing channel object, create a new channel, or fail if the request cannot be satisfied. - Parameters: - type - a D-Bus interface name representing base channel type - handle_type - an integer representing the handle type, or zero if no handle is being specified - handle - an integer handle representing a contact, room or list, or zero - suppress_handler - a boolean indicating that the requesting client intends to take responsibility for displaying the channel to the user, so that no other handler needs to be launched - - Returns: - the D-Bus object path for the channel created or retrieved - Possible Errors: Disconnected, NetworkError, NotImplemented (unknown channel type), InvalidHandle (the given handle does not exist or cannot be created), NotAvailable (the requested channel type cannot be created with the given handle), Channel.Banned, Channel.Full, Channel.InviteOnly </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Unknown channel type + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The given handle does not exist or cannot be created + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel type cannot be created with the given handle + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + </tp:potential-errors> </method> <tp:enum name="ConnectionHandleType"> - <tp:enumvalue name="CONNECTION_HANDLE_TYPE_NONE" value="0"/> - <tp:enumvalue name="CONNECTION_HANDLE_TYPE_CONTACT" value="1"/> - <tp:enumvalue name="CONNECTION_HANDLE_TYPE_ROOM" value="2"/> - <tp:enumvalue name="CONNECTION_HANDLE_TYPE_LIST" value="3"/> - <tp:enumvalue name="CONNECTION_HANDLE_TYPE_GROUP" value="4"/> + <tp:enumvalue name="CONNECTION_HANDLE_TYPE_NONE" value="0"> + <tp:docstring> + A "null" handle type used to indicate the absence of a handle + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_HANDLE_TYPE_CONTACT" value="1"> + <tp:docstring> + A contact + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_HANDLE_TYPE_ROOM" value="2"> + <tp:docstring> + A chat room + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_HANDLE_TYPE_LIST" value="3"> + <tp:docstring> + A server-generated contact list (see Channel.Interface.Group) + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_HANDLE_TYPE_GROUP" value="4"> + <tp:docstring> + A user-defined contact list (see Channel.Interface.Group) + </tp:docstring> + </tp:enumvalue> </tp:enum> <method name="RequestHandles"> - <arg direction="in" name="handle_type" type="u"/> - <arg direction="in" name="names" type="as"/> - <arg direction="out" type="au"/> + <arg direction="in" name="handle_type" type="u"> + <tp:docstring> + An integer handle type (as defined in ConnectionHandleType) + </tp:docstring> + </arg> + <arg direction="in" name="names" type="as"> + <tp:docstring> + An array of names of entities to request handles for + </tp:docstring> + </arg> + <arg direction="out" type="au"> + <tp:docstring> + An array of integer handle numbers in the same order as the given strings + </tp:docstring> + </arg> <tp:docstring> Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The @@ -226,116 +341,129 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA method. Where the name refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager. - - The type value may be one of the following: - 0 - CONNECTION_HANDLE_TYPE_NONE - 1 - CONNECTION_HANDLE_TYPE_CONTACT - 2 - CONNECTION_HANDLE_TYPE_ROOM - 3 - CONNECTION_HANDLE_TYPE_LIST - 4 - CONNECTION_HANDLE_TYPE_GROUP - - Parameters: - handle_type - an integer handle type (as defined in RequestHandle) - name - an array of names of entities to request handles for - - Returns: - an array of integer handle numbers in the same order as given strings - - Potential Errors: - Disconnected, InvalidArgument (the given type is not valid), NotAvailable (the given name is not a valid entity of the given type) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The given name is not a valid entity of the given type + </tp:error> + </tp:potential-errors> </method> <tp:enum name="ConnectionStatus"> - <tp:enumvalue name="CONNECTION_STATUS_CONNECTED" value="0"/> - <tp:enumvalue name="CONNECTION_STATUS_CONNECTING" value="1"/> - <tp:enumvalue name="CONNECTION_STATUS_DISCONNECTED" value="2"/> - </tp:enum> - <tp:enum name="ConnectionStatusReason"> - <tp:enumvalue name="CONNECTION_STATUS_REASON_NONE_SPECIFIED" value="0"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_REQUESTED" value="1"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_NETWORK_ERROR" value="2"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_AUTHENTICATION_FAILED" value="3"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_ENCRYPTION_ERROR" value="4"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_NAME_IN_USE" value="5"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_NOT_PROVIDED" value="6"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_UNTRUSTED" value="7"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_EXPIRED" value="8"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_NOT_ACTIVATED" value="9"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_HOSTNAME_MISMATCH" value="10"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_FINGERPRINT_MISMATCH" value="11"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_SELF_SIGNED" value="12"/> - <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_OTHER_ERROR" value="13"/> - </tp:enum> - <signal name="StatusChanged"> - <arg name="status" type="u"/> - <arg name="reason" type="u"/> - <tp:docstring> - Emitted when the status of the connection changes. All states and - reasons have numerical values, as defined here: - - 0 - CONNECTION_STATUS_CONNECTED + <tp:enumvalue name="CONNECTION_STATUS_CONNECTED" value="0"> + <tp:docstring> The connection is alive and all methods are available. - - 1 - CONNECTION_STATUS_CONNECTING + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_CONNECTING" value="1"> + <tp:docstring> The connection has not yet been established, or has been severed and reconnection is being attempted. Some methods may fail until the connection has been established. - - 2 - CONNECTION_STATUS_DISCONNECTED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_DISCONNECTED" value="2"> + <tp:docstring> The connection has been severed and no method calls are valid. The object may be removed from the bus at any time. - - The reason should be one of the following: - - 0 - CONNECTION_STATUS_REASON_NONE_SPECIFIED + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <tp:enum name="ConnectionStatusReason"> + <tp:enumvalue name="CONNECTION_STATUS_REASON_NONE_SPECIFIED" value="0"> + <tp:docstring> There is no reason set for this state change. - - 1 - CONNECTION_STATUS_REASON_REQUESTED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_REQUESTED" value="1"> + <tp:docstring> The change is in response to a user request. - - 2 - CONNECTION_STATUS_REASON_NETWORK_ERROR + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_NETWORK_ERROR" value="2"> + <tp:docstring> There was an error sending or receiving on the network socket. - - 3 - CONNECTION_STATUS_REASON_AUTHENTICATION_FAILED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_AUTHENTICATION_FAILED" value="3"> + <tp:docstring> The username or password was invalid. - - 4 - CONNECTION_STATUS_REASON_ENCRYPTION_ERROR + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_ENCRYPTION_ERROR" value="4"> + <tp:docstring> There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created. - - 5 - CONNECTION_STATUS_REASON_NAME_IN_USE + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_NAME_IN_USE" value="5"> + <tp:docstring> Someone is already connected to the server using the name you are trying to connect with. - - 6 - CONNECTION_STATUS_REASON_CERT_NOT_PROVIDED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_NOT_PROVIDED" value="6"> + <tp:docstring> The server did not provide a SSL certificate. - - 7 - CONNECTION_STATUS_REASON_CERT_UNTRUSTED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_UNTRUSTED" value="7"> + <tp:docstring> The server's SSL certificate could not be trusted. - - 8 - CONNECTION_STATUS_REASON_CERT_EXPIRED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_EXPIRED" value="8"> + <tp:docstring> The server's SSL certificate has expired. - - 9 - CONNECTION_STATUS_REASON_CERT_NOT_ACTIVATED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_NOT_ACTIVATED" value="9"> + <tp:docstring> The server's SSL certificate is not yet valid. - - 10 - CONNECTION_STATUS_REASON_CERT_HOSTNAME_MISMATCH + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_HOSTNAME_MISMATCH" value="10"> + <tp:docstring> The server's SSL certificate did not match its hostname. - - 11 - CONNECTION_STATUS_REASON_CERT_FINGERPRINT_MISMATCH + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_FINGERPRINT_MISMATCH" value="11"> + <tp:docstring> The server's SSL certificate does not have the expected fingerprint. - - 12 - CONNECTION_STATUS_REASON_CERT_SELF_SIGNED + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_SELF_SIGNED" value="12"> + <tp:docstring> The server's SSL certificate is self-signed. - - 13 - CONNECTION_STATUS_REASON_CERT_OTHER_ERROR + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_STATUS_REASON_CERT_OTHER_ERROR" value="13"> + <tp:docstring> There was some other error validating the server's SSL certificate. - - Parameters: - status - an integer indicating the new status - reason - an integer indicating the reason for the status change + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <signal name="StatusChanged"> + <arg name="status" type="u"> + <tp:docstring> + An integer indicating the new status, as defined by ConnectionStatus + </tp:docstring> + </arg> + <arg name="reason" type="u"> + <tp:docstring> + An integer indicating the reason for the status change, as defined + by ConnectionStatusReason + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the status of the connection changes. All states and + reasons have numerical values, as defined in ConnectionStatus + and ConnectionStatusReason. </tp:docstring> </signal> <tp:docstring> diff --git a/spec/ConnectionInterfaceAliasing.xml b/spec/ConnectionInterfaceAliasing.xml index f78f8e2a..3295e440 100644 --- a/spec/ConnectionInterfaceAliasing.xml +++ b/spec/ConnectionInterfaceAliasing.xml @@ -22,69 +22,85 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Aliasing" tp:name-const="CONN_INTERFACE_ALIASING"> <signal name="AliasesChanged"> - <arg name="aliases" type="a(us)"/> + <arg name="aliases" type="a(us)"> + <tp:docstring> + An array containing structs of: + - the handle representing the contact + - the new alias + </tp:docstring> + </arg> <tp:docstring> Signal emitted when a contact's alias (or that of the user) is changed. - - Parameters: - aliases - an array containing structs of: - the handle representing the contact - the new alias </tp:docstring> </signal> <tp:flags name="ConnectionAliasFlags"> - <tp:flag name="CONNECTION_ALIAS_FLAG_USER_SET" value="1"/> + <tp:flag name="CONNECTION_ALIAS_FLAG_USER_SET" value="1"> + <tp:docstring> + The aliases of contacts on this connection are specified by the user + of the service, not the contacts themselves. This is the case on + eg Jabber. + </tp:docstring> + </tp:flag> </tp:flags> <method name="GetAliasFlags"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + An integer with a bitwise OR of flags from ConnectionAliasFlags + </tp:docstring> + </arg> <tp:docstring> - Return a logical OR of flags detailing the behaviour of aliases on this - connection. Valid flags are: - 1 - CONNECTION_ALIAS_FLAG_USER_SET - The aliases of contacts on this connection are specified by the user - of the service, not the contacts themselves. This is the case on - eg Jabber. - - Returns: - a integer with a logical OR of flags as defined above - - Potential Errors: - Disconnected + Return a bitwise OR of flags detailing the behaviour of aliases on this + connection. </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:potential-errors> </method> <method name="RequestAliases"> - <arg direction="in" name="contacts" type="au"/> - <arg direction="out" type="as"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as"> + <tp:docstring> + A list of aliases in the same order as the contact handles + </tp:docstring> + </arg> <tp:docstring> Request the value of several contacts' aliases at once. - - Parameters: - contacts - an array of the handle representing contacts - - Returns: - a dictionary of contact handles to aliases in the same order - - Possible Errors: - Disconnected, NetworkError, NotAvailable, InvalidHandle </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:potential-errors> </method> <method name="SetAliases"> - <arg direction="in" name="aliases" type="a{us}"/> + <arg direction="in" name="aliases" type="a{us}"> + <tp:docstring> + A dictionary mapping: + - integer handles of contacts + to: + - strings of the new alias to set + </tp:docstring> + </arg> <tp:docstring> Request that the alias of the given contact be changed. Success will be indicated by emitting an AliasUpdate signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only - ever succeed if contact is the user's own handle (as returned by + ever succeed if the contact is the user's own handle (as returned by GetSelfHandle on the Connection interface). - - Parameters: - a dictionary mapping: - integer handles of contacts - strings of the new alias to set - - Possible Errors: - Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:potential-errors> </method> <tp:docstring> An interface on connections to support protocols where contacts have an diff --git a/spec/ConnectionInterfaceAvatars.xml b/spec/ConnectionInterfaceAvatars.xml index 6f393243..f3b5be95 100644 --- a/spec/ConnectionInterfaceAvatars.xml +++ b/spec/ConnectionInterfaceAvatars.xml @@ -22,101 +22,145 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars" tp:name-const="CONN_INTERFACE_AVATARS"> <signal name="AvatarUpdated"> - <arg name="contact" type="u"/> - <arg name="new_avatar_token" type="s"/> + <arg name="contact" type="u"> + <tp:docstring> + An integer handle for the contact whose avatar has changed + </tp:docstring> + </arg> + <arg name="new_avatar_token" type="s"> + <tp:docstring> + Unique token for their new avatar + </tp:docstring> + </arg> <tp:docstring> Emitted when the avatar for a contact has been updated, or first discovered on this connection. If the token differs from the token associated with the client's cached avatar for this contact, the new avatar should be requested with RequestAvatar. - - Parameters: - contact - an integer handle for the contact whose avatar has changed - new_avatar_token - unique token for their new avatar </tp:docstring> </signal> <method name="GetAvatarRequirements"> - <arg direction="out" type="as"/> - <arg direction="out" type="q"/> - <arg direction="out" type="q"/> - <arg direction="out" type="q"/> - <arg direction="out" type="q"/> - <arg direction="out" type="u"/> + <arg direction="out" type="as"> + <tp:docstring> + An array of supported MIME types (eg image/jpeg) + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The minimum image width in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The minimum image height in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The maximum image width in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The maximum image height in pixels + </tp:docstring> + </arg> + <arg direction="out" type="u"> + <tp:docstring> + The maximum image size in bytes + </tp:docstring> + </arg> <tp:docstring> Get the required format of avatars on this connection. - - Returns: - an array of supported MIME types (eg image/jpeg) - the minimum image width in pixels - the minimum image height in pixels - the maximum image width in pixels - the maximum image height in pixels - the maximum image size in bytes - - Possible Errors: - Disconnected, NetworkError, PermissionDenied, NotAvailable </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.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <method name="GetAvatarTokens"> - <arg direction="in" name="contacts" type="au"/> - <arg direction="out" type="as"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as"> + <tp:docstring> + An array of avatar tokens or empty strings (if no avatar is set) in the + same order as the given array of contact handles + </tp:docstring> + </arg> <tp:docstring> Get the unique tokens for the given contacts' avatars. These tokens can be persisted across connections, and should be used by the client to check whether the avatars have been updated. A empty token means that no avatar is set for the given contact. - - Parameters: - contacts - an array of handles representing contacts - - Returns: - an array of avatar tokens or empty strings (if no avatar is set) in the - same order as the given array of contact handles - - Possible Errors: - Disconnected, NetworkError, InvalidArgument, PermissionDenied, - NotAvailable </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:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <method name="RequestAvatar"> - <arg direction="in" name="contact" type="u"/> - <arg direction="out" type="ay"/> - <arg direction="out" type="s"/> + <arg direction="in" name="contact" type="u"> + <tp:docstring> + An integer handle for the contact to request the avatar for + </tp:docstring> + </arg> + <arg direction="out" type="ay"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg direction="out" type="s"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> <tp:docstring> Request the avatar for a given contact. - - Parameters: - contact - an integer handle for the contact to request the avatar for - - Returns: - an array of bytes containing the image data - a string containing the image MIME type (eg image/jpeg), or empty if - unknown - - Possible Errors: - Disconnected, NetworkError, InvalidHandle, PermissionDenied, - NotAvailable </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.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <method name="SetAvatar"> - <arg direction="in" name="avatar" type="ay"/> - <arg direction="in" name="mime_type" type="s"/> - <arg direction="out" type="s"/> + <arg direction="in" name="avatar" type="ay"> + <tp:docstring> + An array of bytes representing the avatar image data + </tp:docstring> + </arg> + <arg direction="in" name="mime_type" type="s"> + <tp:docstring> + A string representing the image MIME type + </tp:docstring> + </arg> + <arg direction="out" type="s"> + <tp:docstring> + The string token of the new avatar + </tp:docstring> + </arg> <tp:docstring> Set a new avatar image for this connection. The avatar image must respect the requirements obtained by GetAvatarRequirements. - - Parameters: - avatar - an array of bytes representing the avatar image data - mime_type - a string representing the image MIME type - - Returns: - the string token of the new avatar - - Possible Errors: - Disconnected, NetworkError, InvalidArgument, PermissionDenied, - NotAvailable </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:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <tp:docstring> An interface for requesting avatars for contacts on a given connection, diff --git a/spec/ConnectionInterfaceCapabilities.xml b/spec/ConnectionInterfaceCapabilities.xml index e8770d09..c4979854 100644 --- a/spec/ConnectionInterfaceCapabilities.xml +++ b/spec/ConnectionInterfaceCapabilities.xml @@ -22,9 +22,25 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities" tp:name-const="CONN_INTERFACE_CAPABILITIES"> <method name="AdvertiseCapabilities"> - <arg direction="in" name="add" type="a(su)"/> - <arg direction="in" name="remove" type="as"/> - <arg direction="out" type="a(su)"/> + <arg direction="in" name="add" type="a(su)"> + <tp:docstring> + An array of structures containing: + - a string channel type + - a bitwise OR of type specific capability flags + </tp:docstring> + </arg> + <arg direction="in" name="remove" type="as"> + <tp:docstring> + An array of D-Bus interface names of channel types to remove + </tp:docstring> + </arg> + <arg direction="out" type="a(su)"> + <tp:docstring> + An array of structures describing the current capabilities containing: + - a string channel type + - a bitwise OR of type specific capability flags + </tp:docstring> + </arg> <tp:docstring> Used by user interfaces to indicate which channel types they are able to handle on this connection. Because these may be provided by @@ -43,58 +59,58 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA that the set is kept accurate - for example, a client may remove capabilities or type specific capability flags when it exits which are still provided by another client. - - Parameters: - add - an array of structures containing: - a string channel type - a bitwise OR of type specific capability flags - remove - an array of D-Bus interface names of channel types to remove - - Returns: - an array of structures describing the current capabilities containing: - a string channel type - a bitwise OR of type specific capability flags - - Potential Errors: - NetworkError, Disconnected </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> </method> <signal name="CapabilitiesChanged"> - <arg name="caps" type="a(usuuuu)"/> + <arg name="caps" type="a(usuuuu)"> + <tp:docstring> + An array of structures containing: + - an integer handle representing the contact + - a string channel type + - a bitwise OR of the contact's old generic capability flags + - a bitwise OR of the contact's new generic capability flags + - a bitwise OR of the contact's old type specific capability flags + - a bitwise OR of the contact's new type specific capability flags + </tp:docstring> + </arg> <tp:docstring> Announce that there has been a change of capabilities on the given handle, or on the connection itself if the handle is zero. - - Parameters: - an array of structures containing: - an integer handle representing the contact - a string channel type - a bitwise OR of the contact's old generic capability flags - a bitwise OR of the contact's new generic capability flags - a bitwise OR of the contact's old type specific capability flags - a bitwise OR of the contact's new type specific capability flags </tp:docstring> </signal> <method name="GetCapabilities"> - <arg direction="in" name="handles" type="au"/> - <arg direction="out" type="a(usuu)"/> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + An array of contact handles for this connection, or zero to query capabilities available on the connection itself + </tp:docstring> + </arg> + <arg direction="out" type="a(usuu)"> + <tp:docstring> + An array of structures containing: + - an integer handle representing the contact + - a string channel type + - a bitwise OR of generic capability flags for the type + - a bitwise OR of type specific capability flags for the type + </tp:docstring> + </arg> <tp:docstring> Returns an array of capabilities for the given contact handles, or the connection itself (where handle is zero). - - Parameters: - handle - a contact handle for this connection, or zero for channel types available on the connection itself - - Returns: - an array of structures containing: - an integer handle representing the contact - a string channel type - a bitwise OR of generic capability flags for the type - a bitwise OR of type specific capability flags for the type - - Possible Errors: - Disconnected, NetworkError, InvalidHandle (the handle does not represent a contact), PermissionDenied </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The handle does not represent a contact + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <tp:docstring> An interface for connections where it is possible to know what channel @@ -110,12 +126,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA as searching and room listing. The activities are represented by the D-Bus interface name of the channel type for that activity. - The following generic capability flags are defined: - 1 - CONNECTION_CAPABILITY_FLAG_CREATE - The given channel type and handle can be given to RequestChannel to - create a new channel of this type. - 2 - CONNECTION_CAPABILITY_FLAG_INVITE - The given contact can be invited to an existing channel of this type. + The generic capability flags are defined by ConnectionCapabilityFlag. In addition, channel types may have type specific capability flags of their own, which are described in the documentation for each channel type. @@ -128,8 +139,17 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:docstring> </interface> <tp:flags name="ConnectionCapabilityFlag"> - <tp:flag name="CONNECTION_CAPABILITY_FLAG_CREATE" value="1"/> - <tp:flag name="CONNECTION_CAPABILITY_FLAG_INVITE" value="2"/> + <tp:flag name="CONNECTION_CAPABILITY_FLAG_CREATE" value="1"> + <tp:docstring> + The given channel type and handle can be given to RequestChannel to + create a new channel of this type. + </tp:docstring> + </tp:flag> + <tp:flag name="CONNECTION_CAPABILITY_FLAG_INVITE" value="2"> + <tp:docstring> + The given contact can be invited to an existing channel of this type. + </tp:docstring> + </tp:flag> </tp:flags> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/ConnectionInterfaceContactInfo.xml b/spec/ConnectionInterfaceContactInfo.xml index 30e8de38..d774c028 100644 --- a/spec/ConnectionInterfaceContactInfo.xml +++ b/spec/ConnectionInterfaceContactInfo.xml @@ -22,30 +22,39 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo" tp:name-const="CONN_INTERFACE_CONTACT_INFO"> <signal name="GotContactInfo"> - <arg name="contact" type="u"/> - <arg name="vcard" type="s"/> + <arg name="contact" type="u"> + <tp:docstring> + An integer handle of the contact ID on the server + </tp:docstring> + </arg> + <arg name="vcard" type="s"> + <tp:docstring> + The XML string containing their vcard information + </tp:docstring> + </arg> <tp:docstring> Emitted when information has been received from the server with the details of a particular contact. - - Parameters: - contact - an integer handle of the contact ID on the server - vcard - the XML string containing their vcard information </tp:docstring> </signal> <method name="RequestContactInfo"> - <arg direction="in" name="contact" type="u"/> + <arg direction="in" name="contact" type="u"> + <tp:docstring> + An integer handle for the contact to request info for + </tp:docstring> + </arg> <tp:docstring> Request information for a given contact. The function will return after a GotContactInfo signal has been emitted for the contact, or an error returned. - - Parameters: - contact - an integer handle for the contact to request info for - - Possible Errors: - Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable </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.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <tp:docstring> THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. A new version diff --git a/spec/ConnectionInterfaceForwarding.xml b/spec/ConnectionInterfaceForwarding.xml index f261f10a..2eb17e2e 100644 --- a/spec/ConnectionInterfaceForwarding.xml +++ b/spec/ConnectionInterfaceForwarding.xml @@ -22,39 +22,48 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding" tp:name-const="CONN_INTERFACE_FORWARDING"> <signal name="ForwardingChanged"> - <arg name="forward_to" type="u"/> + <arg name="forward_to" type="u"> + <tp:docstring> + An integer contact handle to forward communication to + </tp:docstring> + </arg> <tp:docstring> Emitted when the forwarding contact handle for this connection has been changed. An zero handle indicates forwarding is disabled. - - Parameters: - forward_to - an integer contact handle to forward communication to </tp:docstring> </signal> <method name="GetForwardingHandle"> - <arg direction="out" type="u"/> + <arg direction="out" type="u"> + <tp:docstring> + An integer contact handle to whom incoming communication is forwarded + </tp:docstring> + </arg> <tp:docstring> Returns the current forwarding contact handle, or zero if none is set. - - Returns: - an integer contact handle to whom incoming communication is forwarded - - Possible Errors: - Disconnected, NetworkError, NotAvailable </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.NotAvailable"/> + </tp:possible-errors> </method> <method name="SetForwardingHandle"> - <arg direction="in" name="forward_to" type="u"/> + <arg direction="in" name="forward_to" type="u"> + <tp:docstring> + An integer contact handle to forward incoming communications to + </tp:docstring> + </arg> <tp:docstring> Set a contact handle to forward incoming communications to. A zero handle disables forwarding. - - Parameters: - forward_to - an integer contact handle to forward incoming communications to - - Possible Errors: - Disconnected, NetworkError, PermissionDenied, NotAvailable, InvalidHandle </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> </method> <tp:docstring> A connection interface for services which can signal to contacts diff --git a/spec/ConnectionInterfacePresence.xml b/spec/ConnectionInterfacePresence.xml index 06d2044b..8f310759 100644 --- a/spec/ConnectionInterfacePresence.xml +++ b/spec/ConnectionInterfacePresence.xml @@ -22,20 +22,31 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence" tp:name-const="CONN_INTERFACE_PRESENCE"> <method name="AddStatus"> - <arg direction="in" name="status" type="s"/> - <arg direction="in" name="parms" type="a{sv}"/> + <arg direction="in" name="status" type="s"> + <tp:docstring> + The string identifier of the desired status + </tp:docstring> + </arg> + <arg direction="in" name="parms" type="a{sv}"> + <tp:docstring> + A dictionary of optional parameter names mapped to their variant-boxed values + </tp:docstring> + </arg> <tp:docstring> Request that a single presence status is published for the user, along with any desired parameters. Changes will be indicated by PresenceUpdate signals being emitted. - Parameters: - status - the string identifier of the desired status - parms - a dictionary of optional parameter names mapped to their variant-boxed values - Possible Errors: Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <method name="ClearStatus"> <tp:docstring> @@ -43,108 +54,148 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA that this request may simply result in the statuses being replaced by a default available status. Changes will be indicated by PresenceUpdate signals being emitted. - - Possible Errors: - Disconnected, NetworkError, PermissionDenied </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.PermissionDenied"/> + </tp:possible-errors> </method> <method name="GetPresence"> - <arg direction="in" name="contacts" type="au"/> - <arg direction="out" name="presence" type="a{u(ua{sa{sv}})}"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> + <arg direction="out" name="presence" type="a{u(ua{sa{sv}})}"> + <tp:docstring> + Presence information in the same format as for the PresenceUpdate + signal + </tp:docstring> + </arg> <tp:docstring> Get presence previously emitted by PresenceUpdate for the given contacts. Data is returned in the same structure as the PresenceUpdate signal. Using this method in favour of RequestPresence has the advantage that it will not wake up each client connected to the PresenceUpdate signal. - - Parameters: - contacts - an array of the contacts whose presence should be obtained - - Possible Errors: - Disconnected, InvalidHandle, NotAvailable </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <method name="GetStatuses"> - <arg direction="out" type="a{s(ubba{ss})}"/> - <tp:docstring> - Get a dictionary of the valid presence statuses for this connection. - This is only available when online because only some statuses will - be available on some servers. - - Returns: - a dictionary of string identifiers mapped to a struct for each status, containing: + <arg direction="out" type="a{s(ubba{ss})}"> + <tp:docstring> + A dictionary of string identifiers mapped to a struct for each status, containing: - a type value from one of the values above - a boolean to indicate if this status may be set on yourself - a boolean to indicate if this is an exclusive status which you may not set alongside any other - a dictionary of valid optional string argument names mapped to their types - - Possible Errors: - Disconnected, NetworkError + </tp:docstring> + </arg> + <tp:docstring> + Get a dictionary of the valid presence statuses for this connection. + This is only available when online because only some statuses will + be available on some servers. </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <signal name="PresenceUpdate"> - <arg name="presence" type="a{u(ua{sa{sv}})}"/> + <arg name="presence" type="a{u(ua{sa{sv}})}"> + <tp:docstring> + A dictionary of contact handles mapped to a struct containing: + - a UNIX timestamp of the last activity time (in UTC) + - a dictionary mapping the contact's current status identifiers to: + a dictionary of optional parameter names mapped to their + variant-boxed values + </tp:docstring> + </arg> <tp:docstring> This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has been changed, or when the presence requested by RequestPresence is available. - Parameters: - a dictionary of contact handles mapped to a struct containing: - - a UNIX timestamp of the last activity time (in UTC) - - a dictionary mapping the contact's current status identifiers to: - a dictionary of optional parameter names mapped to their - variant-boxed values </tp:docstring> </signal> <method name="RemoveStatus"> - <arg direction="in" name="status" type="s"/> + <arg direction="in" name="status" type="s"> + <tp:docstring> + The string identifier of the status not to publish anymore for the user + </tp:docstring> + </arg> <tp:docstring> Request that the given presence status is no longer published for the user. Changes will be indicated by PresenceUpdate signals being emitted. As with ClearStatus, removing a status may actually result in it being replaced by a default available status. - - Parameters: - status - the string identifier of the status not to publish anymore for the user - - Possible Errors: - Disconnected, NetworkError, PermissionDenied, InvalidArgument (if the status - requested is not currently set) </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.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring>The status requested is not currently set</tp:docstring> + </tp:error> + </tp:possible-errors> </method> <method name="RequestPresence"> - <arg direction="in" name="contacts" type="au"/> + <arg direction="in" name="contacts" type="au"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> <tp:docstring> Request the presence for contacts on this connection. A PresenceUpdate signal will be emitted when they are received. This is not the same as subscribing to the presence of a contact, which must be done using the 'subscription' Channel.Type.ContactList, and on some protocols presence information may not be available unless a subscription exists. - - Parameters: - contacts - an array of the contacts whose presence should be obtained - - Possible Errors: - Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable (if the presence of the requested contacts is not reported to this connection) </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.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The presence of the requested contacts is not reported to this connection + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <method name="SetLastActivityTime"> - <arg direction="in" name="time" type="u"/> + <arg direction="in" name="time" type="u"> + <tp:docstring> + A UNIX timestamp of the user's last activity time (in UTC) + </tp:docstring> + </arg> <tp:docstring> Request that the recorded last activity time for the user be updated on the server. - - Parameters: - time - a UNIX timestamp of the user's last activity time (in UTC) - - Possible Errors: - Disconnected, NetworkError, NotImplemented (this protocol has no concept of idle time) </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.NotImplemented"> + <tp:docstring> + This protocol has no concept of idle time + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <method name="SetStatus"> - <arg direction="in" name="statuses" type="a{sa{sv}}"/> + <arg direction="in" name="statuses" type="a{sa{sv}}"> + <tp:docstring> + A dictionary mapping status identifiers to dictionaries, which + map optional parameter names to their variant-boxed values + </tp:docstring> + </arg> <tp:docstring> Request that the user's presence be changed to the given statuses and desired parameters. Changes will be reflected by PresenceUpdate @@ -155,14 +206,14 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA NotAvailable will be returned and the connection will remain offline, or if the protocol does not support signing on with a certain status, Disconnected will be returned. - - Parameters: - a dictionary of status identifiers mapped to: - a dictionary of optional parameter names mapped to their variant-boxed values - - Possible Errors: - Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <tp:docstring> This interface is for services which have a concept of presence which can @@ -191,13 +242,9 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - offline As well as these well-known status identifiers, every status also has a - numerical type value which can be used by the client to classify even - unknown statuses into different fundamental types: - 1 - CONNECTION_PRESENCE_TYPE_OFFLINE - 2 - CONNECTION_PRESENCE_TYPE_AVAILABLE - 3 - CONNECTION_PRESENCE_TYPE_AWAY - 4 - CONNECTION_PRESENCE_TYPE_EXTENDED_AWAY - 5 - CONNECTION_PRESENCE_TYPE_HIDDEN + numerical type value chosen from ConnectionPresenceType which can be + used by the client to classify even unknown statuses into different + fundamental types. These numerical types exist so that even if a client does not understand the string identifier being used, and hence cannot present the presence to @@ -223,12 +270,36 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA of presence information. </tp:docstring> <tp:enum name="ConnectionPresenceType"> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_UNSET" value="0"/> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_OFFLINE" value="1"/> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_AVAILABLE" value="2"/> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_AWAY" value="3"/> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_EXTENDED_AWAY" value="4"/> - <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_HIDDEN" value="5"/> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_UNSET" value="0"> + <tp:docstring> + An invalid presence type used as a null value + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_OFFLINE" value="1"> + <tp:docstring> + Offline + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_AVAILABLE" value="2"> + <tp:docstring> + Available + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_AWAY" value="3"> + <tp:docstring> + Away + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_EXTENDED_AWAY" value="4"> + <tp:docstring> + Away for an extended time + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue name="CONNECTION_PRESENCE_TYPE_HIDDEN" value="5"> + <tp:docstring> + Hidden (invisible) + </tp:docstring> + </tp:enumvalue> </tp:enum> </interface> </node> diff --git a/spec/ConnectionInterfacePrivacy.xml b/spec/ConnectionInterfacePrivacy.xml index d5e7e433..a922de1d 100644 --- a/spec/ConnectionInterfacePrivacy.xml +++ b/spec/ConnectionInterfacePrivacy.xml @@ -22,55 +22,63 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Privacy" tp:name-const="CONN_INTERFACE_PRIVACY"> <method name="GetPrivacyMode"> - <arg direction="out" type="s"/> + <arg direction="out" type="s"> + <tp:docstring> + A string representing the current privacy mode + </tp:docstring> + </arg> <tp:docstring> Return the current privacy mode, which must be one of the values returned by GetPrivacyModes. - - Returns: - a string of the current privacy mode - - Possible Errors: - Disconnected, NetworkError </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <method name="GetPrivacyModes"> - <arg direction="out" type="as"/> + <arg direction="out" type="as"> + <tp:docstring> + An array of valid privacy modes for this connection + </tp:docstring> + </arg> <tp:docstring> Returns the privacy modes available on this connection. The following well-known names should be used where appropriate: allow-all - any contact may initiate communication allow-specified - only contacts on your 'allow' list may initiate communication allow-subscribed - only contacts on your subscription list may initiate communication - - Returns: - an array of valid privacy modes for this connection </tp:docstring> </method> <signal name="PrivacyModeChanged"> - <arg name="mode" type="s"/> + <arg name="mode" type="s"> + <tp:docstring> + The current privacy mode + </tp:docstring> + </arg> <tp:docstring> Emitted when the privacy mode is changed or the value has been initially received from the server. - - Parameters: - mode - the current privacy mode </tp:docstring> </signal> <method name="SetPrivacyMode"> - <arg direction="in" name="mode" type="s"/> + <arg direction="in" name="mode" type="s"> + <tp:docstring> + The desired privacy mode + </tp:docstring> + </arg> <tp:docstring> Request that the privacy mode be changed to the given value, which must be one of the values returned by GetPrivacyModes. Success is indicated by the method returning and the PrivacyModeChanged signal being emitted. - - Parameters: - mode - the desired privacy mode - - Possible Errors: - Disconnected, NetworkError, PermissionDenied, InvalidArgument </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.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> </method> <tp:docstring> An interface to support getting and setting privacy modes to configure diff --git a/spec/ConnectionInterfaceRenaming.xml b/spec/ConnectionInterfaceRenaming.xml index 85cb3d14..3ea16c56 100644 --- a/spec/ConnectionInterfaceRenaming.xml +++ b/spec/ConnectionInterfaceRenaming.xml @@ -22,30 +22,39 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming" tp:name-const="CONN_INTERFACE_RENAMING"> <signal name="Renamed"> - <arg name="original" type="u"/> - <arg name="new" type="u"/> + <arg name="original" type="u"> + <tp:docstring> + The handle of the original identifier + </tp:docstring> + </arg> + <arg name="new" type="u"> + <tp:docstring> + The handle of the new identifier + </tp:docstring> + </arg> <tp:docstring> Emitted when the unique identifier of a contact on the server changes. - - Parameters: - original - the handle of the original identifier - new - the handle of the new identifier </tp:docstring> </signal> <method name="RequestRename"> - <arg direction="in" name="name" type="s"/> + <arg direction="in" name="name" type="s"> + <tp:docstring> + The desired identifier + </tp:docstring> + </arg> <tp:docstring> Request that the users own identifier is changed on the server. Success is indicated by a Renamed signal being emitted. A new handle will be allocated for the user's new identifier, and remain valid for the lifetime of the connection. - - Parameters: - name - a string of the desired identifier - - Possible Errors: - Disconnected, NetworkError, NotAvailable, InvalidArgument, PermissionDenied </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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <tp:docstring> An interface on connections to support protocols where the unique diff --git a/spec/ConnectionManager.xml b/spec/ConnectionManager.xml index 5422daa1..19662f53 100644 --- a/spec/ConnectionManager.xml +++ b/spec/ConnectionManager.xml @@ -22,43 +22,59 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.ConnectionManager" tp:name-const="CONN_MGR_INTERFACE"> <tp:flags name="ConnMgrParamFlags"> - <tp:flag name="CONN_MGR_PARAM_FLAG_REQUIRED" value="1"/> - <tp:flag name="CONN_MGR_PARAM_FLAG_REGISTER" value="2"/> - <tp:flag name="CONN_MGR_PARAM_FLAG_HAS_DEFAULT" value="4"/> + <tp:flag name="CONN_MGR_PARAM_FLAG_REQUIRED" value="1"> + <tp:docstring> + This parameter is required for connecting to the server. + </tp:docstring> + </tp:flag> + <tp:flag name="CONN_MGR_PARAM_FLAG_REGISTER" value="2"> + <tp:docstring> + This parameter is required for registering an account on the + server. + </tp:docstring> + </tp:flag> + <tp:flag name="CONN_MGR_PARAM_FLAG_HAS_DEFAULT" value="4"> + <tp:docstring> + This parameter has a default value, which is returned in + GetParameters; not providing this parameter is equivalent to + providing the default. + </tp:docstring> + </tp:flag> </tp:flags> <method name="GetParameters"> - <arg direction="in" name="proto" type="s"/> - <arg direction="out" type="a(susv)"/> + <arg direction="in" name="proto" type="s"> + <tp:docstring> + The required protocol name + </tp:docstring> + </arg> + <arg direction="out" type="a(susv)"> + <tp:docstring> + An array of structs containing: + - a string parameter name + - a bitwise OR of the parameter flags (as defined above) + - a string D-Bus type signature + - a variant boxed default value (if the HAS_DEFAULT flag is not + present, there is no default and this takes some dummy value) + </tp:docstring> + </arg> <tp:docstring> Get a list of the parameters which must or may be provided to the RequestConnection method when connecting to the given protocol, - or registering (the boolean "register" parameter is available, and - set to true). - - Parameters may have the following flags: - 1 - CONN_MGR_PARAM_FLAG_REQUIRED - This parameter is required for connecting to the server. - 2 - CONN_MGR_PARAM_FLAG_REGISTER - This parameter is required for registering an account on the - server. - 4 - CONN_MGR_PARAM_FLAG_HAS_DEFAULT - This parameter has a default value, which is returned; not - providing this parameter is equivalent to providing the default. - - Returns: - an array of structs containing: - a string parameter name - a bitwise OR of the parameter flags (as defined above) - a string D-Bus type signature - a variant boxed default value (only relevant if the - HAS_DEFAULT flag is present) - - Potential Errors: - NotImplemented (the requested protocol is not supported by this manager) + or registering (the boolean "register" parameter is available, + and set to true). </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + The requested protocol is not supported by this manager + </tp:error> + </tp:potential-errors> </method> <method name="ListProtocols"> - <arg direction="out" type="as"/> + <arg direction="out" type="as"> + <tp:docstring> + A array of string protocol identifiers supported by this manager + </tp:docstring> + </arg> <tp:docstring> Get a list of protocol identifiers that are implemented by this connection manager. The following well-known values should be used @@ -76,29 +92,49 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA trepia - Trepia yahoo - Yahoo! Messenger zephyr - Zephyr - - Returns: - an array of string protocol identifiers supported by this manager </tp:docstring> </method> <signal name="NewConnection"> - <arg name="bus_name" type="s"/> - <arg name="object_path" type="o"/> - <arg name="proto" type="s"/> + <arg name="bus_name" type="s"> + <tp:docstring> + The D-Bus service where the connection object can be found + </tp:docstring> + </arg> + <arg name="object_path" type="o"> + <tp:docstring> + The object path of the Connection object on this service + </tp:docstring> + </arg> + <arg name="proto" type="s"> + <tp:docstring> + The identifier for the protocol this connection uses + </tp:docstring> + </arg> <tp:docstring> Emitted when a new Connection object is created. - - Parameters: - bus_name - the D-Bus service where the connection object can be found - object_path - the object path of the Connection object on this service - proto - the identifier for the protocol this connection uses </tp:docstring> </signal> <method name="RequestConnection"> - <arg direction="in" name="proto" type="s"/> - <arg direction="in" name="parameters" type="a{sv}"/> - <arg direction="out" type="s"/> - <arg direction="out" type="o"/> + <arg direction="in" name="proto" type="s"> + <tp:docstring> + The protocol identifier + </tp:docstring> + </arg> + <arg direction="in" name="parameters" type="a{sv}"> + <tp:docstring> + A dictionary mapping parameter name to the variant boxed value + </tp:docstring> + </arg> + <arg direction="out" type="s"> + <tp:docstring> + A D-Bus service name where the new Connection object can be found + </tp:docstring> + </arg> + <arg direction="out" type="o"> + <tp:docstring> + The D-Bus object path to the Connection on this service + </tp:docstring> + </arg> <tp:docstring> Request a Connection object representing a given account on a given protocol with the given parameters. The method returns the bus name @@ -108,7 +144,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Connect method. In order to allow Connection objects to be discovered by new clients, - the bus name and object path must be of the form: + the object path and bus name must be of the form: /org/freedesktop/Telepathy/Connection/manager/proto/account And: org.freedesktop.Telepathy.Connection.manager.proto.account @@ -163,18 +199,19 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections. - - Parameters: - proto - the protocol identifier - parameters - a dictionary mapping parameter name to the variant boxed value - - Returns: - a D-Bus service name where the new Connection object can be found - the D-Bus object path to the Connection on this service - - Potential Errors: - NetworkError, NotImplemented (unknown protocol), NotAvailable (the requested connection already appears to exist), InvalidArgument (unrecognised connection parameters) </tp:docstring> + <tp:potential-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + The requested protocol is not supported by this manager + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The requested connection already appears to exist + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + Unrecognised connection parameters + </tp:error> + </tp:potential-errors> </method> <tp:docstring> A D-Bus service which allows connections to be created. The manager diff --git a/spec/Properties.xml b/spec/Properties.xml index 9dad24a7..f9f0f7a0 100644 --- a/spec/Properties.xml +++ b/spec/Properties.xml @@ -22,8 +22,6 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </tp:license> <interface name="org.freedesktop.Telepathy.Properties" tp:name-const="PROPERTIES_INTERFACE"> <method name="GetProperties"> - <arg direction="in" name="properties" type="au"/> - <arg direction="out" type="a(uv)"/> <tp:docstring> Returns a dictionary of variants containing the current values of the given properties. @@ -31,56 +29,61 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA If any given property identifiers are invalid, InvalidArgument will be returned. All properties must have the PROPERTY_FLAG_READ flag, or PermissionDenied will be returned. - - Parameters: - properties - an array of property identifiers - - Returns: - an array of structs containing: - integer identifiers - variant boxed values - - Potential Errors: - Disconnected, InvalidArgument, PermissionDenied </tp:docstring> + <arg direction="in" name="properties" type="au"> + <tp:docstring>An array of property identifiers</tp:docstring> + </arg> + <arg direction="out" type="a(uv)"> + <tp:docstring>An array of structs containing: + - integer identifiers + - variant boxed values + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> </method> <method name="ListProperties"> - <arg direction="out" type="a(ussu)"/> <tp:docstring> Returns a dictionary of the properties available on this channel. - - Returns: - an array of structs containing: - integer identifiers - a string property name - a string representing the D-Bus signature of this property - a bitwise OR of the flags applicable to this property </tp:docstring> + <arg direction="out" type="a(ussu)"> + <tp:docstring> + An array of structs containing: + - an integer identifier + - a string property name + - a string representing the D-Bus signature of this property + - a bitwise OR of the flags applicable to this property + </tp:docstring> + </arg> </method> <signal name="PropertiesChanged"> - <arg name="properties" type="a(uv)"/> <tp:docstring> Emitted when the value of readable properties has changed. - - Parameters: - properties - an array of structs containing: - integer identifiers - variant boxed values </tp:docstring> + <arg name="properties" type="a(uv)"> + <tp:docstring> + An array of structs containing: + - integer identifiers + - variant boxed values + </tp:docstring> + </arg> </signal> <signal name="PropertyFlagsChanged"> - <arg name="properties" type="a(uu)"/> <tp:docstring> Emitted when the flags of some room properties have changed. - - Parameters: - properties - an array of structs containing: - integer identifiers - a bitwise OR of the current flags </tp:docstring> + <arg name="properties" type="a(uu)"> + <tp:docstring> + An array of structs containing: + - integer identifiers + - a bitwise OR of the current flags + </tp:docstring> + </arg> </signal> <method name="SetProperties"> - <arg direction="in" name="properties" type="a(uv)"/> <tp:docstring> Takes a dictionary of variants containing desired values to set the given properties. In the case of any errors, no properties will be changed. @@ -91,14 +94,20 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA PermissionDenied will be returned. If any variants are of the wrong type, NotAvailable will be returned. If any given property identifiers are invalid, InvalidArgument will be returned. + </tp:docstring> - Parameters: - properties - a dictionary mapping integer identifiers to: - variant boxed values - - Potential Errors: - Disconnected, InvalidArgument, NotAvailable, PermissionDenied, NetworkError + <arg direction="in" name="properties" type="a(uv)"> + <tp:docstring> + A dictionary mapping integer identifiers to boxed values </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> </method> <tp:docstring> Interface for channels and other objects, to allow querying and setting @@ -136,15 +145,15 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA a contact handle representing who last modified the subject Each property also has a flags value to indicate what methods are - available. This is a bitwise OR of the following values: - 1 - PROPERTY_FLAG_READ - the property can be read - 2 - PROPERTY_FLAG_WRITE - the property can be written + available. This is a bitwise OR of PropertyFlags values. </tp:docstring> <tp:flags name="PropertyFlags"> - <tp:flag name="PROPERTY_FLAG_READ" value="1"/> - <tp:flag name="PROPERTY_FLAG_WRITE" value="2"/> + <tp:flag name="PROPERTY_FLAG_READ" value="1"> + <tp:docstring>The property can be read</tp:docstring> + </tp:flag> + <tp:flag name="PROPERTY_FLAG_WRITE" value="2"> + <tp:docstring>The property can be written</tp:docstring> + </tp:flag> </tp:flags> </interface> </node> diff --git a/spec/all.xml b/spec/all.xml index 9fc37ce1..9841c3af 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -4,11 +4,13 @@ <tp:version>0.5.0</tp:version> -<tp:docstring> +<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited Copyright (C) 2005, 2006 Nokia Corporation Copyright (C) 2006 INdT +</tp:copyright> +<tp:license> 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 @@ -22,7 +24,7 @@ Library General Public License for more details. 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -</tp:docstring> +</tp:license> <xi:include href="ConnectionManager.xml"/> <xi:include href="Connection.xml"/> |