A SIP application can issue a SUBSCRIBE request for notification
of a future change or changes to a document. The XCAP XML document
header information for the SUBSCRIBE request is checked by the XCAP
server to determine whether the request should be honored or rejected.
The following is a sample SUBSCRIBE request code snippet showing
the format of SUBSCRIBE request. The event header consists of specific
tags, separated by a semi-colon, which provide detailed information
for the SUBSCRIBE request.
Accept header
The accept header parameter
must be application/xcap-diff+xml if you if you
want to receive a xcap-diff document with your notifies. This is the
case with both UA-profile and xcap-diff events.
UA-profile event header
When
IBM® XDMS receives
a subscribe request it scans the document header for the required
UA-profile or
xcap-diff event.
If the Event header format is incorrect, a
489 Bad Event response
will be returned
- ua-profile tag
- The event for a UA-profile event subscription.
- profile-type tag
- The profile-type tag is mandatory and must be set to application as
defined by the SIP UA-profile specification.
- vendor tag
- The vendor tag is mandatory. IBM XDMS ensures
that the tag exists, but it can be set to any value.
- model tag
- The model tag is mandatory. IBM XDMS ensures
that the tag exists, but it can be set to any value.
- version tag
- The version tag is mandatory. IBM XDMS ensures
that the tag exists, but it can be set to any value.
- auid tag
- The auid tag specifies the AUID of the target document. It is
not required if you specify the AUID in the document tag
- document tag
- The value of the document tag is used to identify the document
that is being subscribed to.
- If the auid tag and document tag
do not exist the request URI in the TO header of the SUBSCRIBE request
is used. This URI should represent a service URI in a rls-services
document. The rls-services definition is retrieved and the associated
resource-lists XCAP URI is used for the subscription.
- If the service URI does not exist in an rls-services document,
or if the document represented by the XCAP URI associated with that
service URI does not exist in IBM XDMS,
a 404 Not Found response will be returned.
- If the auid tag is rls-services and the document tag
is “global/index”, then the rls-services is again used to retrieve
the associated resource-lists XCAP URI used for the subscription.
However, the Request-URI is used to match the service URI instead
of the TO header.
- If the auid tag is specified but the document
header is not specified, then a user home directory for that AUID
is being subscribed to. The XUI for the user's home directory is specified
in the Request-URI.
- The document URI may be in the form of:
- AUID/users/XUI/document
- AUID/global/document
- users/XUI/document
- global/document
In order to process the document URI, IBM XDMS checks
to see if the document URI starts with either global or users.
If it does, IBM XDMS requires
an AUID, which must be specified using the auid tag
Sample ua-profile event header
Event: ua-profile;profile-type="application";vendor="ibm";model="xdms";version="7.0";
auid="resource-lists";document="users/sip:joe@us.example.com/mydocument.xml"
xcap-diff event header
- xcap-diff tag
- This event is for xcap-diff SIP subscribe event which allows for
node level subscriptions.
- diff-processing tag
- The diff-processing parameter has three options:
- xcap-patching
- Provides xcap diff patch operations, this is default value assigned
if the diff-processing parameter is not included
in the subscribe request.
- no-patching
- Patch operations are not provided.
- aggregate
- This value will perform the same as xcap-patching in this 7.0 release
of XDMS
Sample xcap-diff event header
Event: xcap-diff;diff-processing=xcap-patching
Expires header
The
Expires header
is an optional value for
IBM XDMS.
The value of this header field specifies the time in seconds that
the subscription request is valid.
- If the Expires header does not exist, the value
from the subscribeExpiresDefault configuration parameter
is used.
- If the Expires value is zero the subscription
is cancelled. Even if a subscription does not exist in IBM XDMS,
a 200 OK response will be returned to the requester.
This will trigger a NOTIFY with a Subscription-State of terminated.
- If the Expires value is non-zero, the value will
be checked against the Min-Expires and Max-Expires values.
The
actual expiration time values are set using a minute boundary, which
means the time value after being read into the system is then reduced
to the next lower minute value. For example, if the Expires time
value was 80 seconds the next lower minute value of 60 seconds will
be used. If the time value was 170 seconds the next lower minute value
would be 120 seconds.
- If the Expires value is less than zero, the value
is considered malformed and is set to the default value.
- If the Expires value is greater than zero, but
less than the minimum time defined in the configuration property subscribeExpireMin,
a 423 Interval Too Brief response will be returned.
- If the Expires value is greater than the configured
maximum value as defined in the configuration property subscibeExpireMax it
is set to the maximum value defined in the property subscibeExpireMax.