mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-22 01:02:17 -05:00
4825961d70
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@45 4b5297f7-1745-476d-ba37-a9c6900126ab
1044 lines
54 KiB
XML
1044 lines
54 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Waiting Lists</title>
|
|
<abstract>This document defines an XMPP protocol extension that enables a user to add a non-IM user to a waiting list and be informed when the contact creates an IM account.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0130</number>
|
|
<status>Active</status>
|
|
<type>Historical</type>
|
|
<jig>Standards JIG</jig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XMPP IM</spec>
|
|
<spec>XEP-0094</spec>
|
|
<spec>XEP-0030</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>waitinglist</shortname>
|
|
<schemaloc>
|
|
<url>http://www.xmpp.org/schemas/waitinglist.xsd</url>
|
|
</schemaloc>
|
|
&stpeter;
|
|
<author>
|
|
<firstname>Yehezkel</firstname>
|
|
<surname>Dallal</surname>
|
|
<email>yehezkeld@followap.com</email>
|
|
</author>
|
|
<author>
|
|
<firstname>Alexandre</firstname>
|
|
<surname>Nolle</surname>
|
|
<email>anolle@francetelecom.com</email>
|
|
</author>
|
|
<author>
|
|
<firstname>Jean-Louis</firstname>
|
|
<surname>Seguineau</surname>
|
|
<email>jean-louis.seguineau@antepo.com</email>
|
|
<jid>jlseguineau@im.antepo.com</jid>
|
|
</author>
|
|
<author>
|
|
<firstname>Mark</firstname>
|
|
<surname>Troyer</surname>
|
|
<email>mtroyer@jabber.com</email>
|
|
<jid>mtroyer@corp.jabber.com</jid>
|
|
</author>
|
|
&val;
|
|
<revision>
|
|
<version>1.3</version>
|
|
<date>2006-09-13</date>
|
|
<initials>psa</initials>
|
|
<remark>Clarified alternate flow for main use case; corrected order of errors and JID pushes; specified that item removal is always the responsibility of the IM user; removed remote-server-not-found example (use item-not-found instead).</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.2</version>
|
|
<date>2006-01-24</date>
|
|
<initials>psa</initials>
|
|
<remark>Adjusted remote-server-timeout flow to recommend IQ result followed by JID push message.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2005-11-30</date>
|
|
<initials>psa</initials>
|
|
<remark>Harmonized root element specification with implemented usage, reversing change made in version 0.5.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2005-08-26</date>
|
|
<initials>psa</initials>
|
|
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2005-08-16</date>
|
|
<initials>psa</initials>
|
|
<remark>Added error case for remote server timeout; specified client and service responsibilities regarding removal of waiting list items in error cases.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2005-05-16</date>
|
|
<initials>psa</initials>
|
|
<remark>Corrected schema and IQ examples by changing root element for namespace from <query/> to <waitlist/> (this had been used for message examples but not IQ examples).</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2005-04-01</date>
|
|
<initials>psa</initials>
|
|
<remark>Changed document type to Informational; corrected Remote Server Error example to use &remoteserver; rather than &unavailable;; added service discovery identity to XMPP Registrar Considerations; corrected text regarding registration of service discovery features; corrected some small errors in the text, examples, and schema.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2004-09-27</date>
|
|
<initials>psa</initials>
|
|
<remark>Corrected error syntax used when Contact URI is not handled by any InteropPartner.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2004-09-03</date>
|
|
<initials>psa</initials>
|
|
<remark>Added alternate flow for situation in which Contact URI is not handled by any InteropPartner; changed headline message type for JID pushes from SHOULD to MAY; clarified semantics of item ID; added name child of item; corrected and updated the XML schema; updated examples to use XMPP error conditions.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2004-03-18</date>
|
|
<initials>psa</initials>
|
|
<remark>Initial version.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.10</version>
|
|
<date>2003-09-03</date>
|
|
<initials>psa</initials>
|
|
<remark>Fixed several small errors in the examples.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.9</version>
|
|
<date>2003-08-22</date>
|
|
<initials>psa</initials>
|
|
<remark>Specified optional use of message type 'headline'; fixed one small error in the examples.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.8</version>
|
|
<date>2003-07-23</date>
|
|
<initials>psa</initials>
|
|
<remark>Changed client-server push mechanism to use <message/> rather than <iq/>, since client may not be online; allowed IQ result to include waitlist information if known; added more detailed disco#info lookup to support discovery of URI types supported.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.7</version>
|
|
<date>2003-07-02</date>
|
|
<initials>psa</initials>
|
|
<remark>Modified to use a generic <uri scheme=''/> element.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.6</version>
|
|
<date>2003-06-26</date>
|
|
<initials>psa</initials>
|
|
<remark>Refactored protocol to use IQ sets that are "pushed" to the component or client (similar to XMPP rosters); added service discovery and agents support; made text more generic; simplified error handling; change name to "Waiting Lists".</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.5</version>
|
|
<date>2003-06-24</date>
|
|
<initials>psa</initials>
|
|
<remark>Added remove use case and protocol; added XML schema.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.4</version>
|
|
<date>2003-06-19</date>
|
|
<initials>psa</initials>
|
|
<remark>Specified protocol.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.3</version>
|
|
<date>2003-06-18</date>
|
|
<initials>psa</initials>
|
|
<remark>Simplified requirements; defined main use case.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.2</version>
|
|
<date>2003-06-16</date>
|
|
<initials>psa</initials>
|
|
<remark>Converted to XML format; formalized use case definitions; minor editorial changes.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2003-06-10</date>
|
|
<initials>an</initials>
|
|
<remark>First draft.</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic="Introduction" anchor='intro'>
|
|
<p>An IM user may want to be informed when a contact creates an IM account. If the user knows some information about the contact (e.g., a phone number or email address), the user's service can use that information to place the contact on a "waiting list", then inform the user when the contact creates an IM account. This document defines an extension to &rfc3920; and &rfc3921; that enables such "waiting list" functionality, including the ability to add contacts on other domains if service providers agree to interoperate (e.g., to add a contact who uses a different mobile telephony service provider).</p>
|
|
<p><em>Note: The protocol defined herein is currently in use at several large service providers in Europe. Others are welcome to use the protocol.</em></p>
|
|
</section1>
|
|
<section1 topic="Glossary" anchor='glossary'>
|
|
<table caption="Terms Used">
|
|
<tr>
|
|
<th>Term</th>
|
|
<th>Definition</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Contact</td>
|
|
<td>A person with whom an IM User seeks to communicate, identified by a URI such as <tel:PhoneNumber> (see &rfc3966;) or <mailto:EmailAddress> (see &rfc2368;).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Customer</td>
|
|
<td>A person who is contracted for services with a ServiceProvider.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IM User</td>
|
|
<td>Any Customer who has registered for instant messaging services.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>InteropPartner</td>
|
|
<td>Any company that agrees to interoperate using the protocol defined herein.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>JID</td>
|
|
<td>The unique identifier of an IM User in the XMPP protocol. Outside the context of an IM session, a JID is of the form &BAREJID; ("bare JID"); within the context of an IM session, a JID is of the form &FULLJID; ("full JID").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ServiceProvider</td>
|
|
<td>A company that provides telephony or email services to a Customer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>URI</td>
|
|
<td>A Uniform Resource Identifier as defined in &rfc3986;. Specific URI schemes that may be useful in this specification include 'tel:', 'mailto:', and 'sip:', but any URI scheme may be used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Waiting List</td>
|
|
<td>A list of Contacts whom an entity (IM User or InteropPartner) is waiting to hear about regarding their status as instant messaging users.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>WaitingListService</td>
|
|
<td>An XMPP service that maintains Waiting lists for IM Users and/or InteropPartners.</td>
|
|
</tr>
|
|
</table>
|
|
</section1>
|
|
<section1 topic="Requirements" anchor='reqs'>
|
|
<p>This protocol is designed so that an IM User can:</p>
|
|
<ol type='1' start='1'>
|
|
<li>Request the user's current Waiting List</li>
|
|
<li>Add a Contact to a local WaitingList (based on some URI associated with the Contact)</li>
|
|
<li>Receive notification from a local WaitingListService if the Contact has (or subsequently creates) an IM account</li>
|
|
<li>Remove a Contact from the Waiting List</li>
|
|
</ol>
|
|
<p>In addition, this protocol is designed so that a ServiceProvider can:</p>
|
|
<ol type='1' start='1'>
|
|
<li>Request the service's current WaitingList</li>
|
|
<li>Add a Contact to a WaitingList at an InteroPartner (based on some URI associated with the Contact)</li>
|
|
<li>Receive notification from the InteropPartner if the Contact has (or subsequently creates) an IM account</li>
|
|
<li>Remove a Contact from the Waiting List</li>
|
|
</ol>
|
|
</section1>
|
|
<section1 topic="Use Cases" anchor='usecases'>
|
|
<section2 topic="IM User Retrieves Current WaitingList" anchor='imuser-retrieve'>
|
|
<p>Before adding or removing Contacts from its WaitingList, an IM User SHOULD retrieve its current WaitingList. The activity flow is as follows:</p>
|
|
<section3 topic="Primary Flow" anchor='imuser-retrieve-primary'>
|
|
<ol type='1' start='1'>
|
|
<li>IM User discovers WaitingListService hosted by ServiceProvider [A1]; it is RECOMMENDED to do this immediately after logging in.</li>
|
|
<li>IM User requests current WaitingList from WaitingListService.</li>
|
|
<li>WaitingListService returns WaitingList to IM User, including any items for which JIDs have been discovered. [A2]</li>
|
|
</ol>
|
|
</section3>
|
|
<section3 topic="Alternate Flows" anchor='imuser-retrieve-alt'>
|
|
<ol type='1' start='1'>
|
|
<li>ServiceProvider does not host a WaitingListService:
|
|
<ol type='1' start='1'>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>IM User does not have a Waiting List:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService returns ¬found; error to IM User.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic="IM User Adds Contact to WaitingList" anchor='imuser-add'>
|
|
<p>An IM User may know a URI for a Contact (e.g., a phone number or email address) but not the Contact's JID. In order to subscribe to the Contact's presence or otherwise communicate with the Contact over an instant messaging system, the IM User first needs to discover the Contact's JID based on a URI for the Contact. However, the Contact may not yet have an IM account. Because the IM User may therefore need to wait until the Contact creates an account, the IM User needs to add the Contact to a WaitingList. The activity flow is as follows:</p>
|
|
<section3 topic="Primary Flow" anchor='imuser-add-primary'>
|
|
<ol type='1' start='1'>
|
|
<li>IM User completes <link url='#imuser-retrieve'>IM User Retrieves Current WaitingList</link> use case.</li>
|
|
<li>IM User requests addition of Contact to WaitingList based on Contact's URI.</li>
|
|
<li>WaitingListService determines that the URI scheme is supported. [A1]</li>
|
|
<li>WaitingListService determines that the information provided is a valid URI for that URI scheme. [A2]</li>
|
|
<li>WaitingListService determines that Contact's URI does not belong to a person served by ServiceProvider. [A3]</li>
|
|
<li>WaitingListService acknowledges addition of Contact to IM User's WaitingList.</li>
|
|
<li>WaitingListService discovers WaitingListServices hosted by one or more InteropPartners.</li>
|
|
<li>WaitingListService queries one or more InteropPartner's WaitingListServices for JID associated with URI.</li>
|
|
<li>InteropPartner's WaitingListService determines that Contact's URI belongs to a person served by that partner. [A4]</li>
|
|
<li>InteropPartner's WaitingListService determines that Contact is an IM User. [A5]</li>
|
|
<li>InteropPartner's WaitingListService informs ServiceProvider's WaitingListService of JID associated with Contact's URI. [A6] [A10]</li>
|
|
<li>ServiceProvider's WaitingListService informs IM User of Contact's JID. [A8]</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</section3>
|
|
<section3 topic="Alternate Flows" anchor='imuser-add-alt'>
|
|
<ol type='1' start='1'>
|
|
<li>The URI scheme is not supported:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService sends &badrequest; error to IM User and does not add contact to WaitingList.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>The information provided is not a valid URI:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService sends ¬acceptable; error to IM User and does not add contact to WaitingList.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>URI belongs to person served by ServiceProvider:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService determines that Contact is an IM User registered with ServiceProvider [A7].</li>
|
|
<li>WaitingListService informs IM User of Contact's JID. [A9]</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</li>
|
|
<li>URI does not belong to a person served by InteropPartner:
|
|
<ol type='1' start='1'>
|
|
<li>InteropPartner sends ¬found; error to WaitingListService.</li>
|
|
<li>If all InteropPartners queried return ¬found; error, WaitingListService sends ¬found; error (or local equivalent) to IM User.</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>Contact is not an IM User registered with InteropPartner:
|
|
<ol type='1' start='1'>
|
|
<li>InteropPartner records and acknowledges WaitingListService's request for JID associated with URI.</li>
|
|
<li>OPTIONALLY, InteropPartner invites Contact to register as an IM User.</li>
|
|
<li>Contact registers.</li>
|
|
<li>InteropPartner informs Service Provider's WaitingListService of JID associated with Contact's URI.</li>
|
|
<li>ServiceProvider's WaitingListService informs all IM Users who requested JID associated with Contact's URI.</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</li>
|
|
<li>InteropPartner refuses to provide service to ServiceProvider:
|
|
<ol type='1' start='1'>
|
|
<li>InteropPartner's WaitingListService sends ¬authorized; error to ServiceProvider's WaitingListService.</li>
|
|
<li>If all other InteropPartners also return errors, WaitingListService returns ¬found; error to IM User.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>Contact is not an IM User registered with ServiceProvider:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService records IM User's request for JID associated with URI.</li>
|
|
<li>OPTIONALLY, WaitingListService invites Contact to register as an IM User.</li>
|
|
<li>Contact registers.</li>
|
|
<li>WaitingListService informs all IM Users who requested JID associated with Contact's URI.</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</li>
|
|
<li>Contact's URI is not handled by any ServiceProvider:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService informs all IM Users who requested JID associated with Contact's URI that no InteropPartner services Contact's URI.</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>IM User completes <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.
|
|
<ol type='1' start='1'>
|
|
<li>ServiceProvider's WaitingListService removes item from WaitingList.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
<li>All Users Remove Contact from Their WaitingLists
|
|
<ol type='1' start='1'>
|
|
<li>ServiceProvider's WaitingListService removes item from WaitingList at InteropPartner's WaitingListService.</li>
|
|
<li>Use Case Ends unsuccessfully.</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic="IM User Removes Contact from WaitingList" anchor='imuser-remove'>
|
|
<p>An IM User should remove a contact from the WaitingList after the <link url='#imuser-add'>IM User Adds Contact to WaitingList</link> use case ends (either successfully or unsuccessfully), and may remove a contact from the WaitingList at any other time.</p>
|
|
<section3 topic="Primary Flow" anchor='imuser-remove-primary'>
|
|
<ol type='1' start='1'>
|
|
<li>IM User sends removal request to WaitingListService.</li>
|
|
<li>WaitingListService removes IM User's request for JID associated with URI.</li>
|
|
<li>WaitingListService informs IM User of successful removal [A1].</li>
|
|
<li>WaitingListService sends removal request to appropriate InteropPartner's WaitingListService [A2].</li>
|
|
<li>InteropPartner's WaitingListService determines that URI belongs to a person served by that partner.</li>
|
|
<li>InteropPartner's WaitingListService removes ServiceProvider's WaitingListService's request for JID.</li>
|
|
<li>InteropPartner's WaitingListService informs ServiceProvider's WaitingListService of successful removal.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</section3>
|
|
<section3 topic="Alternate Flows" anchor='imuser-remove-alt'>
|
|
<ol type='1' start='1'>
|
|
<li>IM User never requested JID associated with URI:
|
|
<ol type='1' start='1'>
|
|
<li>WaitingListService sends ¬found; error to IM User.</li>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</li>
|
|
<li>Contact URI is served by WaitingListService or IM User was not the only person who requested the JID:
|
|
<ol type='1' start='1'>
|
|
<li>Use Case Ends.</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic="Protocol" anchor='protocol'>
|
|
<section2 topic="IM User Interaction With WaitingListService" anchor='protocol-imuser'>
|
|
<p>
|
|
<em>This section of the document is provided for the sake of domains that implement XMPP as their local protocol; domains that implement another protocol will use their service-specific protocol to complete the user-to-domain interaction.</em>
|
|
</p>
|
|
<section3 topic="IM User Retrieves Current WaitingList" anchor='protocol-imuser-retrieve'>
|
|
<p>It is RECOMMENDED for an IM User's client to retrieve the WaitingList immediately after logging in. However, first it must discover its local WaitingListService. An IM User MAY use either &xep0030; or the deprecated &xep0094; protocol.</p>
|
|
<example caption="IM User Discovers WaitingListService by Sending Agent Information Request to its Server"><![CDATA[
|
|
<iq type='get' id='agent1'>
|
|
<query xmlns='jabber:iq:agents'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Server Returns Address of its WaitingListService"><![CDATA[
|
|
<iq type='result' id='agent1'>
|
|
<query xmlns='jabber:iq:agents'>
|
|
...
|
|
<agent jid='waitlist.service-provider.com'>
|
|
<name>Waiting List Service</name>
|
|
<service>waitinglist</service>
|
|
</agent>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="IM User Discovers WaitingListService by Sending Service Discovery Request to its Server"><![CDATA[
|
|
<iq type='get' id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Server Returns Address of its WaitingListService"><![CDATA[
|
|
<iq type='result' id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
...
|
|
<item jid='waitlist.service-provider.com'
|
|
name='Waiting List Service'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="IM User Queries WaitingListService for Detailed Information"><![CDATA[
|
|
<iq type='get'
|
|
from='user@service-provider.com/resource'
|
|
to='waitlist.service-provider.com'
|
|
id='disco2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The WaitingListService SHOULD return detailed information about the service it provides, including the URI schemes it supports (see also the <link url='#registrar-features'>Service Discovery Features</link> section of this document).</p>
|
|
<example caption="WaitingListService Returns Detailed Information"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='disco2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity category='directory' type='waitinglist'/>
|
|
<feature var='http://jabber.org/protocol/waitinglist'/>
|
|
<feature var='http://jabber.org/protocol/waitinglist/schemes/mailto'/>
|
|
<feature var='http://jabber.org/protocol/waitinglist/schemes/tel'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>Once an IM User has discovered the WaitingListService, the user's client SHOULD request its current Waiting List. This is done by sending an IQ-get to the WaitingListService containing an empty <query/> element qualified by the 'http://jabber.org/protocol/waitinglist' namespace:</p>
|
|
<example caption="IM User Requests its Current WaitingList"><![CDATA[
|
|
<iq type='get'
|
|
from='user@service-provider.com/resource'
|
|
to='waitlist.service-provider.com'
|
|
id='request1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Upon request, the WaitingListService MUST return the current WaitingList to the IM User:</p>
|
|
<example caption="WaitingListService Returns WaitingList to IM User"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='request1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='12345'>
|
|
<uri scheme='tel'>3033083282</uri>
|
|
<name>PSA</name>
|
|
</item>
|
|
<item id='23456'>
|
|
<uri scheme='mailto'>editor@jabber.org</uri>
|
|
<name>XMPP Extensions Editor</name>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>Each ItemID MUST be unique within the scope of the client's WaitingList items. The value of the ItemID is an opaque string; an implementation MAY assign semantic meaning to the ItemID (e.g., id="John Smith (mobile)" rather than id="12345"), but such meaning is implementation-specific and outside the scope of the protocol defined herein. The user MAY include a <name/> element containing a natural-language name for the Contact.</p>
|
|
<p>The WaitingList MAY contain an item for which a JID has been discovered.</p>
|
|
<example caption="IM User Asks for its WaitingList including Newly Discovered JID"><![CDATA[
|
|
<iq type='get'
|
|
from='user@service-provider.com/resource'
|
|
to='waitlist.service-provider.com'
|
|
id='jidask1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='jidask1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='12345' jid='stpeter@jabber.org'>
|
|
<uri scheme='tel'>3033083282</uri>
|
|
<name>PSA</name>
|
|
</item>
|
|
<item id='23456'>
|
|
<uri scheme='mailto'>editor@jabber.org</uri>
|
|
<name>XMPP Extensions Editor</name>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
<section3 topic="IM User Adds Contact to WaitingList" anchor='protocol-imuser-add'>
|
|
<p>Once an IM User's client has discovered the WaitingListService and requested the user's WaitingList, the user can add Contacts to the WaitingList based on the Contact's URI. (Note: This document uses the example of phone numbers via the 'tel' URI scheme, but the same rules apply to WaitingList items based on email addresses or other URI schemes.)</p>
|
|
<example caption="IM User Requests Addition of Contact to WaitingList"><![CDATA[
|
|
<iq type='set'
|
|
to='waitlist.service-provider.com'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>As described below, various error conditions may occur. (For information about error syntax, refer to <cite>RFC 3920</cite> and &xep0086;.)</p>
|
|
<p>If the IM User provided a URI whose scheme is not supported, WaitingListService MUST return a &badrequest; error to the IM User and MUST NOT add the Contact to the WaitingList.</p>
|
|
<example caption='WaitingListService Returns &badrequest; Error to IM User'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tag'>shakespeare.lit,2005-08:waitlist1</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</query>
|
|
<error code='400' type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the IM User included a JID in the request, WaitingListService MUST return a &badrequest; error to IM User and MUST NOT add the Contact to the WaitingList. (Note: A WaitingListService MUST NOT return a non-XMPP URI to an IM User based on the Contact's JID; see the <link url='#security'>Security Considerations</link> section of this document.)</p>
|
|
<example caption='WaitingListService Returns &badrequest; Error to IM User'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item jid='some-jid'>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</query>
|
|
<error code='400' type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the IM User provided an invalid URI (e.g., a phone number with too many digits or an email address with no '@' character), WaitingListService MUST return a ¬acceptable; error to the IM User and MUST NOT add the Contact to the WaitingList.</p>
|
|
<example caption='WaitingListService Returns ¬acceptable; Error to IM User'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>+1234563033083283</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</query>
|
|
<error code='406' type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If one of the foregoing errors was generated (all of which have a type of "modify"), IM User SHOULD modify the request and re-submit it.</p>
|
|
<p>If none of the "modify" errors was generated, WaitingListService MUST inform the IM User that the request was successfully received, including a unique ID number for the new WaitingList item.</p>
|
|
<example caption="WaitingListService Informs IM User that Request was Received"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If none of the "modify" errors was generated and WaitingListService knows Contact JID when the IQ result is returned to the user (e.g., because Contact is served by ServiceProvider), WaitingListService MAY include the WaitingList item in the IQ result: <note>Even if WaitingListService returns Contact JID in the IQ-result, it MUST also send a "JID push" message.</note></p>
|
|
<example caption="WaitingListService Returns IQ Result to IM User (With Contact JID)"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567' jid='contact@service-provider.com'>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If none of the "modify" errors was generated and WaitingListService does not know Contact JID when the IQ result is returned to the user, it needs to contact InteropPartners in order to determine if the Contact is associated with one of the InteropPartners. Thus before it returns the Contact JID to the IM User, it needs to wait for the one of the InteropPartners to return Contact JID or for all of the InteropPartners to return errors.</p>
|
|
<p>If all of the InteropPartners return an error of type "cancel" (typically ¬found; and/or ¬authorized;) to WaitingListService, WaitingListService MUST return an ¬found; error (or local equivalent) to the IM User (and IM User SHOULD complete <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case).</p>
|
|
<example caption='WaitingListService Returns ¬found; Error to IM User'><![CDATA[
|
|
<message
|
|
type='error'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<waitlist xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>+1234563033083283</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</waitlist>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</message>
|
|
]]></example>
|
|
<p>If the connection to at least one of the InteropPartners times out (a &timeout; error), WaitingListService MUST return an IQ-result as described above (indicating that the request was received) and resend the request to the InteropPartners that timed out. If connections continue to time out (over some configurable time period and for some configurable number of retries), WaitingListService SHOULD then return a &timeout; error to IM User via a "JID push" message as shown below.</p>
|
|
<p>If InterPartner's WaitingListService knows the Contact JID, it sends it to ServiceProvider's WaitingListService as shown in the <link url='#protocol-service-add'>ServiceProvider's WaitingListService Adds Contact to WaitingList</link> section of this document.</p>
|
|
<p>If WaitingListService knows Contact JID (or learns Contact JID from InteropPartner), it MUST inform IM User through a "JID push" message, which consists of a message stanza that contains a <waitlist/> element qualified by the 'http://jabber.org/protocol/waitinglist' namespace:
|
|
<note>When waiting list information is included in a message stanza, the root element for the 'http://jabber.org/protocol/waitinglist' namespace is <waitlist/> rather than <query/> (as used within IQ stanzas). This disparity is historical and tracks the protocol syntax that was most widely implemented, as defined in version 0.4 of this specification. In the interest of interoperability, the IQ usage was changed back to <query/> in version 1.1 of this specification. If this document were not historical, the root element usage would be harmonized to use only the <waitlist/> element.</note>
|
|
</p>
|
|
<example caption="WaitingListService Pushes Contact's JID to IM User"><![CDATA[
|
|
<message
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com'>
|
|
<body>This message contains a WaitingList item.</body>
|
|
<waitlist xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567' jid='contact@service-provider.com'>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</waitlist>
|
|
</message>
|
|
]]></example>
|
|
<p>Note: The JID push uses an XMPP <message/> stanza because the WaitingListService has no knowledge of the user's presence and therefore cannot assume that an &IQ; stanza will be received by the user at a specific resource.</p>
|
|
<p>If WaitingListService learns that Contact's URI is not handled by any InteropPartner, it MUST inform IM User through a "JID push" message:</p>
|
|
<example caption="WaitingListService Informs IM User that No InteropPartner Handles Contact's URI"><![CDATA[
|
|
<message
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com'>
|
|
<body>Sorry, we cannot find this contact.</body>
|
|
<waitlist xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'
|
|
jid='contact@service-provider.com'
|
|
type='error'>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
<name>contact-name</name>
|
|
<error code='404'
|
|
type='cancel'
|
|
xmlns='jabber:client'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</item>
|
|
</waitlist>
|
|
</message>
|
|
]]></example>
|
|
<p>After receiving the "JID push" message, IM User SHOULD complete the <link url='#imuser-remove'>IM User Removes Contact from WaitingList</link> use case.</p>
|
|
</section3>
|
|
<section3 topic="IM User Removes Contact from WaitingList" anchor='protocol-imuser-remove'>
|
|
<p>In order to remove the item from the WaitingList, the IM User MUST complete the <link url='#imuser-remove'>Remove Contact from WaitingList</link> use case.</p>
|
|
<example caption="IM User Sends Removal Request to WaitingListService"><![CDATA[
|
|
<iq type='set'
|
|
from='user@service-provider.com/resource'
|
|
to='waitlist.service-provider.com'
|
|
id='remove1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'>
|
|
<remove/>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If WaitingListService previously recorded request, WaitingListService removes request from list and returns result to IM User.</p>
|
|
<example caption="WaitingListService Returns Result to IM User"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='remove1'/>
|
|
]]></example>
|
|
<p>If WaitingListService did not previously record this request, WaitingListService MUST return an ¬found; error to the IM User.</p>
|
|
<example caption='WaitingListService Returns ¬found; Error to IM User'><![CDATA[
|
|
<iq type='error' id='remove1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'>
|
|
<remove/>
|
|
</item>
|
|
</query>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic="WaitingListService Interaction With InteropPartners" anchor='protocol-service'>
|
|
<p>
|
|
<em>This section of the document describes the inter-domain protocol for communication between WaitingListServices. The protocol defined in this section MUST be implemented by ServiceProviders.</em>
|
|
</p>
|
|
<p>A ServiceProvider's WaitingListService MUST be configured with a "whitelist" of InteropPartner's WaitingListServices with which it communicates. Therefore service discovery SHOULD NOT be necessary. However, if necessary it MAY use either the <cite>Agent Information</cite> protocol or the <cite>Service Discovery</cite> protocol as described in the following examples.</p>
|
|
<p>Note: The InteropPartner's WaitingListService is not required to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.</p>
|
|
<section3 topic="ServiceProvider's WaitingListService Retrieves Current WaitingList" anchor='protocol-service-retrieve'>
|
|
<example caption="ServiceProvider Discovers InteropPartner's WaitingListService by Sending Agent Information Request to InteropPartner"><![CDATA[
|
|
<iq type='get'
|
|
from='waitlist.service-provider.com'
|
|
to='interop-partner.com'
|
|
id='agent2'>
|
|
<query xmlns='jabber:iq:agents'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="InteropPartner Returns Address of its WaitingListService"><![CDATA[
|
|
<iq type='result'
|
|
from='interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='agent2'>
|
|
<query xmlns='jabber:iq:agents'>
|
|
...
|
|
<agent jid='waitlist.interop-partner.com'>
|
|
<name>Waiting List Service</name>
|
|
<service>waitinglist</service>
|
|
</agent>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="ServiceProvider Discovers InteropPartner's WaitingListService by Sending Service Discovery Request to InteropPartner"><![CDATA[
|
|
<iq type='get'
|
|
from='waitlist.service-provider.com'
|
|
to='interop-partner.com'
|
|
id='disco3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="InteropPartner Returns Address of its WaitingListService"><![CDATA[
|
|
<iq type='result' id='disco3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
...
|
|
<item jid='waitlist.service-provider.com'
|
|
name='Waiting List Service'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service Provider Queries InteropPartner's WaitingListService for Detailed Information"><![CDATA[
|
|
<iq type='get'
|
|
from='waitlist.service-provider.com'
|
|
to='waitlist.interop-partner.com'
|
|
id='disco4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="InteropPartner's WaitingListService Returns Detailed Information"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='disco4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity category='directory'
|
|
type='waitinglist'/>
|
|
<feature var='http://jabber.org/protocol/waitinglist'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
<section3 topic="ServiceProvider's WaitingListService Adds Contact to WaitingList" anchor='protocol-service-add'>
|
|
<p>Once a ServiceProvider's WaitingListService has discovered the InteropPartner's WaitingListService and requested its WaitingList, the ServiceProvider's WaitingListService can add items to its WaitingList based on URI.</p>
|
|
<example caption="ServiceProvider's WaitingListService Adds New Item to WaitingList"><![CDATA[
|
|
<iq type='set'
|
|
from='waitlist.service-provider.com'
|
|
to='waitlist.interop-partner.com'
|
|
id='waitinglist2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If InteropPartner refuses to provide service to ServiceProvider, it MUST return a ¬authorized; error to the ServiceProvider:</p>
|
|
<example caption='InteropPartner Returns ¬authorized; Error to ServiceProvider'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='waitinglist2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
</item>
|
|
</query>
|
|
<error code='401' type='cancel'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If Contact's URI is not associated with a person served by this InteropPartner, the InteropPartner MUST return an ¬found; error to the ServiceProvider.</p>
|
|
<example caption='InteropPartner Returns ¬found; Error to ServiceProvider'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='waitinglist2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
</item>
|
|
</query>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If ServiceProvider's WaitingListService receives ¬authorized; and/or ¬found; errors from all InteropPartners, it returns a ¬found; error to IM User:</p>
|
|
<example caption='WaitingListService Returns ¬found; Error to IM User'><![CDATA[
|
|
<message
|
|
type='error'
|
|
from='waitlist.service-provider.com'
|
|
to='user@service-provider.com/resource'
|
|
id='waitinglist1'>
|
|
<waitlist xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item>
|
|
<uri scheme='tel'>+1234563033083283</uri>
|
|
<name>contact-name</name>
|
|
</item>
|
|
</waitlist>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</message>
|
|
]]></example>
|
|
<p>If Contact's URI is associated with a person served by this InteropPartner, InteropPartner MUST return acknowledgement of the WaitingList addition to the ServiceProvider's WaitingListService.</p>
|
|
<example caption="InteropPartner's WaitingListService Acknowledges Receipt"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='waitinglist2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If Contact is an IM User served by InteropPartner, InteropPartner's WaitingListService pushes Contact's JID to ServiceProvider's WaitingListService.</p>
|
|
<example caption="InteropPartner's WaitingListService Pushes Contact's JID to ServiceProvider's WaitingListService"><![CDATA[
|
|
<iq type='set'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='jidpush1'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567' jid='user@domain'>
|
|
<uri scheme='tel'>contact-number</uri>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="ServiceProvider's WaitingListService Acknowledges Receipt of JID Push"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.service-provider.com'
|
|
to='waitlist.interop-partner.com'
|
|
id='jidpush1'/>
|
|
]]></example>
|
|
<p>After receiving acknowledgement (but not before), InteropPartner's WaitingListService MUST remove that item from the WaitingList for the ServiceProvider's WaitingListService.</p>
|
|
</section3>
|
|
<section3 topic="ServiceProvider's WaitingListService Removes Contact from WaitingList" anchor='protocol-service-remove'>
|
|
<example caption="ServiceProvider Requests Removal of Item from WaitingList"><![CDATA[
|
|
<iq type='set'
|
|
from='waitlist.service-provider.com'
|
|
to='waitlist.interop-partner.com'
|
|
id='remove2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'>
|
|
<remove/>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If item exists on WaitingList, InteropPartner's WaitingListService removes item from list and returns result to ServiceProvider's WaitingListService.</p>
|
|
<example caption="InteropPartner Returns Result to ServiceProvider"><![CDATA[
|
|
<iq type='result'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='remove2'/>
|
|
]]></example>
|
|
<p>If item does not exist on WaitingList, InteropPartner's WaitingListService MUST return an ¬found; error to the ServiceProvider's WaitingListService.</p>
|
|
<example caption='InteropPartner Returns ¬found; Error to ServiceProvider'><![CDATA[
|
|
<iq type='error'
|
|
from='waitlist.interop-partner.com'
|
|
to='waitlist.service-provider.com'
|
|
id='remove2'>
|
|
<query xmlns='http://jabber.org/protocol/waitinglist'>
|
|
<item id='34567'>
|
|
<remove/>
|
|
</item>
|
|
</query>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic="Implementation Notes" anchor='impl'>
|
|
<ol type='1' start='1'>
|
|
<li><p>Protocols and mechanisms for inviting a Contact to register as an IM User are out of scope for this document and shall be determined by each InteropPartner individually.</p></li>
|
|
<li><p>A ServiceProvider's WaitingListService MUST record which of its IM Users have requested the JID associated with Contact's URI, and an InteropPartner's WaitingListService MUST record that Service Provider's WaitingListService (not User) has requested JID associated with Contact's URI. Therefore when Contact registers, InteropPartner's WaitingListService informs its local users as well as ServiceProvider's WaitingListService, and ServiceProvider's WaitingListService informs its local users.</p></li>
|
|
<li><p>The InteropPartner's WaitingListService is not required to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.</p></li>
|
|
<li><p>Once an IM User learns a Contact's JID, the IM User MAY send a normal subscription request to the Contact, setting the "to" address to Contact's JID. This interaction is defined in the base XMPP specifications and is out of scope for this document.</p></li>
|
|
<li><p>For historical reasons, implementations MUST support the older <cite>Agent Information</cite> protocol (XEP-0094) and SHOULD support <cite>Service Discovery</cite> (XEP-0030). Note well that the <cite>Agent Information</cite> protocol will eventually be deprecated in favor of <cite>Service Discovery</cite>.</p></li>
|
|
<li><p>An IM User's client receives WaitingList information either through a "JID push" message (received from WaitingListService at any time) or in the IQ result received after requesting the WaitingList (since one or more of the WaitingList items may contain a JID). (The same rule applies to a ServiceProvider's WaitingListService that receives an IQ set from an InteropPartner's WaitingListService.)</p></li>
|
|
<li><p>When an IM User logs in, the user's client SHOULD request the current WaitingList.</p></li>
|
|
<li><p>Although the examples in this document show the hostname of the WaitingListService as 'waitlist.third-party.com' (etc.), this is for convenience only; the hostname MAY be any valid DNS hostname.</p></li>
|
|
<li><p>When sending JID pushes, an implementation MAY specify a message type of 'headline', which in some deployments will prevent such messages from being stored offline for later delivery.</p></li>
|
|
<li><p>It can happen that WaitingListService does not receive a reply from InteropPartner within a certain amount of time or the connection to InteropPartner times out. Because such behavior is often transient, WaitingListService MAY attempt to reconnect and then resend the request (although any retry logic to handle these cases is a matter of implementation). However, WaitingListService SHOULD NOT return an ¬found; error to IM User unless it knows definitively that the Contact's InteropPartner is permanently unavailable, since returning an ¬found; error in response to temporary connection timeouts is likely to be misleading.</p></li>
|
|
</ol>
|
|
</section1>
|
|
<section1 topic="Security Considerations" anchor='security'>
|
|
<p>A ServiceProvider's WaitingListService MUST be configured with a "whitelist" of InteropPartners with which it communicates. The WaitingListService SHOULD NOT communicate with any InteropPartners that are not on the whitelist.</p>
|
|
<p>Requesting JIDs via WaitingLists is not bidirectional; i.e., a service MUST NOT allow an IM User to discover a Contact's non-XMPP URI based on the Contact's JID.</p>
|
|
<p>A service MAY require a Contact to approve the disclosure of the Contact's JID, either as a global preference or for each request; however, this is a local policy matter.</p>
|
|
</section1>
|
|
<section1 topic="IANA Considerations" anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic="XMPP Registrar Considerations" anchor='registrar'>
|
|
<section2 topic="Protocol Namespaces" anchor='registrar-ns'>
|
|
<p>The ®ISTRAR; includes 'http://jabber.org/protocol/waitinglist' in its registry of protocol namespaces.</p>
|
|
</section2>
|
|
<section2 topic="Service Discovery Identities" anchor='registrar-identities'>
|
|
<p>The Jabber Registar includes a type of "waitinglist" in the "directory" category in its registry of service discovery identities.</p>
|
|
</section2>
|
|
<section2 topic="Service Discovery Features" anchor='registrar-features'>
|
|
<p>The XMPP Registrar includes supported URI schemes in its registry of service discovery features. These features shall be of the form 'http://jabber.org/protocol/waitlist/schemes/SCHEME-NAME'.</p>
|
|
<p>This document registers the following two namespace names for URI schemes, but others MAY be registered in the future using standard registration procedures:</p>
|
|
<ul>
|
|
<li>http://jabber.org/protocol/waitlist/schemes/mailto</li>
|
|
<li>http://jabber.org/protocol/waitlist/schemes/tel</li>
|
|
</ul>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic="XML Schema" anchor='schema'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/waitinglist'
|
|
xmlns='http://jabber.org/protocol/waitinglist'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0130: http://www.xmpp.org/extensions/xep-0130.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:import namespace='jabber:client'/>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
Note: there are two allowable root elements for the
|
|
'http://jabber.org/protocol/waitinglist' namespace,
|
|
query and waitlist. The query element is used within
|
|
IQ stanzas and the waitlist element is used within
|
|
message stanzas. See XEP-0130 for details.
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='waitlist'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='item'
|
|
minOccurs='0'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='query'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='item'
|
|
minOccurs='0'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='item'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' maxOccurs='1'>>
|
|
<xs:all xmlns:xmpp='jabber:client'>
|
|
<xs:element ref='uri'/>
|
|
<xs:element ref='name' minOccurs='0'/>
|
|
<xs:element ref='xmpp:error' minOccurs='0'/>
|
|
</xs:all>
|
|
<xs:element ref='remove'/>
|
|
</xs:choice>
|
|
<xs:attribute name='id'
|
|
type='xs:string'
|
|
use='optional'/>
|
|
<xs:attribute name='jid'
|
|
type='xs:string'
|
|
use='optional'/>
|
|
<xs:attribute name='type'
|
|
use='optional'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='error'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='uri' type='xs:string'>
|
|
<xs:complexType>
|
|
<xs:attribute name='scheme'
|
|
type='xs:NCNAME'
|
|
use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='name' type='string1023'/>
|
|
|
|
<xs:element name='remove' type='empty'/>
|
|
|
|
<xs:simpleType name='string1023'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:maxLength value='1023'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
</xep>
|