<?xml version="1.0" ?>
<node name="/Properties_Interface" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright> Copyright (C) 2005-2007 Collabora Limited </tp:copyright>
<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>
<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.</p>
<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
<interface name="org.freedesktop.Telepathy.Properties">
<tp:struct name="Property_Spec" array-name="Property_Spec_List">
<tp:docstring>A struct (property ID, property name, D-Bus signature,
flags) representing a property, as returned by ListProperties on the
Properties interface.</tp:docstring>
<tp:member type="u" name="Property_ID"/>
<tp:member type="s" name="Name"/>
<tp:member type="s" tp:type="DBus_Signature" name="Signature"/>
<tp:member type="u" tp:type="Property_Flags" name="Flags"/>
</tp:struct>
<tp:struct name="Property_Flags_Change"
array-name="Property_Flags_Change_List">
<tp:docstring>A struct (property ID, flags) representing a change to
a property's flags, as seen in the PropertyFlagsChanged signal on
the Properties interface.</tp:docstring>
<tp:member type="u" name="Property_ID"/>
<tp:member type="u" name="New_Flags"/>
</tp:struct>
<tp:simple-type name="Property_ID" type="u" array-name="Property_ID_List">
<tp:docstring>
An unsigned integer used to represent a Telepathy property.
</tp:docstring>
</tp:simple-type>
<tp:struct name="Property_Value" array-name="Property_Value_List">
<tp:docstring>A struct (property ID, value) representing a
property's value, as seen in the PropertiesChanged signal on
the Properties interface, returned by the GetProperties method
and passed to the SetProperties method.</tp:docstring>
<tp:member type="u" tp:type="Property_ID" name="Identifier"/>
<tp:member type="v" name="Value"/>
</tp:struct>
<method name="GetProperties" tp:name-for-bindings="Get_Properties">
<tp:docstring>
Returns an array of (identifier, value) pairs containing the current
values of the given properties.
</tp:docstring>
<arg direction="in" name="Properties" type="au" tp:type="Property_ID[]">
<tp:docstring>An array of property identifiers</tp:docstring>
</arg>
<arg direction="out" type="a(uv)" tp:type="Property_Value[]"
name="Values">
<!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of structs containing:</p>
<ul>
<li>integer identifiers</li>
<li>variant boxed values</li>
</ul>
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
Some property identifier requested is invalid
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
<tp:docstring>
Some property requested does not have the PROPERTY_FLAG_READ flag
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="ListProperties" tp:name-for-bindings="List_Properties">
<tp:docstring>
Returns a dictionary of the properties available on this channel.
</tp:docstring>
<arg direction="out" type="a(ussu)" tp:type="Property_Spec[]"
name="Available_Properties">
<!-- XXX: if we're ever breaking API compatibility, make this
a{u(ssu)} ? -->
<tp:docstring>
An array of structs containing:
<ul>
<li>an integer identifier</li>
<li>a string property name</li>
<li>a string representing the D-Bus signature of this property</li>
<li>a bitwise OR of the flags applicable to this property</li>
</ul>
</tp:docstring>
</arg>
</method>
<signal name="PropertiesChanged" tp:name-for-bindings="Properties_Changed">
<tp:docstring>
Emitted when the value of readable properties has changed.
</tp:docstring>
<arg name="Properties" type="a(uv)" tp:type="Property_Value[]">
<!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of structs containing:</p>
<ul>
<li>integer identifiers</li>
<li>variant boxed values</li>
</ul>
<p>The array should contain only properties whose values have
actually changed.</p>
</tp:docstring>
</arg>
</signal>
<signal name="PropertyFlagsChanged"
tp:name-for-bindings="Property_Flags_Changed">
<tp:docstring>
Emitted when the flags of some room properties have changed.
</tp:docstring>
<arg name="Properties" type="a(uu)" tp:type="Property_Flags_Change[]">
<!-- XXX: if we're ever breaking API compatibility, make this a{uu} -->
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of structs containing:</p>
<ul>
<li>integer identifiers</li>
<li>a bitwise OR of the current flags</li>
</ul>
<p>The array should contain only properties whose flags have actually
changed.</p>
</tp:docstring>
</arg>
</signal>
<method name="SetProperties" tp:name-for-bindings="Set_Properties">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Takes an array of (identifier, value) pairs containing desired
values to set the given properties. In the case of any errors, no
properties will be changed. When the changes have been acknowledged
by the server, the PropertiesChanged signal will be emitted.</p>
<p>All properties given must have the PROPERTY_FLAG_WRITE flag, or
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.</p>
</tp:docstring>
<arg direction="in" name="Properties" type="a(uv)"
tp:type="Property_Value[]">
<!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
<tp:docstring>
An array mapping integer property 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 xmlns="http://www.w3.org/1999/xhtml">
<p>Interface for channels and other objects, to allow querying and setting
properties. ListProperties returns which properties are valid for
the given channel, including their type, and an integer handle used to
refer to them in GetProperties, SetProperties, and the PropertiesChanged
signal. The values are represented by D-Bus variant types, and are
accompanied by flags indicating whether or not the property is readable or
writable.</p>
<p>Each property also has a flags value to indicate what methods are
available. This is a bitwise OR of PropertyFlags values.</p>
</tp:docstring>
<tp:flags name="Property_Flags" value-prefix="Property_Flag" type="u">
<tp:flag suffix="Read" value="1">
<tp:docstring>The property can be read</tp:docstring>
</tp:flag>
<tp:flag suffix="Write" value="2">
<tp:docstring>The property can be written</tp:docstring>
</tp:flag>
</tp:flags>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->