summaryrefslogtreecommitdiff
path: root/spec/Properties_Interface.xml
blob: bc9c8b260faa46f50e20e51a032756d80b88973b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
<?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: -->