-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathxep-0208.xml
172 lines (161 loc) · 9.19 KB
/
xep-0208.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
<?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>Bootstrapping Implementation of Jingle</title>
<abstract>This document provides guidelines to XMPP client developers for bootstrapping implementation of Jingle technologies.</abstract>
&LEGALNOTICE;
<number>0208</number>
<status>Retracted</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0166</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>0.4</version>
<date>2009-01-06</date>
<initials>psa</initials>
<remark><p>Retracted because unnecessary given the wide implementation of Jingle.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2007-11-15</date>
<initials>psa</initials>
<remark><p>Editorial review and consistency check.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2007-05-11</date>
<initials>psa</initials>
<remark><p>Specified use of port 17777 as default.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2007-04-10</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2007-03-23</date>
<initials>psa</initials>
<remark><p>Changed echo namespace to be a content description format only; defined basic direct-tcp transport for bootstrapping purposes only.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2007-02-27</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0166; defines a framework for using XMPP to negotiate and manage out-of-band media sessions. Unfortunately, most developers of XMPP clients have limited experience with multimedia applications such as voice and video, making it difficult to get started with implementation of Jingle technologies. Therefore this document provides a simple application format that client developers can use to bootstrap Jingle implementations.</p>
<p><em>Note: The methods specified herein are provided for experimentation and unit testing only. They are not intended for inclusion in released software or production environments.</em></p>
</section1>
<section1 topic='Resource Determination' anchor='session-resource'>
<p>In order to initiate a Jingle session, the initiator must determine which of the responder's XMPP resources is best for the desired application format. The following approach may be helpful to implementors:</p>
<ol>
<li><p>If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, the initiator SHOULD attempt to negotiate a Jingle session with that resource unless the initiator knows via &xep0030; or &xep0115; that the resource does not support Jingle and the desired application format. <note>Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use <cite>Entity Capabilities</cite>, whereby support for Jingle and various Jingle application formats and transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to <cite>XEP-0115</cite> for details.</note></p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but only one of the resources supports Jingle and the desired application format, the initiator SHOULD initiate the Jingle session with that resource.</p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired application format, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p></li>
<li><p>If the intended responder does not share presence with the initiator, the initiator SHOULD first send a &xep0155; request to the responder in order to initiate the exchange of XMPP stanzas. The request SHOULD include a RAP routing hint as specified in <cite>XEP-0168</cite> and the &MESSAGE; stanza containing the request SHOULD be of type "headline" so that (typically) it is not stored offline for later delivery. The stanza session negotiation SHOULD result in temporary sharing of presence between the parties via the "presence" field as described in <cite>XEP-0155</cite>.</p></li>
</ol>
</section1>
<section1 topic='Protocol Flow' anchor='protocol'>
<p>The intent of this simple Jingle profile is to enable exchange of data using the Echo Protocol specified in &rfc0862;, but using a port other than 7 (the default port for this experimental usage is 17777). The protocol flow is as follows. (The following examples use &xep0177; as the transport protocol; although it is possible to complete echo protocol exchanges via TCP, that is deemed less useful and there is no Jingle transport method for direct TCP exchanges.)</p>
<example caption='Initiation'><![CDATA[
<iq from='[email protected]/orchard'
id='jingle1'
to='[email protected]/balcony'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate'
initiator='[email protected]/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='echo-this'>
<description xmlns='http://www.xmpp.org/extensions/xep-0208.html#ns'/>
<transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
<candidate ip='10.1.1.104' port='17777' generation='0'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>If none of the errors specified in <cite>XEP-0166</cite> occurs, the responder acknowledges the session initiation request.</p>
<example caption='Responder acknowledges session-initiate'><![CDATA[
<iq from='[email protected]/balcony'
id='jingle1'
to='[email protected]/orchard'
type='result'/>
]]></example>
<p>If no negotiation is required (e.g., to modify the port number or transport method), the responder simply accepts the session. (Alternatively, if the responder wants to use a port other 17777, it SHOULD negotiate the port using a Jingle content-modify action; see <cite>XEP-0166</cite> for details and examples.)</p>
<example caption='Responder definitively accepts the session'><![CDATA[
<iq from='[email protected]/balcony'
id='jingle2'
to='[email protected]/orchard'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-accept'
initiator='[email protected]/orchard'
sid='a73sjjvkla37jfea'/>
</iq>
]]></example>
<example caption='Initiating entity acknowledges definitive acceptance'><![CDATA[
<iq from='[email protected]/orchard'
id='accept1'
to='[email protected]/balcony'
type='result'/>
]]></example>
<p>The parties may now exchange data using the echo protocol in order to test the connection.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>As noted, the methods specified herein are provided for experimental use only and are not intended for inclusion in released software or production environments.</p>
<p>On some operating systems, access to the root or administrative user may be necessary in order to use the echo protocol over TCP or UDP port 7; therefore it is RECOMMENDED to use port 17777 instead.</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='ns'>
<p>Because this specification defines an experimental protocol that is to be used only for bootstrapping purposes, the ®ISTRAR; shall not issue a permanent namespace upon approval of this specification. Therefore, its associated namespace shall always be "http://www.xmpp.org/extensions/xep-0208.html#ns".</p>
</section2>
<section2 topic='Jingle Content Description Formats' anchor='registrar-content'>
<p>The XMPP Registrar shall include "echo" in its registry of Jingle content description formats. The registry submission is as follows:</p>
<code><![CDATA[
<content>
<name>echo</name>
<desc>A bootstrapping method for exchanging echo protocol data (see RFC 862).</desc>
<doc>XEP-0208</doc>
</content>
]]></code>
</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://www.xmpp.org/extensions/xep-0208.html#ns'
xmlns='http://www.xmpp.org/extensions/xep-0208.html#ns'
elementFormDefault='qualified'>
<xs:element name='description' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</xep>