mirror of https://github.com/moparisthebest/xeps
Use PEP (and XEP-0222) for XEP-0292
While the existing version says this was rejected by community consensus, since then the consensus of most implementations is to use PEP directly even though it was never specified to work, and that the raw-IQ protocol adds complexity. This update removes the raw-IQ mode and specifies the reuse of PEP.
This commit is contained in:
Stephen Paul Weber
parent
2d4b8b5728
commit
ff13349982
239
xep-0292.xml
239
xep-0292.xml
|
|
@ -155,16 +155,18 @@
|
|||
|
||||
<p>This section describes the use of the vCard format for self-publication and retrieval of publicly-accessible information about any entity on an XMPP network, thus fulfilling all the use cases of the old vcard-temp format.</p>
|
||||
|
||||
<section2 topic='IQ-Based Publication and Retrieval' anchor='self-iq'>
|
||||
<p>As in <cite>XEP-0054</cite>, the primary method for publishing and retrieving vCards is the XMPP &IQ; stanza. (Although it would have been possible to use &xep0222; for public storage and retrieval, community consensus is that storage via IQ is more backward-compatible with <cite>XEP-0054</cite>, and that publish-subscribe is more appropriate only for event notifications.)</p>
|
||||
<section3 topic='Retrieval' anchor='self-iq-retrieval'>
|
||||
<p>An XMPP entity retrieves the vCard of another entity (or itself) by sending an IQ-get to the target entity containing a <vcard/> child element (note the lowercase "c"!) qualified by the 'urn:ietf:params:xml:ns:vcard-4.0' namespace.</p>
|
||||
<section2 topic='PEP Publication and Retrieval' anchor='self-iq'>
|
||||
<p>The primary method for publishing and retrieving vCards is via &xep0222; using the node name 'urn:xmpp:vcard4'.</p>
|
||||
<section3 topic='Retrieval' anchor='self-pep-retrieval'>
|
||||
<p>An XMPP entity retrieves the vCard of another entity (or itself) by sending a PEP-get to the target entity for the 'urn:xmpp:vcard4' node.</p>
|
||||
<example caption="vCard Retrieval Request"><![CDATA[
|
||||
<iq from='samizzi@cisco.com/foo'
|
||||
id='bx81v356'
|
||||
to='stpeter@jabber.org'
|
||||
type='get'>
|
||||
<vcard xmlns='urn:ietf:params:xml:ns:vcard-4.0'/>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:vcard4'/>
|
||||
</pubsub>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If a vCard exists for the target entity, the responsible entity (e.g., the XMPP server that hosts the account for a bare JID) MUST return the data in an IQ-result:</p>
|
||||
|
|
@ -173,116 +175,118 @@
|
|||
id='bx81v356'
|
||||
to='samizzi@cisco.com/foo'
|
||||
type='result'>
|
||||
<vcard xmlns="urn:ietf:params:xml:ns:vcard-4.0">
|
||||
<fn><text>Peter Saint-Andre</text></fn>
|
||||
<n><surname>Saint-Andre</surname><given>Peter</given><additional></additional></n>
|
||||
<nickname><text>stpeter</text></nickname>
|
||||
<nickname><text>psa</text></nickname>
|
||||
<photo><uri>https://stpeter.im/images/stpeter_oscon.jpg</uri></photo>
|
||||
<bday><date>1966-08-06</date></bday>
|
||||
<adr>
|
||||
<parameters>
|
||||
<type><text>work</text><text>voice</text></type>
|
||||
<pref><integer>1</integer></pref>
|
||||
</parameters>
|
||||
<ext>Suite 600</ext>
|
||||
<street>1899 Wynkoop Street</street>
|
||||
<locality>Denver</locality>
|
||||
<region>CO</region>
|
||||
<code>80202</code>
|
||||
<country>USA</country>
|
||||
</adr>
|
||||
<adr>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<ext></ext>
|
||||
<street></street>
|
||||
<locality>Parker</locality>
|
||||
<region>CO</region>
|
||||
<code>80138</code>
|
||||
<country>USA</country>
|
||||
</adr>
|
||||
<tel>
|
||||
<parameters>
|
||||
<type><text>work</text><text>voice</text></type>
|
||||
<pref><integer>1</integer></pref>
|
||||
</parameters>
|
||||
<uri>tel:+1-303-308-3282</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters><type><text>work</text><text>fax</text></type></parameters>
|
||||
<uri>tel:+1-303-308-3219</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters>
|
||||
<type><text>cell</text><text>voice</text><text>text</text></type>
|
||||
</parameters>
|
||||
<uri>tel:+1-720-256-6756</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters><type><text>home</text><text>voice</text></type></parameters>
|
||||
<uri>tel:+1-303-555-1212</uri>
|
||||
</tel>
|
||||
<geo><uri>geo:39.59,-105.01</uri></geo>
|
||||
<title><text>Executive Director</text></title>
|
||||
<role><text>Patron Saint</text></role>
|
||||
<org>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<text>XMPP Standards Foundation</text>
|
||||
</org>
|
||||
<url><uri>https://stpeter.im/</uri></url>
|
||||
<note>
|
||||
<text>
|
||||
More information about me is located on my
|
||||
personal website: https://stpeter.im/
|
||||
</text>
|
||||
</note>
|
||||
<gender><sex><text>M</text></sex></gender>
|
||||
<lang>
|
||||
<parameters><pref>1</pref></parameters>
|
||||
<language-tag>en</language-tag>
|
||||
</lang>
|
||||
<email>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<text>psaintan@cisco.com</text>
|
||||
</email>
|
||||
<email>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<text>stpeter@jabber.org</text>
|
||||
</email>
|
||||
<impp>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<uri>xmpp:psaintan@cisco.com</uri>
|
||||
</impp>
|
||||
<impp>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<uri>xmpp:stpeter@jabber.org</uri>
|
||||
</impp>
|
||||
<key>
|
||||
<uri>https://stpeter.im/stpeter.asc</uri>
|
||||
</key>
|
||||
</vcard>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If no vCard exists, the server MUST return an IQ-result containing an empty <vcard/> element.</p>
|
||||
<example caption="No vCard (empty element)"><![CDATA[
|
||||
<iq from='stpeter@jabber.org'
|
||||
id='bx81v356'
|
||||
to='samizzi@cisco.com/foo'
|
||||
type='result'>
|
||||
<vcard xmlns='urn:ietf:params:xml:ns:vcard-4.0'/>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:vcard4'>
|
||||
<item id='e0bf7714-a8dd-4749-8a18-e1979525b0d5'>
|
||||
<vcard xmlns="urn:ietf:params:xml:ns:vcard-4.0">
|
||||
<fn><text>Peter Saint-Andre</text></fn>
|
||||
<n><surname>Saint-Andre</surname><given>Peter</given><additional></additional></n>
|
||||
<nickname><text>stpeter</text></nickname>
|
||||
<nickname><text>psa</text></nickname>
|
||||
<photo><uri>https://stpeter.im/images/stpeter_oscon.jpg</uri></photo>
|
||||
<bday><date>1966-08-06</date></bday>
|
||||
<adr>
|
||||
<parameters>
|
||||
<type><text>work</text><text>voice</text></type>
|
||||
<pref><integer>1</integer></pref>
|
||||
</parameters>
|
||||
<ext>Suite 600</ext>
|
||||
<street>1899 Wynkoop Street</street>
|
||||
<locality>Denver</locality>
|
||||
<region>CO</region>
|
||||
<code>80202</code>
|
||||
<country>USA</country>
|
||||
</adr>
|
||||
<adr>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<ext></ext>
|
||||
<street></street>
|
||||
<locality>Parker</locality>
|
||||
<region>CO</region>
|
||||
<code>80138</code>
|
||||
<country>USA</country>
|
||||
</adr>
|
||||
<tel>
|
||||
<parameters>
|
||||
<type><text>work</text><text>voice</text></type>
|
||||
<pref><integer>1</integer></pref>
|
||||
</parameters>
|
||||
<uri>tel:+1-303-308-3282</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters><type><text>work</text><text>fax</text></type></parameters>
|
||||
<uri>tel:+1-303-308-3219</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters>
|
||||
<type><text>cell</text><text>voice</text><text>text</text></type>
|
||||
</parameters>
|
||||
<uri>tel:+1-720-256-6756</uri>
|
||||
</tel>
|
||||
<tel>
|
||||
<parameters><type><text>home</text><text>voice</text></type></parameters>
|
||||
<uri>tel:+1-303-555-1212</uri>
|
||||
</tel>
|
||||
<geo><uri>geo:39.59,-105.01</uri></geo>
|
||||
<title><text>Executive Director</text></title>
|
||||
<role><text>Patron Saint</text></role>
|
||||
<org>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<text>XMPP Standards Foundation</text>
|
||||
</org>
|
||||
<url><uri>https://stpeter.im/</uri></url>
|
||||
<note>
|
||||
<text>
|
||||
More information about me is located on my
|
||||
personal website: https://stpeter.im/
|
||||
</text>
|
||||
</note>
|
||||
<gender><sex><text>M</text></sex></gender>
|
||||
<lang>
|
||||
<parameters><pref>1</pref></parameters>
|
||||
<language-tag>en</language-tag>
|
||||
</lang>
|
||||
<email>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<text>psaintan@cisco.com</text>
|
||||
</email>
|
||||
<email>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<text>stpeter@jabber.org</text>
|
||||
</email>
|
||||
<impp>
|
||||
<parameters><type><text>work</text></type></parameters>
|
||||
<uri>xmpp:psaintan@cisco.com</uri>
|
||||
</impp>
|
||||
<impp>
|
||||
<parameters><type><text>home</text></type></parameters>
|
||||
<uri>xmpp:stpeter@jabber.org</uri>
|
||||
</impp>
|
||||
<key>
|
||||
<uri>https://stpeter.im/stpeter.asc</uri>
|
||||
</key>
|
||||
</vcard>
|
||||
</item>
|
||||
</items>
|
||||
</pubsub>
|
||||
</iq>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Publication' anchor='self-iq-publication'>
|
||||
<p>An XMPP entity publishes or updates its vCard by sending an IQ-set to itself (typically its bare JID), containing a <vcard/> child element qualified by the 'urn:ietf:params:xml:ns:vcard-4.0' namespace. The publication request needs to include the entire vCard, not a "diff" against the prior data (if any).</p>
|
||||
<p>An XMPP entity publishes or updates its vCard by doing a PEP publish to its own 'urn:xmpp:vcard4' node. The publication request needs to include the entire vCard, not a "diff" against the prior data (if any).</p>
|
||||
<example caption="vCard Publication Request"><![CDATA[
|
||||
<iq from='stpeter@jabber.org/squire
|
||||
id='h3vz319m'
|
||||
to='stpeter@jabber.org'
|
||||
type='set'>
|
||||
<vcard xmlns='urn:ietf:params:xml:ns:vcard-4.0'>
|
||||
[...]
|
||||
</vcard>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:vcard4'>
|
||||
<item>
|
||||
<vcard xmlns='urn:ietf:params:xml:ns:vcard-4.0'>
|
||||
[...]
|
||||
</vcard>
|
||||
</item>
|
||||
</publish>
|
||||
</pubsub>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If no error occurs, the responsible entity returns an IQ-result.</p>
|
||||
|
|
@ -290,38 +294,41 @@
|
|||
<iq from='stpeter@jabber.org'
|
||||
id='bx81v356'
|
||||
to='stpeter@jabber.org/squire'
|
||||
type='result'/>
|
||||
type='result'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:vcard4'>
|
||||
<item id='1e3fdd90-f542-41d3-82ae-33d183467a7a'/>
|
||||
</publish>
|
||||
</pubsub>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: An entity MAY have authorization to update the vCard of another entity (e.g., a server administrator might have authorization to modify the server's vCard).</p>
|
||||
</section3>
|
||||
|
||||
</section2>
|
||||
<section2 topic='Event Notifications' anchor='self-pubsub'>
|
||||
<p>&xep0060; provides a way to subscribe to events, and &xep0163; defines a pubsub profile for events associated with instant messaging (IM) accounts. If PEP is supported by an IM server, it can be used to automatically generate event notifications when a user's vCard is modified.</p>
|
||||
<section3 topic='Location' anchor='self-pubsub-location'>
|
||||
<p>The canonical location for notifications regarding a user's vCard is a pubsub node whose name is "urn:xmpp:vcard4".</p>
|
||||
</section3>
|
||||
<p>&xep0163; also provides a way to subscribe to events. It can be used to automatically generate event notifications when a user's vCard is modified.</p>
|
||||
<section3 topic='Subscribing to vCard Notifications' anchor='self-pubsub-subscribe'>
|
||||
<p>Let us imagine that Juliet wishes to receive the updates that Romeo publishes to his vCard. She has two options:</p>
|
||||
<ol>
|
||||
<li>Implicitly subscribe by advertising support for "urn:xmpp:vcard4+notify" in her &xep0115; data. Romeo's PEP service then automatically sends vCard updates to her when it receives presence from her, until and unless she sends presence of type unavailable or stops advertising an interest in vCard updates. This is in accordance with XEP-0060, section 6.1.</li>
|
||||
<li>Implicitly subscribe by advertising support for "urn:xmpp:vcard4+notify" in her &xep0115; data. Romeo's PEP service then automatically sends vCard updates to her when it receives presence from her, until and unless she sends presence of type unavailable or stops advertising an interest in vCard updates. This is in accordance with &xep0060;, section 6.1.</li>
|
||||
<li>Explicitly subscribe by sending a formal subscription request to the "urn:xmpp:vcard4" node at Romeo's JabberID. Romeo's PEP service might send her all vCard updates even if she is offline at the time (depending on service policies regarding presence integration).</li>
|
||||
</ol>
|
||||
</section3>
|
||||
<section3 topic='Receiving a vCard Notification'>
|
||||
<p>Because Juliet has sent presence to Romeo including Entity Capabilities data that includes the "urn:xmpp:vcard4+notify" feature, Romeo's XMPP server will send a PEP notification to Juliet. The notification can include an XMPP message body for backward-compatibility with XMPP clients that are not pubsub-capable. This is in accordance with XEP-0060, second 6.1.7.</p>
|
||||
<p>Because Juliet has sent presence to Romeo including Entity Capabilities data that includes the "urn:xmpp:vcard4+notify" feature, Romeo's XMPP server will send a PEP notification to Juliet.</p>
|
||||
<example caption="Receiving a vCard publication/update"><![CDATA[
|
||||
<message from='romeo@montague.lit'
|
||||
to='juliet@capulet.lit'
|
||||
type='headline'>
|
||||
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||
<items node='urn:xmpp:vcard4'>
|
||||
<item id='current'/>
|
||||
<item id='1e3fdd90-f542-41d3-82ae-33d183467a7a'/>
|
||||
</items>
|
||||
</event>
|
||||
</message>
|
||||
]]></example>
|
||||
<p>Note: There is no payload, because this is a pure notification (the receiver needs to retrieve the vCard using an IQ-get as described earlier).</p>
|
||||
<p>Note: There is no payload, because this is a pure notification (the receiver needs to retrieve the vCard as described earlier).</p>
|
||||
</section3>
|
||||
</section2>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue