SIPPING Working Group G. Camarillo
Internet-Draft Ericsson
Expires: August 6, 2004 M. Garcia-Martin
Nokia
February 6, 2004
A Transaction Event Package for the Session Initiation Protocol (SIP)
draft-camarillo-sipping-transac-package-00.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 6, 2004.
Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract
SIP provides a SIP Events notification framework that is extensible
throught the addition of event packages. This document defines a
transaction event package for the SIP Events notification, along with
a data format used in notifications for this package. The transaction
package allows users to subscribe to a resource in an application
server and receive notifications about the changes in state of
transactions the application server initiates as part of a service.
Additionally, we define a new SIP Associated-Transactions-State
header field that allows a server to return a subscrible URI that
provides transactions notification information.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 1]
Internet-Draft SIP Transaction Event Package February 2004
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 3
4. The Transaction Event Package . . . . . . . . . . . . . . . 4
4.1 Event Package Name . . . . . . . . . . . . . . . . . . . . . 4
4.2 Event Package Parameters . . . . . . . . . . . . . . . . . . 4
4.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . . 4
4.4 Subscription Duration . . . . . . . . . . . . . . . . . . . 4
4.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . . 4
4.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . . . 4
4.7 Notifier Generation of NOTIFY Requests . . . . . . . . . . . 5
4.8 Subscriber Processing of NOTIFY Requests . . . . . . . . . . 5
4.9 Handling of Forked Requests . . . . . . . . . . . . . . . . 5
4.10 Rate of Notifications . . . . . . . . . . . . . . . . . . . 5
4.11 State Agents . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Transaction Information Format . . . . . . . . . . . . . . . 5
5.1 Structure of the Transaction Information . . . . . . . . . . 6
5.1.1 Transaction Element . . . . . . . . . . . . . . . . . . . . 6
5.2 Constructing Coherent State . . . . . . . . . . . . . . . . 7
5.3 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. The Associated-Transactions-State Header Field . . . . . . . 10
6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . 11
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . 11
8.1 MIME Registration for application/transaction-info+xml . . . 11
8.2 URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:transaction-info . . . . . . . . . . 12
8.3 Schema Registration . . . . . . . . . . . . . . . . . . . . 12
8.4 Associated-Transactions-State Header Field Registration . . 13
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13
Normative References . . . . . . . . . . . . . . . . . . . . 13
Informational References . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 14
Intellectual Property and Copyright Statements . . . . . . . 15
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 2]
Internet-Draft SIP Transaction Event Package February 2004
1. Introduction
The SIP [5] Events framework [6] defines general mechanisms for
subscription to, and notification of, events within SIP networks. It
introduces the notion of a package, which is a specific
"instantiation" of the events mechanism for a well-defined set of
events. Here, we define an event package for transactions.
An example of an application using this package is a MESSAGE exploder
(SIP exploders are described in [8]) that sends MESSAGE requests to a
set of destinations on behalf of a user. The user subscribes to the
transaction state of the transactions generated by the application
server as part of the service. The subscriber receives one more
notifications containing the status of those transactions. This way,
the user is informed of which MESSAGE requests were delivered to
their destination and which ones failed.
The transaction state of the transactions generated by the
application server as part of the service is identified by a URI. The
user agent uses this URI to subscribe to this state. The user agent
may use different mechanisms to obtain such a URI. Section 6 defines
one of such mechanisms: the Associated-Transactions-State SIP header
field.
2. Terminology
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as
described in BCP 14, RFC 2119 [1] and indicate requirement levels for
compliant implementations.
3. Definitions
We define the following terms:
Triggering transaction: A SIP transaction that triggers a set of
actions in an application server. These actions usually include
the generation of one or more SIP associated transactions by the
application server.
Triggering request: The SIP request that is part of a triggering
transaction.
Associated transaction: A SIP transaction that is generated by an
application server on reception of a triggering request.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 3]
Internet-Draft SIP Transaction Event Package February 2004
4. The Transaction Event Package
This section provides the details for defining a SIP Events package,
as specified by RFC 3265 [6].
4.1 Event Package Name
The name of this event package is "transaction". This package name is
carried in the Event and Allow-Events header fields, as defined in
[6].
4.2 Event Package Parameters
This package does not define any event package parameters.
4.3 SUBSCRIBE Bodies
This package does not define any SUBSCRIBE bodies.
4.4 Subscription Duration
The default subscription duration for this event package is 60
seconds.
4.5 NOTIFY Bodies
In this event package, the body of the notification contains a
transaction information document. This document describes the state
of one or more transactions associated with the subscribed resource.
All subscribers and notifiers MUST support the "application/
transaction-info+xml" data format described in Section 5. The
subscribe request MAY contain an Accept header field. If no such
header field is present, it has a default value of "application/
transaction-info+xml". If the header field is present, it MUST
include "application/transaction-info+xml", and MAY include any other
types capable of representing transaction state.
The notifications generated by the server MUST be in one of the
formats specified in the Accept header field in the SUBSCRIBE
request.
4.6 Notifier Processing of SUBSCRIBE Requests
The transaction information for a resource contains sensitive
information. So, all subscriptions SHOULD be authenticated.
Authorization policy is at the discretion of the administrator of the
notifier.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 4]
Internet-Draft SIP Transaction Event Package February 2004
4.7 Notifier Generation of NOTIFY Requests
The notifier MUST generate a notification containing the state of all
the transactions associated with the subscribed resource as soon as
any of the following actions take place: a) all the transactions
complete; b) the subscription timer expires.
This behaviour guarantees that the subscriber gets at least one
notification as soon as the transactions are complete or, within
the subscription timer.
The notifier MAY send notifications more often (e.g., once every time
the state of a transaction changes) if there are filters applied to
the subscription.
4.8 Subscriber Processing of NOTIFY Requests
On reception of a valid NOTIFY request, the subscriber SHOULD
immediately render the transaction status to the end-user in an
implementation specific way.
4.9 Handling of Forked Requests
By their nature, the resources supported by this package are
centralized. So, SUBSCRIBE requests should not generally fork. Users
of this package MUST NOT install more than a single subscription as a
result of a single SUBSCRIBE request.
4.10 Rate of Notifications
For reasons of congestion control, it is important that the rate of
notifications not become excessive. As a result, it is RECOMMENDED
that the server not generate notifications for a single subscriber at
a rate faster than once every five seconds.
4.11 State Agents
Transaction state is ideally maintained in the element which
generates the transactions. Consequently, the elements that generate
the transactions are the ones best suited to handle subscriptions to
it. The usage of state agents is NOT RECOMMENDED for this package.
5. Transaction Information Format
Transaction information is an XML document that MUST be well-formed
and SHOULD be valid. Transaction information documents MUST be based
on XML 1.0 and MUST be encoded using UTF-8. This specification makes
use of XML namespaces for identifying Transaction information
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 5]
Internet-Draft SIP Transaction Event Package February 2004
documents. The namespace URI for elements defined by this
specification is a URN [2], using the namespace identifier 'ietf'
defined by RFC 2648 [3] and extended by [7]. This URN is:
urn:ietf:params:xml:ns:transaction-info
A Transaction information document begins with the root element tag
"transaction-info".
5.1 Structure of the Transaction Information
A transaction information document starts with a "transaction-info"
element. This element has three mandatory attributes:
version: allows the recipient of transaction information documents
to properly order them. Versions start at 0, and increment by one
for each new document sent to a subscriber. Versions are scoped
within a subscription. Versions MUST be representable using a 32
bit integer.
state: indicates whether the document contains the "full"
transaction information, or whether it contains only information
on those transactions which have changed since the previous
document ("partial").
entity: contains a URI that identifies the resource whose
transaction information is reported in the remainder of the
document.
The "transaction-info" element has a series of zero or more
"transaction" sub-elements.
5.1.1 Transaction Element
The "transaction" element contains information on a particular
associated transaction. It has two mandatory attributes: "id" and
"r-uri".
id: provides a single string that can be used as an identifier for
this transaction. The "id" is created when the request that
initiates the transaction is sent and it MUST be unique amonst all
the transactions at the subscribed resource.
r-uri: provides the Request-URI of the request that initiated the
associated transaction.
The transaction element has a mandatory sub-element: the "state"
sub-element.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 6]
Internet-Draft SIP Transaction Event Package February 2004
5.1.1.1 State Element
The "state" element indicates the state of the transaction. Its value
is an enumerated type describing one of the following two states:
"pending" or "complete". It has an optional "code" attribute that
contains a provisional response status code (in the pending state) or
a final response code (in the complete state).
The following is an example of a state element:
complete
5.2 Constructing Coherent State
The subscriber to the transaction information maintains a table for
the list of transactions. The table contains a row for each
transaction. Each row is indexed by an ID, present in the "id"
attribute of the "transaction" element. The contents of each row
contain the state of that transaction as conveyed in the document.
The table is also associated with a version number. The version
number MUST be initialized with the value of the "version" attribute
from the "transaction-info" element in the first document received.
Each time a new document is received, the value of the local version
number, and the "version" attribute in the new document, are
compared. If the value in the new document is one higher than the
local version number, the local version number is increased by one,
and the document is processed. If the value in the document is more
than one higher than the local version number, the local version
number is set to the value in the new document, and the document is
processed. If the document did not contain full state, the subscriber
SHOULD generate a refresh request to trigger a full state
notification. If the value in the document is less than the local
version, the document is discarded without processing. The
"transaction-info" element contains an "entity" attribute that
indicate the URI of the subscribed resource.
The processing of the transaction information document depends on
whether it contains full or partial state. If it contains full state,
indicated by the value of the "state" attribute in the
"transaction-info" element, the contents of the table are flushed.
They are repopulated from the document. A new row in the table is
created for each "transaction" element. If the document contains
partial state, as indicated by the value of the "state" attribute in
the "transaction-info" element, the document is used to update the
table. For each "transaction" element in the document, the subscriber
checks to see whether a row exists for that transaction. This check
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 7]
Internet-Draft SIP Transaction Event Package February 2004
is done by comparing the ID in the "id" attribute of the
"transaction" element with the ID associated with the row. If the
transaction does not exist in the table, a row is added, and its
state is set to the information from that "transaction" element. If
the transaction does exist, its state is updated to be the
information from that "transaction" element. If a row is updated or
created, such that its state is now terminated, that entry MAY be
removed from the table at any time.
5.3 Schema
The following is the schema for the application/transaction-info+xml
type:
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 8]
Internet-Draft SIP Transaction Event Package February 2004
5.4 Example
The following is an example of a application/transaction-info+xml
document:
complete
complete
pending
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 9]
Internet-Draft SIP Transaction Event Package February 2004
6. The Associated-Transactions-State Header Field
User agents may need to obtain a URI that identifies a set of
transactions at the application server in order to subscribe to the
state of those transactions. A user agent can use different means to
obtain such a URI. One of them consists of using the
Associated-Transactions-State SIP header field, which we define here.
The Associated-Transactions-State header field can be used when an
application server receives a SIP request that causes the application
server to initiate a set of transactions. We refer to this SIP
request as the triggering request and the set of transactions as the
associated transactions.
For example, an application server provides conferencing services.
When this application server receives an INVITE from a user who is
the first joining a particular conference, the application server
sends a MESSAGE to the rest of the participants to inform them
that there is already a user in the conference. In this case, the
triggering request is the INVITE, and the associated transactions
are the MESSAGE transactions.
Application servers MAY include a Associated-Transactions-State
header field in the responses to a triggering request. Clients can
use the URI in this header field to subscribe to the state of the
associated transactions.
In our example, the response to the INVITE request carries a
Associated-Transactions-State header field. The client subscribes
to the URI received in this header field to monitor the state of
the MESSAGE transactions. This way, the user knows who of the rest
of the participants receives the MESSAGE.
6.1 Syntax
The ABNF of the Associated-Transactions-State header field is:
Associated-Transactions-State = HCOLON transactions-state-uri
transactions-state-uri = SIP-URI / SIPS-URI
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 10]
Internet-Draft SIP Transaction Event Package February 2004
OPEN ISSUE: do we want to have transactions-state-uri = addr-spec,
which includes SIP-URI / SIPS-URI / absoluteURI ? Do we need non-SIP
URIs?
7. Security Considerations
TBD.
8. IANA Considerations
This document registers a new MIME type, application/
transaction-info+xml, new XML namespace and a new SIP header field.
8.1 MIME Registration for application/transaction-info+xml
MIME media type name: application
MIME subtype name: transaction-info+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml as
specified in RFC 3023 [4].
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [4].
Security considerations: See Section 10 of RFC 3023 [4] and Section 7
of this specification.
Interoperability considerations: none.
Published specification: This document.
Applications which use this media type: This document type has been
used to support SIP applications such as MESSAGE exploders.
Additional Information:
Magic Number: None
File Extension: .tin or .xml
Macintosh file type code: "TEXT"
Personal and email address for further information: Gonzalo
Camarillo,
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 11]
Internet-Draft SIP Transaction Event Package February 2004
Intended usage: COMMON
Author/Change controller: The IETF.
8.2 URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:transaction-info
This section registers a new XML namespace, as per the guidelines in
[7]
URI: The URI for this namespace is
urn:ietf:params:xml:ns:transaction-info.
Registrant Contact: IETF, SIPPING working group,,
Gonzalo Camarillo,
XML:
BEGIN
Transaction Information Namespace
Namespace for Transaction Information
application/transaction-info+xml
See RFCXXXX.
END
8.3 Schema Registration
This specification registers a schema, as per the guidelines in [7].
URI: please assign.
Registrant Contact: IETF, SIPPING working group,,
Gonzalo Camarillo,
XML: The XML can be found in Section 5.3.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 12]
Internet-Draft SIP Transaction Event Package February 2004
8.4 Associated-Transactions-State Header Field Registration
9. Acknowledgements
This document is partially based on the event package for INVITE
initiated dialogs [9].
Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] Moats, R., "URN Syntax", RFC 2141, May 1997.
[3] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999.
[4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
3023, January 2001.
[5] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[6] Roach, A., "Session Initiation Protocol (SIP)-Specific Event
Notification", RFC 3265, June 2002.
[7] Mealling, M., "The IETF XML Registry",
draft-mealling-iana-xmlns-registry-05 (work in progress), June
2003.
Informational References
[8] Camarillo, G., "Requirements for Session Initiation Protocol
(SIP) Exploder Invocation", draft-camarillo-sipping-exploders-01
(work in progress), November 2003.
[9] Rosenberg, J. and H. Schulzrinne, "An INVITE Inititiated Dialog
Event Package for the Session Initiation Protocol (SIP)",
draft-ietf-sipping-dialog-package-03 (work in progress), October
2003.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 13]
Internet-Draft SIP Transaction Event Package February 2004
Authors' Addresses
Gonzalo Camarillo
Ericsson
Hirsalantie 11
Jorvas 02420
Finland
EMail: Gonzalo.Camarillo@ericsson.com
Miguel A. Garcia-Martin
Nokia
P.O.Box 407
NOKIA GROUP, FIN 00045
Finland
EMail: miguel.an.garcia@nokia.com
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 14]
Internet-Draft SIP Transaction Event Package February 2004
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2004). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 15]
Internet-Draft SIP Transaction Event Package February 2004
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Camarillo & Garcia-Martin Expires August 6, 2004 [Page 16]