← Back to branch summary

~ubuntu-branches/ubuntu/trusty/telepathy-python/trusty

« 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: 2010-11-21 19:49:38 UTC
  • mfrom: (1.4.1 upstream) (11.1.6 sid)
  • mto: (11.1.7 sid)
  • mto: This revision was merged to the branch mainline in revision 20.
  • Revision ID: james.westby@ubuntu.com-20101121194938-ulhgwjq1vnwofzsa
Tags: 0.15.18-1
* New upstream release.
* Bump Standards-Version to 3.9.1
* Switch to dpkg-source 3.0 (quilt) format

Show diffs side-by-side

added added

removed removed

Lines of Context:
spec/Channel_Type_Contact_Search.xml
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.DRAFT"
22
 
    tp:causes-havoc='experimental'>
 
21
  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch">
23
22
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
23
    <tp:added version="0.19.10">
 
24
      as stable API. Changes from draft 2:
 
25
      <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers
 
26
      rather than handles; consequently, the values need not include
 
27
      <tt>x-telepathy-identifier</tt>.
 
28
    </tp:added>
24
29
 
25
30
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26
31
      <p>A channel type for searching server-stored user directories. A new
27
32
        channel should be requested by a client for each search attempt, and
28
33
        closed when the search is completed or the required result has been
29
 
        found in order to free unused handles.</p>
 
34
        found.</p>
30
35
 
31
36
      <p>Before searching, the
32
37
        <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
56
61
 
57
62
      <p>The client should call the channel's <tp:dbus-ref
58
63
        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>
 
64
        method when it is finished with the channel.</p>
61
65
 
62
66
      <p>Each channel can only be used for a single search; a new channel
63
67
        should be requested for each subsequent search. Connection managers
375
379
      </tp:possible-errors>
376
380
    </method>
377
381
 
378
 
    <signal name="SearchResultReceived"
379
 
      tp:name-for-bindings="Search_Result_Received">
380
 
      <arg name="Contact" type="u" tp:type="Contact_Handle">
381
 
        <tp:docstring>An integer handle for the contact, which will remain
382
 
          valid at least until this Channel closes</tp:docstring>
383
 
      </arg>
384
 
      <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
 
382
    <tp:mapping name="Contact_Search_Result_Map">
 
383
      <tp:docstring>A map from contact identifier to search result, emitted in
 
384
        the <tp:member-ref>SearchResultReceived</tp:member-ref>
 
385
        signal.</tp:docstring>
 
386
 
 
387
      <tp:member name="Contact_Identifier" type="s">
 
388
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
389
          The identifier of a contact matching the search terms.
 
390
 
 
391
          <tp:rationale>
 
392
            This is an identifier rather than a handle in case we make handles
 
393
            immortal; see <a
 
394
              href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a>
 
395
            and <a
 
396
              href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347
 
397
            comment 5</a>.
 
398
          </tp:rationale>
 
399
        </tp:docstring>
 
400
      </tp:member>
 
401
 
 
402
      <tp:member name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
385
403
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
386
404
          <p>An array of fields representing information about this
387
405
            contact, in the same format used in the <tp:dbus-ref
388
 
              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
 
406
              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo</tp:dbus-ref>
389
407
            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>
 
408
              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref>
391
409
            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
410
        </tp:docstring>
 
411
      </tp:member>
 
412
    </tp:mapping>
 
413
 
 
414
    <signal name="SearchResultReceived"
 
415
      tp:name-for-bindings="Search_Result_Received">
 
416
      <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map">
 
417
        <tp:docstring>A mapping from contact identifier to an array of fields
 
418
          representing information about this contact.</tp:docstring>
405
419
      </arg>
 
420
 
406
421
      <tp:docstring>
407
 
        Emitted when a search result is received from the server.
 
422
        Emitted when a some search results are received from the server.
 
423
        This signal can be fired arbitrarily many times so clients MUST NOT
 
424
        assume they'll get only one signal.
408
425
      </tp:docstring>
409
426
    </signal>
410
427