created)
Figure 3
The FSM for dialog state is shown in Figure 3. The FSM is best
understood by considering the UAC and UAS cases separately.
The FSM is created in the Trying state when the UAC sends an INVITE
request. Upon receipt of a 1xx without a tag, the FSM transitions to
the Proceeding state. Note that there is no actual dialog yet, as
defined by the SIP specification. However, there is a "half-dialog",
in the sense that two of the three components of the dialog ID (the
call identifier and local tag) are known. If a 1xx with a tag is
received, the FSM transitions to the Early state. The full dialog
identifier is now defined. Had a 2xx been received, the FSM would
have transitioned to the Confirmed state.
If, after transitioning to the Early or Confirmed states, the UAC
receives another 1xx or 2xx respectively with a different tag,
another instance of the FSM is created, initialized into the Early or
Confirmed state, respectively. The benefit of this approach is that
there will be a single FSM representing the entire state of the
invitation and resulting dialog when dealing in the common case of no
forking.
If the UAC sends a CANCEL and then subsequently receives a 487 to its
INVITE transaction, all FSMs spawned from that INVITE transition to
the Terminated state with the event "cancelled". If the UAC receives
a new invitation (with a Replaces [13] header) that replaces the
current Early or Confirmed dialog, all INVITE transactions spawned
from the replaced invitation transition to the Terminated state with
the event "replaced". If the INVITE transaction terminates with a
non-2xx response for any other reason, all FSMs spawned from that
INVITE transition to the Terminated state with the event "rejected".
Once in the Confirmed state, the call is active. It can transition
to the Terminated state if the UAC sends a BYE or receives a BYE
(corresponding to the "local-bye" and "remote-bye" events as
appropriate), if a mid-dialog request generates a 481 or 408 response
(corresponding to the "error" event), or a mid-dialog request
generates no response (corresponding to the "timeout" event).
From the perspective of the UAS, when an INVITE is received, the FSM
is created in the Trying state. If it sends a 1xx without a tag, the
FSM transitions to the Proceeding state. If a 1xx is sent with a
tag, the FSM transitions to the Early state, and if a 2xx is sent, it
transitions to the Confirmed state. If the UAS receives a CANCEL
request and then generates a 487 response to the INVITE (which can
occur in the Proceeding and Early states), the FSM transitions to the
Terminated state with the event "cancelled". If the UAS generates
any other non-2xx final response to the INVITE request, the FSM
transitions to the Terminated state with the event "rejected". If
the UAS receives a new invitation (with a Replaces [13] header field)
that replaces the current Confirmed dialog, the replaced invitation
transitions to the Terminated state with the event "replaced". Once
in the Confirmed state, the other transitions to the Terminated state
occur for the same reasons they do in the case of UAC.
There should never be a transition from the Trying state to the
Terminated state with the event "cancelled", since the SIP
specification prohibits transmission of CANCEL until a provisional
response is received. However, this transition is defined in the
FSM just to unify the transitions from Trying, Proceeding, and
Early states to the Terminated state.
3.7.2. Applying the State Machine
The notifier MAY generate a NOTIFY request on any event transition of
the FSM. Whether it does or not is policy dependent. However, some
general guidelines are provided.
When the subscriber is unauthenticated, or it is authenticated but
represents a third party with no specific authorization policies, it
is RECOMMENDED that subscriptions to an individual dialog or to a
specific set of dialogs be forbidden. Only subscriptions to all
dialogs (i.e., there are no dialog identifiers in the Event header
field) are permitted. In that case, actual dialog states across all
dialogs will not be reported. Rather, a single "virtual" dialog FSM
will be used, and event transitions on that FSM will be reported.
If there is any dialog at the UA whose state is Confirmed, the
virtual FSM is in the Confirmed state. If there are no dialogs at
the UA in the Confirmed state but there is at least one in the Early
state, the virtual FSM is in the Early or Confirmed state. If there
are no dialogs in the Confirmed or Early states but there is at least
one in the Proceeding state, the virtual FSM is in the Proceeding,
Early, or Confirmed state. If there are no dialogs in the Confirmed,
Early, or Proceeding states but there is at least one in the Trying
state, the virtual FSM is in the Trying, Proceeding, Early or
Confirmed state. The choice of state to use depends on whether the
UA wishes to let unknown users know that their phone is ringing, as
opposed to being in an active call.
It is RECOMMENDED that, in the absence of any preference, Confirmed
is used in all cases as shown in the example in Section 3.6.
Furthermore, it is RECOMMENDED that the notifications of changes in
the virtual FSM machine not convey any information except the state
of the FSM and its event transitions - no dialog identifiers (which
are ill-defined in this model in any case). The use of this virtual
FSM allows minimal information to be conveyed. A subscriber cannot
know how many calls are in progress, or with whom, just that there
exists a call. This is the same information they would receive if
they simply sent an INVITE to the user instead; a 486 (Busy Here)
response would indicate that they are on a call.
When the subscriber is authenticated and has authenticated itself
with the same address-of-record that the UA itself uses, if no
explicit authorization policy is defined, it is RECOMMENDED that all
state transitions on dialogs that have been subscribed to be
reported, along with complete dialog IDs. This means either all of
the dialogs, if no dialog identifiers were present in the Event
header field, or the specific set of dialogs identified by the Event
header field parameters.
The notifier SHOULD generate a NOTIFY request on any change in the
characteristics associated with the dialog. Since these include
Contact URIs, Contact parameters, and session descriptions, receipt
of re-INVITEs and UPDATE requests [3] that modify this information
MAY trigger notifications.
3.8. Subscriber Processing of NOTIFY Requests
The SIP Events framework expects packages to specify how a subscriber
processes NOTIFY requests in package-specific ways. In particular, a
package should specify how it uses the NOTIFY requests to construct a
coherent view of the state of the subscribed resource.
Typically, the NOTIFY for the dialog package will contain information
about only those dialogs whose state has changed. To construct a
coherent view of the total state of all dialogs, a subscriber to the
dialog package will need to combine NOTIFYs received over time.
Notifications within this package can convey partial information;
that is, they can indicate information about a subset of the state
associated with the subscription. This means that an explicit
algorithm needs to be defined in order to construct coherent and
consistent state. The details of this mechanism are specific to the
particular document type. See Section 4.3 for information on
constructing coherent information from an application/dialog-info+xml
document.
3.9. Handling of Forked Requests
Since dialog state is distributed across the UA for a particular
user, it is reasonable and useful for a SUBSCRIBE request for dialog
state to fork and to reach multiple UAs.
As a result, a forked SUBSCRIBE request for dialog state can install
multiple subscriptions. Subscribers to this package MUST be prepared
to install subscription state for each NOTIFY generated as a result
of a single SUBSCRIBE.
3.10. Rate of Notifications
For reasons of congestion control, it is important that the rate of
notifications not be excessive. It is RECOMMENDED that the server
not generate notifications for a single subscriber faster than once
every 1 second.
3.11. State Agents
Dialog state is ideally maintained in the user agents in which the
dialog resides. Therefore, the elements that maintain the dialog are
the ones best suited to handle subscriptions to it. However, in some
cases, a network agent may also know the state of the dialogs held by
a user. Such state agents MAY be used with this package.
4. Dialog Information Format
Dialog information is an XML document [4] that MUST be well-formed
and SHOULD be valid. Dialog 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 dialog information documents
and document fragments. The namespace URI for elements defined by
this specification is a URN [5], using the namespace identifier
’ietf’ defined by [6] and extended by [7]. This URN is:
urn:ietf:params:xml:ns:dialog-info
A dialog information document begins with the root element tag
"dialog-info".
4.1. Structure of Dialog Information
A dialog information document starts with a dialog-info element.
This element has three mandatory attributes:
o version: This attribute allows the recipient of dialog 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 non-negative 32 bit integer.
o state: This attribute indicates whether the document contains the
full dialog information, or whether it contains only information
on those dialogs that have changed since the previous document
(partial).
o entity: This attribute contains a URI that identifies the user
whose dialog information is reported in the remainder of the
document. This user is referred to as the "observed user".
The dialog-info element has a series of zero or more dialog sub-
elements. Each of those represents a specific dialog. An example:
<?xml version="1.0"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
version="0" notify-state="full"
entity="sip:alice@example.com">
</dialog-info>
4.1.1. Dialog Element
The dialog element reports information about a specific dialog or
"half-dialog". It has a single mandatory attribute: id. The id
attribute provides a single string that can be used as an identifier
for this dialog or "half-dialog". This is a different identifier
than the dialog ID defined in RFC 3261 [2], but related to it.
For a caller, the id is created when an INVITE request is sent. When
a 1xx response with a tag, or a 2xx response is received, the dialog
is formally created. The id remains unchanged. However, if an
additional 1xx or 2xx is received, resulting in the creation of
another dialog (and resulting FSM), that dialog is allocated a new
id.
For a callee, the id is created when an INVITE outside of an existing
dialog is received. When a 2xx or a 1xx with a tag is sent, creating
the dialog, the id remains unchanged.
The id MUST be unique amongst all current dialogs at a UA.
There are a number of optional attributes that provide identification
information about the dialog:
o call-id: This attribute is a string that represents the call-id
component of the dialog identifier. (Note that single and
double quotes inside a call-id must be escaped using "e;
for " and ' for ’ .)
o local-tag: This attribute is a string that represents the
local-tag component of the dialog identifier.
o remote-tag: This attribute is a string that represents the
remote-tag component of the dialog identifier. The remote tag
attribute won’t be present if there is only a "half-dialog",
resulting from the generation of an INVITE for which no final
responses or provisional responses with tags has been received.
o direction: This attribute is either initiator or recipient, and
indicates whether the observed user was the initiator of the
dialog, or the recipient of the INVITE that created it.
<?xml version="1.0"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
version="0" state="partial"
entity="sip:alice@example.com">
<dialog id="as7d900as8" call-id="a84b4c76e66710"
local-tag="1928301774" direction="initiator">
...
</dialog>
</dialog-info>
The sub-elements of the dialog element provide additional information
about the dialog. Some of these sub-elements provide more detail
about the dialog itself, while the local and remote sub-elements
describe characteristics of the participants involved in the dialog.
The only mandatory sub-element is the state element.
4.1.2. State Element
The "state" element indicates the state of the dialog. Its value is
an enumerated type describing one of the states in the FSM above. It
has an optional event attribute that can be used to indicate the
event that caused any transition into the terminated state, and an
optional code attribute that indicates the response code associated
with any transition caused by a response to the original INVITE.
<state event="rejected" code="486">terminated</state>
4.1.3. Duration Element
The "duration" element contains the amount of time, in seconds, since
the FSM was created.
<duration>145</duration>
4.1.4. Replaces Element
The "replaces" element is used to correlate a new dialog with one it
replaced as a result of an invitation with a Replaces header field.
This element is present in the replacement dialog only (the newer
dialog) and contains attributes with the call-id, local-tag, and
remote-tag of the replaced dialog.
<replaces call-id="hg287s98s89"
local-tag="6762h7" remote-tag="09278hsb"/>
4.1.5. Referred-By Element
The "referred-by" element is used to correlate a new dialog with a
REFER [12] request that triggered it. The element is present in a
dialog that was triggered by a REFER request that contained a
Referred-By [11] header field and contains the (optional) display
name attribute and the Referred-By URI as its value.
<referred-by display="Bob">sip:bob@example.com</referred-by>
4.1.6. Local and Remote Elements
The "local" and "remote" elements are sub-elements of the dialog
element that contain information about the local and remote
participants, respectively. They both have a number of optional
sub-elements that indicate the identity conveyed by the participant,
the target URI, the feature-tags of the target, and the
session-description of the participant.
4.1.6.1. Identity Element
The "identity" element indicates a local or remote URI, as defined in
[2] as appropriate. It has an optional attribute, display, that
contains the display name from the appropriate URI.
Note that multiple identities (for example a sip: URI and a tel:
URI) could be included if they all correspond to the participant.
To avoid repeating identity information in each request, the
subscriber can assume that the identity URIs are the same as in
previous notifications if no identity elements are present in the
corresponding local or remote element. If any identity elements
are present in the local or remote part of a notification, the new
list of identity tags completely supersedes the old list in the
corresponding part.
<identity display="Anonymous">
sip:anonymous@anonymous.invalid</identity>
4.1.6.2. Target Element
The "target" contains the local or remote target URI constructed by
the user agent for this dialog, as defined in RFC 3261 [2] in a "uri"
attribute.
It can contain a list of Contact header parameters in param sub-
elements (such as those defined in [10]). The param element contains
two required attributes, pname and pval. Boolean parameters are
represented by the explicit pval values, "true" and "false" (for
example, when a feature parameter is explicitly negated). Parameters
that have no value at all are represented by the explicit pval value
"true". The param element itself has no contents. To avoid
repeating Contact information in each request, the subscriber can
assume that the target URI and parameters are the same as in previous
notifications if no target element is present in the corresponding
local or remote element. If a target element is present in the local
or remote part of a notification, the new target tag and list of
parameter tags completely supersedes the old target and parameter
list in the corresponding part. Note that any quoting (including
extra angle-bracket quoting used to quote string values in [10]) or
backslash escaping MUST be removed before being placed in a pval
attribute. Any remaining single quotes, double quotes, and
ampersands MUST be properly XML escaped.
<target uri="sip:alice@pc33.example.com">
<param pname="isfocus" pval="true"/>
<param pname="class" pval="business"/>
<param pname="description" pval="Alice’s desk & office"/>
<param pname="sip.rendering" pval="no"/>
</target>
4.1.6.3. Session Description Element
The session-description element contains the session description used
by the observed user for its end of the dialog. This element should
generally NOT be included in the notifications, unless it was
explicitly requested by the subscriber. It has a single attribute,
"type", which indicates the MIME media type of the session
description. To avoid repeating session description information in
each request, the subscriber can assume that the session description
is the same as in previous notifications if no session description
element is present in the corresponding local or remote element.
4.2. Sample Notification Body
<?xml version="1.0" encoding="UTF-8"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:dialog-info"
version="1" state="full">
<dialog id="123456">
<state>confirmed</state>
<duration>274</duration>
<local>
<identity display="Alice">sip:alice@example.com</identity>
<target uri="sip:alice@pc33.example.com">
<param pname="isfocus" pval="true"/>
<param pname="class" pval="personal"/>
</target>
</local>
<remote>
<identity display="Bob">sip:bob@example.org</identity>
<target uri="sip:bobster@phone21.example.org"/>
</remote>
</dialog>
</dialog-info>
4.3. Constructing Coherent State
The dialog information subscriber maintains a table listing the
dialogs, with a row for each dialog. Each row is indexed by an ID
that is present in the "id" attribute of the "dialog" element. Each
row contains the state of that dialog, 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 "dialog-info" element in the first document received. Each
time a new document is received, the value of the local version
number is compared to the "version" attribute in the new document.
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 (SUBSCRIBE) 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 processing of the dialog 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 "dialog-info"
element, the contents of the table are flushed and then repopulated
from the document. A new row in the table is created for each
"dialog" element. If the document contains partial state, as
indicated by the value of the "state" attribute in the "dialog-info"
element, the document is used to update the table. For each "dialog"
element in the document, the subscriber checks to see whether a row
exists for that dialog. This check compares the ID in the "id"
attribute of the "dialog" element with the ID associated with the
row. If the dialog does not exist in the table, a row is added and
its state is set to the information from that "dialog" element. If
the dialog does exist, its state is updated to be the information
from that "dialog" 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.
4.4. Schema
The following is the schema for the application/dialog-info+xml type:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
targetNamespace="urn:ietf:params:xml:ns:dialog-info"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="urn:ietf:params:xml:ns:dialog-info"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!-- This import brings in the XML language
attribute xml:lang-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/03/xml.xsd"/>
<xs:element name="dialog-info">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:dialog" minOccurs="0"
maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="version" type="xs:nonNegativeInteger"
use="required"/>
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="full"/>
<xs:enumeration value="partial"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="entity" type="xs:anyURI"
use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="dialog">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:state" minOccurs="1" maxOccurs="1"/>