MUST be set to "utf-8".
5.1.1. From Address
The ’from’ attribute of an XMPP presence stanza maps to the ’From’
header of a "Message/CPIM" object. In XMPP, the sender’s server
stamps or validates the "from" address and sets its value to the
<user@host/resource> negotiated between client and server during
authenticating and resource binding as defined in [XMPP-CORE]. Thus
an XMPP-CPIM gateway will receive from the sender’s XMPP server a
presence stanza containing a "from" address of the form
<user@host/resource>. To map the ’from’ attribute of an XMPP
presence stanza to the ’From’ header of a "Message/CPIM" object, the
gateway MUST remove the resource identifier, MUST append the "im:"
Instant Messaging URI scheme to the front of the address, and MAY
include a CPIM "Formal-name" for the sender (if known).
Example: From Address Mapping
XMPP ’from’ attribute
<presence from=’juliet@example.com/balcony’>
...
</presence>
CPIM ’From’ header
From: Juliet Capulet <im:juliet@example.com>
In addition, the ’from’ attribute of an XMPP presence stanza maps to
the ’entity’ attribute of a PIDF <presence/> root element. To map
the XMPP ’from’ attribute to the PIDF ’entity’ attribute, the gateway
MUST remove the resource identifier and MUST append the "pres:"
Instant Messaging URI scheme to the front of the address.
Example: From Address Mapping (PIDF)
XMPP ’from’ attribute
<presence from=’juliet@example.com/balcony’>
...
</presence>
PIDF ’entity’ attribute
<presence entity=’pres:juliet@example.com’>
...
</presence>
Finally, an XMPP-CPIM gateway SHOULD map the resource identifier of
the XMPP address contained in the XMPP ’from’ attribute to the ’id’
attribute of the PIDF <tuple/> child element.
Example: Resource Identifier Mapping
XMPP ’from’ attribute
<presence from=’juliet@example.com/balcony’>
...
</presence>
PIDF ’id’ for <tuple/>
<presence entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
...
</tuple>
</presence>
5.1.2. To Address
The ’to’ attribute of an XMPP presence stanza maps to the ’To’ header
of a "Message/CPIM" object. In XMPP, the sender MAY include a ’to’
attribute on a presence stanza, and MUST include it if the presence
stanza is intended for delivery directly to another user (presence
stanzas intended for broadcasting are stamped with a ’to’ address by
the sender’s server). Thus an XMPP-CPIM gateway will receive from
the sender’s XMPP server a presence stanza containing a "to" address
of the form <user@host> or <user@host/resource>. To map the ’to’
attribute of an XMPP presence stanza to the ’To’ header of a
"Message/CPIM" object, the gateway MUST remove the resource
identifier (if included), MUST append the "im:" Instant Messaging URI
scheme to the front of the address, and MAY include a CPIM
"Formal-name" for the recipient (if known).
Example: To Address Mapping
XMPP ’to’ attribute
<presence to=’romeo@example.net/orchard’>
...
</presence>
CPIM ’To’ header
To: Romeo Montague <im:romeo@example.net>
5.1.3. Stanza ID
An XMPP presence stanza MAY possess an ’id’ attribute, which is used
by the sending application for the purpose of tracking stanzas and is
not a globally-unique identifier such as is defined by the MIME
Content-ID header. Because the XMPP ’id’ attribute does not have the
same meaning as the MIME Content-ID header, it SHOULD NOT be mapped
to that header; however, if the ’id’ is known to be unique (e.g., if
it is generated to be unique by the XMPP server and that fact is
known by the XMPP-CPIM gateway), then it SHOULD be so mapped.
5.1.4. Presence Type
An XMPP presence stanza MAY possess a ’type’ attribute. If no ’type’
attribute is included, the presence stanza indicates that the sender
is available; this state maps to the PIDF basic presence type of
OPEN. If the ’type’ attribute has a value of "unavailable", the
presence stanza indicates that the sender is no longer available;
this state maps to the PIDF basic presence type of CLOSED. Thus both
the absence of a ’type’ attribute and a ’type’ attribute set to a
value of "unavailable" correspond to the [CPP] "notify operation".
All other presence types are used to manage presence subscriptions or
probe for current presence; mappings for these other presence types
are defined under XMPP-CPIM Gateway as Presence Service (Section 6).
Example: Available Presence
XMPP available presence
<presence from=’juliet@example.com/balcony’/>
PIDF basic presence (OPEN)
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
<status>
<basic>open</basic>
</status>
</tuple>
</presence>
Example: Unavailable Presence
XMPP unavailable presence
<presence from=’juliet@example.com/balcony’ type=’unavailable’/>
PIDF basic presence (CLOSED)
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:romeo@example.net’>
<tuple id=’balcony’>
<status>
<basic>closed</basic>
</status>
</tuple>
</presence>
5.1.5. Show Element
The <show/> child element of an XMPP presence stanza provides
additional information about the sender’s availability. The XML
character data of the XMPP <show/> element maps to extended <status/>
content in PIDF. The defined values of the <show/> element are
’away’, ’chat’, ’dnd’, and ’xa’; as soon as values are specified for
extended status states in the ’urn:ietf:params:xml:ns:pidf:im’
namespace, the XMPP values will be mapped to the PIDF values.
Example: Show Element
XMPP <show/> element
<presence from=’juliet@example.com/balcony’>
<show>away</show>
</presence>
PIDF extended presence information
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
xmlns:im=’urn:ietf:params:xml:ns:pidf:im’
entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
<status>
<basic>open</basic>
<im:im>away</im:im>
</status>
</tuple>
</presence>
5.1.6. Status Element
The <status/> child element of an XMPP presence stanza provides a
user-defined, natural-language description of the sender’s detailed
availability state. The XMPP <status/> element maps to the PIDF
<note/> child of the PIDF <tuple/> element.
Example: Status Element
XMPP <status/> element
<presence from=’juliet@example.com/balcony’>
<show>away</show>
<status>retired to the chamber</status>
</presence>
PIDF <note/> element
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
xmlns:im=’urn:ietf:params:xml:ns:pidf:im’
entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
<status>
<basic>open</basic>
<im:im>away</im:im>
</status>
<note>retired to the chamber</note>
</tuple>
</presence>
5.1.7. Presence Priority
An XMPP presence stanza MAY contain a <priority/> child element whose
value is an integer between -128 and +127. The value of this element
MAY be mapped to the ’priority’ attribute of the <contact/> child of
the PIDF <tuple/> element. If the value of the XMPP <priority/>
element is negative, an XMPP-CPIM gateway MUST NOT map the value. The
range of allowable values for the PIDF ’priority’ attribute is any
decimal number from zero to one inclusive, with a maximum of three
decimal places. If an XMPP-CPIM gateway maps these values, it SHOULD
treat XMPP <priority>0</priority> as PIDF priority=’0’ and XMPP
<priority>127</priority> as PIDF priority=’1’, mapping intermediate
values appropriately so that they are unique (e.g., XMPP priority 1
to PIDF priority 0.007, XMPP priority 2 to PIDF priority 0.015, and
so on up through mapping XMPP priority 126 to PIDF priority 0.992;
note that this is an example only, and that the exact mapping shall
be determined by the XMPP-CPIM gateway).
Example: Presence Priority
XMPP <status/> element
<presence from=’juliet@example.com/balcony’>
<priority>13</priority>
</presence>
PIDF <note/> element
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
...
<contact priority=’0.102’>im:juliet@example.com</contact>
</tuple>
</presence>
5.1.8. Presence Extensions
As defined in [XMPP-CORE], an XMPP presence stanza may contain
"extended" content in any namespace in order to supplement or extend
the semantics of the core presence stanza. With the exception of
extended information qualified by the
’urn:ietf:params:xml:ns:xmpp-e2e’ namespace as defined in [XMPP-E2E],
an XMPP-CPIM gateway SHOULD ignore such information and not pass it
through the gateway to the intended recipient. No mapping for such
information is defined.
5.1.9. Gateway-Generated CPIM and PIDF Syntax
5.1.9.1. CPIM Message Headers
CPIM specifies the existence of "Message/CPIM" headers in addition to
those described above, but there is no exact analogue for those
headers in the core XMPP specifications. These include:
o cc -- specifies the address of an entity that is to receive a
"courtesy copy" of the presence information (i.e., a non-primary
addressee)
o DateTime -- specifies the datetime at which the presence
information was sent
o NS -- specifies the namespace of a feature extension
o Subject -- specifies the subject or topic of the encapsulated
"Message/CPIM" object
o Require -- specifies mandatory-to-recognize features
An XMPP-CPIM gateway MAY independently generate such headers based on
its own information (e.g., the datetime at which it received a
presence stanza from an XMPP entity) or based on data encoded in
non-core XMPP extensions, but rules for doing so are out of scope for
this memo.
5.1.9.2. PIDF Elements
PIDF specifies the existence of XML elements in addition to those
described above, but there is no exact analogue for those XML
elements in the core XMPP specifications. These include:
o <contact/> -- specifies an address (e.g., an im:, tel:, or mailto:
URI) at which one may communicate with the presentity; an
XMPP-CPIM gateway MAY include this element, in which case it
SHOULD set its value to the <user@host> of the XMPP sender,
prepended by the "im:" Instant Messaging URI scheme.
o <timestamp/> -- specifies the datetime at which the presence
information was sent; an XMPP-CPIM gateway MAY independently
generate this element based on its own information (e.g., the
datetime at which it received the presence stanza from an XMPP
entity) or based on data encoded in non-core XMPP extensions, but
rules for doing so are out of scope for this memo.
5.2. Presence Syntax Mapping from CPIM Specifications to XMPP
This section defines the mapping of syntax primitives from
"Message/CPIM" objects with encapsulated "application/pidf+xml"
objects to XMPP presence stanzas.
Note: An XMPP-CPIM gateway MUST NOT map to an XMPP presence stanza a
"Message/CPIM" object whose encapsulated MIME object has a
Content-type other than "application/pidf+xml" (with the exception of
multi-part MIME objects as specified in [XMPP-E2E]).
5.2.1. From Address
The ’From’ header of a "Message/CPIM" object maps to the <user@host>
portion of the ’from’ attribute of an XMPP presence stanza, and the
’id’ attribute of the PIDF <tuple/> child element maps to the
resource identifier portion XMPP ’from’ attribute. Therefore, to map
the CPIM and PIDF information to the XMPP ’from’ attribute, the
gateway MUST remove the "im:" Instant Messaging URI scheme from the
front of the address and MUST remove the CPIM "Formal-name" (if
provided) in order to generate the <user@host> portion of the XMPP
’from’ attribute, then add a ’/’ character followed by the value of
the PIDF <tuple/> element’s ’id’ attribute.
Example: From Address Mapping
CPIM ’From’ header
From: Romeo Montague <im:romeo@example.net>
XMPP ’from’ attribute
<presence from=’romeo@example.net’>
...
</presence>
Example: Resource Identifier Mapping
XMPP ’from’ attribute
<presence from=’juliet@example.com/balcony’>
...
</presence>
PIDF ’id’ for <tuple/>
<presence entity=’pres:juliet@example.com’>
<tuple id=’balcony’>
...
</tuple>
</presence>
5.2.2. To Address
The ’To’ header of a "Message/CPIM" object maps to the ’to’ attribute
of an XMPP presence stanza. To map the CPIM ’To’ header to the XMPP
’to’ attribute, the gateway MUST remove the "im:" Instant Messaging
URI scheme from the front of the address and MUST remove the CPIM
"Formal-name" (if provided). If the gateway possesses knowledge of
the resource identifier in use by the XMPP entity, the gateway MAY
append the resource identifier to the address.
Example: To Address Mapping
CPIM ’To’ header
To: Juliet Capulet <im:juliet@example.com>
XMPP ’to’ attribute
<presence to=’juliet@example.com/balcony’>
...
</presence>
5.2.3. Courtesy Copy
The core XMPP specification does not include syntax for specifying a
"courtesy copy" (non-primary addressee) for a presence stanza.
Therefore, if an XMPP-CPIM gateway receives a "Message/CPIM" object
with encapsulated PIDF object that contains a ’cc’ header, it SHOULD
NOT pass the information contained in that header on to the XMPP
recipient.
5.2.4. DateTime Header
The core XMPP specification does not include syntax for specifying
the datetime at which a presence stanza was sent. Therefore, if an
XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated
PIDF object that contains a ’DateTime’ header, it SHOULD NOT pass the
information contained in that header on to the XMPP recipient.
5.2.5. Subject Header
An XMPP presence stanza contains no information that can be mapped to
the ’Subject’ header of a "Message/CPIM" object. Therefore, if an
XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated
PIDF object that contains a ’Subject’ header, it SHOULD NOT pass the
information contained in that header on to the XMPP recipient.
5.2.6. Header Extensions
"Message/CPIM" objects MAY include an optional ’NS’ header to specify
the namespace of a feature extension. An XMPP-CPIM gateway MUST NOT
pass such headers through to the XMPP recipient, and no mapping for
such headers is defined.
5.2.7. Require Header
"Message/CPIM" objects MAY include an optional ’Require’ header to
specify mandatory-to-recognize features. An XMPP-CPIM gateway MUST
NOT pass such headers through to the XMPP recipient, and no mapping
for such headers is defined.
5.2.8. MIME Content-ID
XMPP does not include an element or attribute that captures a
globally unique ID as is defined for the Content-ID MIME header as
specified in [MIME]. If an XMPP-CPIM gateway receives a MIME object
that includes a Content-ID, it MAY provide the Content-ID as the
value of the presence stanza’s ’id’ attribute, but this is OPTIONAL.
Example: Content-ID for Encapsulated Object
MIME header
Content-ID: <123456789@example.net>
XMPP ’id’ attribute (OPTIONAL)
<presence id=’123456789@example.net’>
...
</presence>
5.2.9. Basic Presence Status
The basic presence status types defined in PIDF are OPEN and CLOSED.
The PIDF basic presence status of OPEN maps to an XMPP presence
stanza that possesses no ’type’ attribute (indicating default
availability). The PIDF basic presence status of CLOSED maps to an
XMPP presence stanza that possesses a ’type’ attribute with a value
of "unavailable".
Example: OPEN Presence
PIDF basic presence (OPEN)
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:romeo@example.net’>
<tuple id=’orchard’>
<status>
<basic>open</basic>
</status>
</tuple>
</presence>
XMPP available presence
<presence from=’romeo@example.net/orchard’/>
Example: CLOSED Presence
PIDF basic presence (CLOSED)
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:romeo@example.net’>
<tuple id=’orchard’>
<status>
<basic>closed</basic>
</status>
</tuple>
</presence>
XMPP unavailable presence
<presence from=’romeo@example.net/orchard’
type=’unavailable’/>
5.2.10. Extended Status Information
PIDF documents may contain extended <status/> content. As of this
writing there are no pre-defined extended status states that can be
mapped to the defined values of the XMPP <show/> element (’away’,
’chat’, ’dnd’, and ’xa’). Once PIDF extensions for such extended
status states are defined within the Internet Standards Process, a
gateway SHOULD map those extensions; however, any such mapping is out
of scope for this memo, since the relevant PIDF extensions have not
yet been defined.
Example: Extended Status Information (provisional)
PIDF extended presence information
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
xmlns:im=’urn:ietf:params:xml:ns:pidf:im’
entity=’pres:romeo@example.net’>
<tuple id=’orchard’>
<status>
<basic>open</basic>
<im:im>busy</im:im>
</status>
</tuple>
</presence>
XMPP <show/> element
<presence from=’romeo@example.net/orchard’>
<show>dnd</show>
</presence>
5.2.11. Note Element
A PIDF <tuple/> element may contain a <note/> child that provides a
user-defined, natural-language description of the sender’s detailed
availability state. The PIDF <note/> element maps to the XMPP
<status/> element.
Example: Note Element
PIDF <note/> element
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
xmlns:im=’urn:ietf:params:xml:ns:pidf:im’
entity=’pres:romeo@example.net’>
<tuple id=’orchard’>
<status>
<basic>open</basic>
<im:im>busy</im:im>
</status>
<note>Wooing Juliet</note>
</tuple>
</presence>
XMPP <status/> element
<presence from=’romeo@example.net/orchard’>
<show>dnd</show>
<status>Wooing Juliet</status>
</presence>
A PIDF document with zero tuples MAY contain one or more <note/>
elements as direct children of the PIDF <presence/> element. There
is no mapping of such a PIDF document to an XMPP presence stanza; an
entity on the non-XMPP side of an XMPP-CPIM gateway SHOULD NOT send
such a PIDF document to an XMPP recipient if possible, and an
XMPP-CPIM gateway MUST NOT map such a PIDF document to an XMPP
presence stanza (see Zero Resources (Section 6.3.2)).
5.2.12. Contact Element
A PIDF document may contain a <contact/> element specifying the URI
of an address at which the principal can be contacted (e.g., an im:,
tel:, or mailto: URI). The core XMPP specification does not include
syntax for specifying the URI of a contact address, since the contact
address is implicit in the ’from’ attribute of the XMPP presence
stanza. Therefore, if an XMPP-CPIM gateway receives a "Message/CPIM"
object with encapsulated PIDF object that contains a <contact/>
element, it SHOULD NOT pass the XML character data of the <contact/>
element on to the XMPP recipient. (However, see Inclusion of
Complete PIDF Document (Section 5.2.15) below.)
Example: PIDF Contact Element
PIDF <contact/> element
<?xml version=’1.0’ encoding=’UTF-8’?>
<presence xmlns=’urn:ietf:params:xml:ns:pidf’
entity=’pres:romeo@example.net’>
<tuple id=’orchard’>
...
<contact>im:romeo@example.net</contact>
</tuple>
</presence>
XMPP presence stanza
<presence from=’romeo@example.net/orchard’/>
5.2.13. Presence Priority
The <contact/> child of the PIDF <tuple/> element MAY possess a
’priority’ attribute whose value is a decimal number between zero and
one (with a maximum of three decimal places). The value of this
attribute MAY be mapped to the <priority/> child element of an XMPP
presence stanza. An XMPP-CPIM gateway MUST NOT map PIDF priority
values to negative values of the XMPP <priority/> element. If an
XMPP-CPIM gateway maps these values, it SHOULD treat PIDF
priority=’0’ as XMPP <priority>0</priority> and PIDF priority=’1’ as
<priority>127</priority>, mapping intermediate values appropriately
so that they are unique (e.g., PIDF priorities between 0.001 and
0.007 to XMPP priority 1, PIDF priorities between 0.008 and 0.015 to
XMPP priority 2, and so on up through mapping PIDF priorities between
0.992 and 0.999 to XMPP priority 126; note that this is an example
only, and that the exact mapping shall be determined by the XMPP-CPIM
gateway).
5.2.14. Timestamp Element
The core XMPP specification does not include syntax for specifying
the datetime or timestamp at which a presence stanza was sent.
Therefore, if an XMPP-CPIM gateway receives a "Message/CPIM" object
with encapsulated PIDF object that contains a <timestamp/> element,
it SHOULD NOT pass the XML character data of the <timestamp/> element
on to the XMPP recipient.
5.2.15. Inclusion of Complete PIDF Document
Certain PIDF elements do not map to XMPP presence stanza syntax
(e.g., the XML character data of the <contact/> element). However,
an XMPP client may be able to handle such information by parsing a
native PIDF document. To make this possible, an XMPP-CPIM gateway
MAY include the complete PIDF document as a child element of the
presence stanza, as described in [XMPP-PIDF]. If an XMPP client does
not understand this extended data, it naturally MUST ignore it.
6. XMPP-CPIM Gateway as Presence Service
[CPP] defines semantics for an abstract presence service. An
XMPP-CPIM gateway MAY function as such a presence service, and if so
an XMPP entity can use defined XMPP syntax to interact with the
gateway’s presence service. Because [PIDF] does not specify syntax
for semantic operations such as subscribe, this section defines only
the XMPP interactions with the presence service offered by an
XMPP-CPIM gateway, not the translation of such XMPP syntax into PIDF.
(Note: Detailed information about XMPP presence services can be found
in [XMPP-IM]; as much as possible, an XMPP-CPIM gateway SHOULD
implement the syntax, semantics, and server business rules defined
therein.)