<abstract>This specification defines an extension to the Rayo protocol (XEP-0327) to provide provision for sending and receiving faxcimilies via a call under the control of a Rayo client.</abstract>
<p>Rayo allows for the third-party control of media sessions such as telephone calls. A common requirement in telephony applications providing backward compatability with legacy systems is to support sending and receiving faxes. This specification extends the core Rayo specification, to describe a protocol for this use case.</p>
</section1>
<section1topic='Session Flow'anchor='session'>
<p>This section describes the form, function and order of Rayo stanzas sent across the wire, and the circumstances in which they apply and/or may arise.</p>
<p>A Rayo client may utilise <linkurl=''>Rayo CPA</link> to establish a fax CNG tone before initiating fax receipt using the receivefax component described below.</p>
<p>The receivefax component accepts a fax from a caller, stores it, and makes it available to Rayo clients. The component is created using a <linkurl='#def-receivefax'><receivefax/> command</link>.</p>
<p>The receivefax completion reason MUST be one of the <linkurl='#def-components-complete-reason'>core Rayo reasons</link> or <linkurl='#def-finish'>finish</link> (indicating that the document was fully received). Receivefax component completion provides a fax element only when a document was successfully received.</p>
<p>The server MUST present the fax for consumption by the client by way of fax meta-data on the complete reason, including a URI at which the document may be fetched. It MUST provide url, resolution, file size & page count data as specified on the <linkurl='#def-fax'>fax element</link>. In cases of partial receipt of a fax, a fax element MAY be returned in addition to the error completion reason.</p>
<examplecaption="Component indicates it has completed due to being finished, providing the fax"><![CDATA[
<p>Sending faxes can be achieved by using the Sendfax component. A conformant server MUST support image/tiff documents, and MAY also support others. A conformant server MUST support fetching documents via an HTTP URL and MAY support other URL schemes.</p>
<examplecaption='Client sends a fax document to a call'><![CDATA[
<p>Additionally, a sendfax component MAY include in its completion reason one or more <linkurl='#def-metadata'><metadata/> elements</link> describing the result of transmitting the document, like so:</p>
<examplecaption='Client finishes sending a fax document to a call'><![CDATA[
<p>Provides data for a document to be sent as a fax.</p>
<p>The <document/> element MUST be empty.</p>
<p>The attributes of the <document/> element are as follows.</p>
<tablecaption='Attributes of Document Element'>
<tr>
<th>Attribute</th>
<th>Definition</th>
<th>Possible Values</th>
<th>Inclusion</th>
</tr>
<tr>
<td>url</td>
<td>Indicates the URL at which the document to send is available.</td>
<td>A valid URI.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>identity</td>
<td>Indicates the identity from which the fax should appear to be sent.</td>
<td>A phone number string in E.164 format.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>header</td>
<td>The header line to add to each page of the transmitted fax.</td>
<td>A string.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>pages</td>
<td>The (set of) range of pages of the document to transmit.</td>
<td>A string (or set of strings separated by ',') in the format M[-N], where M and N are integers and the dash and second integer are optional. The set is combinatory and dash-separated integers signify a range of pages. The index is one-based.</td>
<p>If a Rayo server supports Rayo Fax, it MUST advertise that fact by returning a feature of "urn:xmpp:rayo:fax:1" &VNOTE; in response to a &xep0030; information request.</p>
<examplecaption="Service Discovery Information Request - Client to Server"><![CDATA[
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
<p>A server MUST document any cases where its behaviour differs from that in this specification (such as lack of support for particular options/components/etc) and return an error whenever a command is not understood. A server MUST NOT silently ignore any instructions.</p>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
A string (or set of strings separated by ',') in the format M[-N], where M and N are integers and the dash and second integer are optional. The set is combinatory and dash-separated integers signify a range of pages. The index is one-based.
