← Back to branch summary

~ubuntu-branches/ubuntu/utopic/telepathy-python/utopic

« back to all changes in this revision

Viewing changes to spec/Channel_Type_Contact_Search.xml

  • Committer: Bazaar Package Importer
  • Author(s): Laurent Bigonville
  • Date: 2009-06-16 11:23:44 UTC
  • mfrom: (1.1.14 upstream) (8.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090616112344-sslc71m4xns7uv8i
Tags: 0.15.8-1
* New upstream release.
* debian/control:
  - Change package priority to optional
  - Bump Standards-Version to 3.8.1 (no further changes)
  - Be more verbose in package extended description

Show diffs side-by-side

added added

removed removed

Lines of Context:
spec/Channel_Type_Contact_Search.xml
1
1
<?xml version="1.0" ?>
2
2
<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
 
  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
4
 
  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
5
 
  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
 
3
  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
 
4
  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
 
5
  <tp:copyright> Copyright © 2006 INdT </tp:copyright>
6
6
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
7
7
    <p>This library is free software; you can redistribute it and/or
8
8
modify it under the terms of the GNU Lesser General Public
18
18
License along with this library; if not, write to the Free Software
19
19
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
20
20
  </tp:license>
21
 
  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"
22
 
    tp:causes-havoc='not well-tested'>
 
21
  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
 
22
    tp:causes-havoc='experimental'>
23
23
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
24
24
 
25
 
    <tp:struct name="Search_Key_Info">
26
 
      <tp:docstring>A struct representing details on search strings.</tp:docstring>
27
 
      <tp:member type="b" name="Is_Mandatory">
28
 
        <tp:docstring>Booleans indicating if the search key is mandatory.
29
 
          </tp:docstring>
30
 
      </tp:member>
31
 
      <tp:member type="g" name="Type_Signature">
32
 
        <tp:docstring>The type signature of the value for this search key.
33
 
          </tp:docstring>
34
 
      </tp:member>
35
 
    </tp:struct>
36
 
 
37
 
    <tp:mapping name="Search_Key_Info_Map">
38
 
      <tp:docstring>A dictionary mapping string search key names to its search details.
39
 
        </tp:docstring>
40
 
      <tp:member type="s" name="Term"/>
41
 
      <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
42
 
    </tp:mapping>
43
 
 
44
 
    <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
45
 
      <arg direction="out" type="s">
46
 
        <tp:docstring>
47
 
          A string with any instructions from the server
48
 
        </tp:docstring>
49
 
      </arg>
50
 
      <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
51
 
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
52
 
          A dictionary mapping string search key names to its search details.
53
 
        </tp:docstring>
54
 
      </arg>
55
 
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
56
 
        <p>Returns any instructions from the server along with a dictionary of
57
 
        search key names to their types, and a boolean indicating if the key is
58
 
        mandatory. The following well-known search key names should be used
59
 
        where appropriate:</p>
60
 
        <dl>
61
 
          <dt>s:first</dt><dd>The desired contact's given name</dd>
62
 
          <dt>s:last</dt><dd>The desired contact's family name</dd>
63
 
          <dt>s:nick</dt><dd>The desired contact's nickname</dd>
64
 
          <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
65
 
        </dl>
66
 
      </tp:docstring>
67
 
      <tp:possible-errors>
68
 
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
69
 
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
70
 
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
71
 
      </tp:possible-errors>
72
 
    </method>
 
25
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
26
      <p>A channel type for searching server-stored user directories. A new
 
27
        channel should be requested by a client for each search attempt, and
 
28
        closed when the search is completed or the required result has been
 
29
        found in order to free unused handles.</p>
 
30
 
 
31
      <p>Before searching, the
 
32
        <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
 
33
        inspected to determine the valid search keys which can be provided to
 
34
        the <tp:member-ref>Search</tp:member-ref> method. A search request is
 
35
        then started by providing some of these terms to the Search method, and
 
36
        the <tp:member-ref>SearchState</tp:member-ref> will change from
 
37
        <code>Not_Started</code> to <code>In_Progress</code>.  As results are
 
38
        returned by the server, the
 
39
        <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
 
40
        for each contact found; when the search is complete, the search state
 
41
        will be set to <code>Completed</code>. If the search fails after Search
 
42
        has been called, the state will change to <code>Failed</code>.  A
 
43
        running search can be cancelled by calling
 
44
        <tp:member-ref>Stop</tp:member-ref>.</p>
 
45
 
 
46
      <p>If the protocol supports limiting the number of results returned by a
 
47
        search and subsequently requesting more results, after
 
48
        <tp:member-ref>Limit</tp:member-ref> results have been received the
 
49
        search state will be set to <code>More_Available</code>. Clients may
 
50
        call <tp:member-ref>More</tp:member-ref> to request another
 
51
        <tp:member-ref>Limit</tp:member-ref> results. If allowed by the
 
52
        connection manager, clients may specify the "page size" by specifying
 
53
        <tp:member-ref>Limit</tp:member-ref> when calling
 
54
        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
 
55
        </p>
 
56
 
 
57
      <p>The client should call the channel's <tp:dbus-ref
 
58
        namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
 
59
        method when it is finished with the channel, so that any handles held
 
60
        only by the channel can be released.</p>
 
61
 
 
62
      <p>Each channel can only be used for a single search; a new channel
 
63
        should be requested for each subsequent search. Connection managers
 
64
        MUST support multiple ContactSearch channels being open at once (even
 
65
        to the same server, if applicable).</p>
 
66
 
 
67
      <p>It does not make sense to request this channel type using <tp:dbus-ref
 
68
          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
 
69
        clients SHOULD request channels of this type using
 
70
        <tp:dbus-ref
 
71
          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
 
72
        instead.</p>
 
73
 
 
74
      <tp:rationale>
 
75
        <p>A contact search channel that is already in use for a different
 
76
          search isn't useful.</p>
 
77
      </tp:rationale>
 
78
    </tp:docstring>
 
79
 
73
80
    <tp:enum name="Channel_Contact_Search_State" type="u">
74
 
      <tp:enumvalue suffix="Before" value="0">
 
81
      <tp:enumvalue suffix="Not_Started" value="0">
75
82
        <tp:docstring>The search has not started</tp:docstring>
76
83
      </tp:enumvalue>
77
 
      <tp:enumvalue suffix="During" value="1">
 
84
      <tp:enumvalue suffix="In_Progress" value="1">
78
85
        <tp:docstring>The search is in progress</tp:docstring>
79
86
      </tp:enumvalue>
80
 
      <tp:enumvalue suffix="After" value="2">
 
87
      <tp:enumvalue suffix="More_Available" value="2">
 
88
        <tp:docstring>The search has paused, but more results can be retrieved
 
89
          by calling <tp:member-ref>More</tp:member-ref>.</tp:docstring>
 
90
      </tp:enumvalue>
 
91
      <tp:enumvalue suffix="Completed" value="3">
81
92
        <tp:docstring>The search has been completed</tp:docstring>
82
93
      </tp:enumvalue>
 
94
      <tp:enumvalue suffix="Failed" value="4">
 
95
        <tp:docstring>The search has failed</tp:docstring>
 
96
      </tp:enumvalue>
83
97
    </tp:enum>
84
 
    <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
85
 
      <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
86
 
        <tp:docstring>The search state represented as one of the values of
87
 
          ChannelContactSearchState</tp:docstring>
88
 
      </arg>
89
 
      <tp:docstring>
90
 
        Returns the current state of this search channel object.
91
 
      </tp:docstring>
92
 
    </method>
93
 
    <method name="Search">
94
 
      <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
 
98
 
 
99
    <property name="SearchState" tp:name-for-bindings="Search_State"
 
100
      access="read" type="u" tp:type="Channel_Contact_Search_State">
 
101
      <tp:docstring>
 
102
        The current state of this search channel object. Change notification
 
103
        is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
 
104
      </tp:docstring>
 
105
    </property>
 
106
 
 
107
    <signal name="SearchStateChanged"
 
108
      tp:name-for-bindings="Search_State_Changed">
 
109
      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
 
110
        <tp:docstring>The new search state</tp:docstring>
 
111
      </arg>
 
112
      <arg name="Error" type="s" tp:type="DBus_Error_Name">
 
113
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
114
          If the new state is <code>Failed</code>, the name of a D-Bus error
 
115
          describing what went wrong. Otherwise, the empty string.
 
116
        </tp:docstring>
 
117
      </arg>
 
118
      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
 
119
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
120
          <p>Additional information about the state transition, which may
 
121
            include the following well-known keys:</p>
 
122
 
 
123
          <dl>
 
124
            <dt>debug-message (s)</dt>
 
125
            <dd>Debugging information on the change, corresponding to the
 
126
              message part of a D-Bus error message, which SHOULD NOT be
 
127
              displayed to users under normal circumstances</dd>
 
128
          </dl>
 
129
 
 
130
          <tp:rationale>
 
131
            <p>This argument allows for future extensions. For instance,
 
132
              if moving to state <code>Failed</code> because the server
 
133
              rejected one of our search terms, we could define a key
 
134
              that indicates which terms were invalid.</p>
 
135
          </tp:rationale>
 
136
        </tp:docstring>
 
137
      </arg>
 
138
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
139
        <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
 
140
          changes. The implementation MUST NOT make transitions other than the
 
141
          following:</p>
 
142
 
 
143
        <ul>
 
144
          <li><code>Not_Started</code> → <code>In_Progress</code></li>
 
145
          <li><code>In_Progress</code> → <code>More_Available</code></li>
 
146
          <li><code>More_Available</code> → <code>In_Progress</code></li>
 
147
          <li><code>In_Progress</code> → <code>Completed</code></li>
 
148
          <li><code>In_Progress</code> → <code>Failed</code></li>
 
149
        </ul>
 
150
      </tp:docstring>
 
151
    </signal>
 
152
 
 
153
    <tp:simple-type name="Contact_Search_Key" type="s">
 
154
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
155
        <p>Any of the following search keys, with the indicated result for
 
156
          the search:</p>
 
157
 
 
158
        <dl>
 
159
          <dt>The empty string</dt>
 
160
          <dd>Search for the search term in some implementation-dependent
 
161
            set of fields, using an implementation-dependent algorithm
 
162
            (e.g. searching for each word mentioned)
 
163
            <tp:rationale>
 
164
              The "one big search box" approach to searching, as is familiar
 
165
              from Google. The Sametime plugin to Pidgin appears to search in
 
166
              this way.
 
167
            </tp:rationale>
 
168
          </dd>
 
169
 
 
170
          <dt>A <tp:type>VCard_Field</tp:type></dt>
 
171
          <dd>Search for the search term in fields matching that name (for
 
172
            instance, <code>nickname</code> would search nicknames, and
 
173
            <code>tel</code> would search any available phone number,
 
174
            regardless of its work/home/mobile/... status).</dd>
 
175
 
 
176
          <dt>A <tp:type>VCard_Field</tp:type> followed by
 
177
            "<code>;</code>" and a
 
178
            <tp:type>VCard_Type_Parameter</tp:type> of the form
 
179
            "<code>type=...</code>"</dt>
 
180
          <dd>Search for the search term in fields of that name and type
 
181
            only (for instance, <code>tel;type=mobile</code>).</dd>
 
182
 
 
183
          <dt><code>x-telepathy-identifier</code></dt>
 
184
          <dd>Search for contacts whose identifier in the IM protocol
 
185
            matches the search term (e.g. contains it as a substring)
 
186
            <tp:rationale>
 
187
              Otherwise, starting a search by identifier would require the UI
 
188
              to know the vCard field name corresponding to identifiers in
 
189
              this protocol, which might be non-standard (like
 
190
              <code>x-jabber</code>) or not exist at all.
 
191
            </tp:rationale>
 
192
          </dd>
 
193
 
 
194
          <dt><code>x-gender</code></dt>
 
195
          <dd>For the search term "male" or "female", search only for contacts
 
196
            listed as male or female, respectively. The results for other
 
197
            search terms are undefined; it is likely that contacts with
 
198
            unspecified gender will only be matched if this search key
 
199
            is omitted from the request.
 
200
            <tp:rationale>
 
201
              Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
 
202
              also supports limiting search results by gender.
 
203
            </tp:rationale>
 
204
          </dd>
 
205
 
 
206
          <dt><code>x-n-family</code></dt>
 
207
          <dd>Search for the search term in contacts' family names
 
208
            (the first component of the vCard field <code>n</code>).
 
209
            <tp:rationale>
 
210
              Gadu-Gadu and TOC seem to support this mode of searching.
 
211
            </tp:rationale>
 
212
          </dd>
 
213
 
 
214
          <dt><code>x-n-given</code></dt>
 
215
          <dd>Search for the search term in contacts' given names
 
216
            (the second component of the vCard field <code>n</code>).
 
217
            <tp:rationale>
 
218
              As for <code>x-n-family</code>.
 
219
            </tp:rationale>
 
220
          </dd>
 
221
 
 
222
          <dt><code>x-online</code></dt>
 
223
          <dd>For the search term "yes", search only for contacts who are
 
224
            currently online. The results for other search terms are undefined.
 
225
            <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
 
226
          </dd>
 
227
 
 
228
          <dt><code>x-adr-locality</code></dt>
 
229
          <dd>Search for the search term as a locality or city (the fourth
 
230
            component of the vCard field <code>adr</code>).
 
231
            <tp:rationale>
 
232
              Gadu-Gadu and TOC appear to support this.
 
233
            </tp:rationale>
 
234
          </dd>
 
235
        </dl>
 
236
      </tp:docstring>
 
237
    </tp:simple-type>
 
238
 
 
239
    <property name="Limit" type="u" access="read"
 
240
      tp:name-for-bindings="Limit">
 
241
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
242
        <p>If supported by the protocol, the maximum number of results that
 
243
          should be returned, where <code>0</code> represents no limit. If the
 
244
          protocol does not support limiting results, this should be
 
245
          <code>0</code>.</p>
 
246
 
 
247
        <p>For example, if the terms passed to
 
248
          <tp:member-ref>Search</tp:member-ref> match <i>Antonius</i>,
 
249
          <i>Bridget</i> and <i>Charles</i> and this property is
 
250
          <code>2</code>, the search service SHOULD only return <i>Antonius</i>
 
251
          and <i>Bridget</i>.</p>
 
252
 
 
253
        <p>This property cannot change during the lifetime of the channel.
 
254
          This property SHOULD be in the Allowed_Properties of a
 
255
          <tp:type>Requestable_Channel_Class</tp:type> if and only if the
 
256
          protocol supports specifying a limit; implementations SHOULD use
 
257
          <code>0</code> as the default if possible, or a protocol-specific
 
258
          sensible default otherwise.</p>
 
259
      </tp:docstring>
 
260
    </property>
 
261
 
 
262
    <property name="AvailableSearchKeys" type="as" access="read"
 
263
      tp:name-for-bindings="Available_Search_Keys">
 
264
      <tp:docstring>
 
265
        The set of search keys supported by this channel. Example values
 
266
        include [""] (for protocols where several address fields are
 
267
        implicitly searched) or ["x-n-given", "x-n-family", "nickname",
 
268
        "email"] (for XMPP XEP-0055, without extensibility via Data Forms).
 
269
        This property cannot change during the lifetime of a channel.
 
270
 
 
271
        <tp:rationale>
 
272
          It can be in the <tp:dbus-ref
 
273
            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
 
274
          signal for round-trip reduction.
 
275
        </tp:rationale>
 
276
      </tp:docstring>
 
277
    </property>
 
278
 
 
279
    <tp:mapping name="Contact_Search_Map">
 
280
      <tp:docstring>A map from search keys to search terms.</tp:docstring>
 
281
      <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
 
282
        <tp:docstring>
 
283
          The search key to match against
 
284
        </tp:docstring>
 
285
      </tp:member>
 
286
 
 
287
      <tp:member name="Term" type="s">
 
288
        <tp:docstring>
 
289
          The term or terms to be searched for in the search key; depending on
 
290
          the protocol and the server implementation, this may be matched by
 
291
          exact or approximate equality, substring matching, word matching
 
292
          or any other matching algorithm
 
293
        </tp:docstring>
 
294
      </tp:member>
 
295
    </tp:mapping>
 
296
 
 
297
    <method name="Search" tp:name-for-bindings="Search">
 
298
      <arg direction="in" name="Terms"
 
299
        type="a{ss}" tp:type="Contact_Search_Map">
95
300
        <tp:docstring>
96
301
          A dictionary mapping search key names to the desired values
97
302
        </tp:docstring>
98
303
      </arg>
99
304
      <tp:docstring>
100
 
        Send a request to start a search for contacts on this connection. A
101
 
        valid search request will cause the SearchStateChanged signal to be
102
 
        emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
 
305
        Send a request to start a search for contacts on this connection. This
 
306
        may only be called while the <tp:member-ref>SearchState</tp:member-ref>
 
307
        is Not_Started; a valid search request will cause the
 
308
        <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
 
309
        with the state In_Progress.
103
310
      </tp:docstring>
104
311
      <tp:possible-errors>
105
 
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
 
312
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 
313
          <tp:docstring>
 
314
            The <tp:member-ref>SearchState</tp:member-ref> is no longer
 
315
            Not_Started, so this method is no longer available.
 
316
          </tp:docstring>
 
317
        </tp:error>
 
318
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
 
319
          <tp:docstring>
 
320
            The search terms included something this connection manager cannot
 
321
            search for.
 
322
          </tp:docstring>
 
323
        </tp:error>
106
324
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
107
 
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
108
 
      </tp:possible-errors>
109
 
    </method>
 
325
      </tp:possible-errors>
 
326
    </method>
 
327
 
 
328
    <method name="More" tp:name-for-bindings="More">
 
329
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
330
        Request that a search in <tp:member-ref>SearchState</tp:member-ref>
 
331
        <code>More_Available</code> move back to state <code>In_Progress</code>
 
332
        and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.
 
333
      </tp:docstring>
 
334
      <tp:possible-errors>
 
335
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 
336
          <tp:docstring>
 
337
            The <tp:member-ref>SearchState</tp:member-ref> is not
 
338
            <code>More_Available</code>.
 
339
          </tp:docstring>
 
340
        </tp:error>
 
341
      </tp:possible-errors>
 
342
    </method>
 
343
 
 
344
    <method name="Stop" tp:name-for-bindings="Stop">
 
345
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
346
        <p>Stop the current search. This may not be called while the
 
347
          <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called
 
348
          while the SearchState is In_Progress,
 
349
          <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted,
 
350
          with the state Failed and the error
 
351
          <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
 
352
 
 
353
        <p>Calling this method on a search in state Completed or Failed
 
354
          succeeds, but has no effect.</p>
 
355
 
 
356
        <tp:rationale>
 
357
          <p>Specifying Stop to succeed when the search has finished means that
 
358
            clients who call Stop just before receiving
 
359
            <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to
 
360
            handle a useless error.</p>
 
361
        </tp:rationale>
 
362
 
 
363
        <p>Depending on the protocol, the connection manager may not be
 
364
          able to prevent the server from sending further results after this
 
365
          method returns; if this is the case, it MUST ignore any further
 
366
          results.</p>
 
367
      </tp:docstring>
 
368
      <tp:possible-errors>
 
369
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 
370
          <tp:docstring>
 
371
            The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so
 
372
            this method is not yet available.
 
373
          </tp:docstring>
 
374
        </tp:error>
 
375
      </tp:possible-errors>
 
376
    </method>
 
377
 
110
378
    <signal name="SearchResultReceived"
111
379
      tp:name-for-bindings="Search_Result_Received">
112
380
      <arg name="Contact" type="u" tp:type="Contact_Handle">
113
 
        <tp:docstring>An integer handle for the contact</tp:docstring>
 
381
        <tp:docstring>An integer handle for the contact, which will remain
 
382
          valid at least until this Channel closes</tp:docstring>
114
383
      </arg>
115
 
      <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
116
 
        <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
 
384
      <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
 
385
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
386
          <p>An array of fields representing information about this
 
387
            contact, in the same format used in the <tp:dbus-ref
 
388
              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
 
389
            interface. It is possible that a separate call to <tp:dbus-ref
 
390
              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
 
391
            would return more information than this signal provides.</p>
 
392
 
 
393
          <p>This array SHOULD include the <code>x-telepathy-identifier</code>
 
394
            field, whose values matches the result of calling <tp:dbus-ref
 
395
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
 
396
            on the Contact handle.</p>
 
397
 
 
398
          <tp:rationale>
 
399
            <p>UIs will most likely want to show the identifier to the user;
 
400
              while they could do this by inspecting the signalled handle,
 
401
              including it in this signal is cheap and removes a roundtrip to
 
402
              look it up.</p>
 
403
          </tp:rationale>
 
404
        </tp:docstring>
117
405
      </arg>
118
406
      <tp:docstring>
119
407
        Emitted when a search result is received from the server.
120
408
      </tp:docstring>
121
409
    </signal>
122
 
    <signal name="SearchStateChanged"
123
 
      tp:name-for-bindings="Search_State_Changed">
124
 
      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
125
 
        <tp:docstring>An integer representing the new search state</tp:docstring>
126
 
      </arg>
 
410
 
 
411
    <property name="Server" tp:name-for-bindings="Server"
 
412
      type="s" access="read">
127
413
      <tp:docstring>
128
 
        Emitted when the search state (as returned by the GetSearchState
129
 
        method) changes.
 
414
        <p>For protocols which support searching for contacts on multiple
 
415
          servers with different DNS names (like XMPP), the DNS name of the
 
416
          server being searched by this channel, e.g.
 
417
          "characters.shakespeare.lit".  Otherwise, the empty string.</p>
 
418
 
 
419
        <tp:rationale>
 
420
          <p>XEP 0055 defines a mechanism for XMPP clients to search services
 
421
            of their choice for contacts, such as users.jabber.org (the "Jabber
 
422
            User Directory").</p>
 
423
        </tp:rationale>
 
424
 
 
425
        <p>This property cannot change during the lifetime of the channel.
 
426
          This property SHOULD be in the Allowed_Properties of a
 
427
          <tp:type>Requestable_Channel_Class</tp:type> if and only if the
 
428
          protocol supports querying multiple different servers;
 
429
          implementations SHOULD use a sensible default if possible if this
 
430
          property is not specified in a channel request.</p>
 
431
 
 
432
        <tp:rationale>
 
433
          <p>This allows a client to perform searches on a protocol it knows
 
434
            nothing about without requiring the user to guess a valid server's
 
435
            hostname.</p>
 
436
        </tp:rationale>
130
437
      </tp:docstring>
131
 
    </signal>
132
 
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
133
 
    <p>A channel type for searching server-stored user directories. A new channel
134
 
    should be requested by a client for each search attempt, and it should be
135
 
    closed when the search is completed or the required result has been found
136
 
    in order to free unused handles. The search can be cancelled at any time
137
 
    by calling the channel Close method, although depending upon the protocol
138
 
    the connection manager may not be able to prevent the server from sending
139
 
    further results.</p>
 
438
    </property>
140
439
 
141
 
    <p>Before searching, the GetSearchKeys method should be used to discover any
142
 
    instructions sent by the server, and the valid search keys which can be
143
 
    provided to the Search method. A search request is then started by
144
 
    providing some of these terms to the Search method, and the search status
145
 
    will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
146
 
    returned by the server, the SearchResultReceived signal is emitted for each
147
 
    contact found, and when the search is complete, the search status will be
148
 
    set to CHANNEL_SEARCH_STATE_AFTER.</p>
149
 
    </tp:docstring>
150
440
  </interface>
151
441
</node>
152
442
<!-- vim:set sw=2 sts=2 et ft=xml: -->