2.2.1 text/xml+msrtc.pidf Presence Document Format

  • Article

These extensions support a nonstandard Presence Document Format that has a number of enhancements, such as the capability to carry device capabilities and the capability to support multiple devices for a single user. A user can log on by using multiple devices. Each device presents its presence information to the server. The XML instance containing presence information submitted to the server is called the Presence Document. When retrieving presence information for a user, the server not only returns the Presence Document from every device, but it also determines the overall presence of the user. This XML instance returned by the server is called the Aggregated Presence Document.

Some of the key elements and attributes are defined as follows:

  • presentity

    The element contains the overall aggregated availability and activity of a user, as well as the availability and activity of all endpoints of the user. The uri attribute specifies the sip entity that this element is describing.

  • epid

    This attribute can appear in the availability element, the activity element, or a devicePresence element. When used in the availability and activity elements inside the presentity element, the epid identifies the availability and activity for the most active endpoint. When used in the devicePresence element, the epid advertises the availability and identifies the activity for a specific endpoint. This value is a hexadecimal string no longer than 16 bytes in length. This epid value is the same endpoint identifier value used to identify a specific SIP endpoint.

  • ageOfPresence

    The ageOfPresence attribute appears in a devicePresence element. This is the number of seconds since the device last updated its presence information.

  • availability

    Availability indicates whether the user can receive a call. The availability element has an aggregate attribute that represents the availability of a user on a device. The aggregate attribute is processed by the server as being within a range that has a span of 100 (the class code). Note that within the XML sent by the client, the client does not specify the class code, but rather, the actual value. The server interprets the values as being within the following classes.

    Class code

    Server interpretation

    000-099

    The user cannot receive calls.

    100-199

    The user can be online; however, availability is unknown until a call is attempted. A cell phone gateway typically uses this setting.

    200-299

    The user has a device that is currently connected and it can receive calls.

    300-399

    The user is in proximity of a device that can receive calls.

    Rather than a hard-coded enumeration, a numeric value is used. This makes it easy to compare the availability that is sent by two different user agents. For example, the higher the availability, the more available the user.

  • activity

    The purpose of activity is not to indicate if a user can receive a call, but rather, to indicate to watchers how likely the user is to want to be disturbed. The activity element has an attribute aggregate that contains a numeric value that defines the activity of the user.

    Activity code

    Server interpretation

    000-099

    There is no information about the activity of the user.

    100-149

    The user is away.

    150-199

    The user is out to lunch.

    200-299

    The user is idle.

    300-399

    The user will be right back.

    400-499

    The user is active.

    500-599

    The user is already participating in a communications session.

    600-699

    The user is busy.

    700-799

    The user is away.

    800-999

    The user is active.

    Rather than a hard-coded enumeration, a numeric value is used. This makes it easy to compare the availability sent by two different user agents.

  • note

    This attribute in the activity element can be used by the client to store a string that indicates the user's status on the device.

  • userInfo

    This element is used for storing persisted presence information for a user. This information is stored by the server and is available regardless of the device to which a user is logged on or even whether the user is logged on at all. Any valid XML can be stored on the server. The server enforces a limit of 1,024 characters on the size of the element body, where the entire element body is treated as a single string.

The Presence Document is described by the XML schema in Appendix A: Full text/xml+msrtc.pidf Presence Document Format (section 6).

Note that the schema defines two different versions of the Presence Document:

  • A version that is published by the client using a setPresence request.

  • A version that is generated by the server and sent in a NOTIFY or BENOTIFY request to the watcher containing the aggregation of the various presence information published by the 1+ devices of the user.

The aggregated Presence Document describes a user's availability on all its devices as well as an overall aggregated presence. This is the document published by the server to anyone obtaining the presence of a particular user. The availability and activity elements in the aggregated Presence Document indicate the availability and activity information from the most available device of the user. The server MAY also include the displayName, email, and phoneNumber of the user in the aggregated Presence Document.