<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY I-D.ietf-geopriv-pdif-lo-profile PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-pdif-lo-profile.xml">
<!ENTITY I-D.winterbottom-geopriv-deref-protocol PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.winterbottom-geopriv-deref-protocol.xml">
<!ENTITY I-D.ietf-geopriv-lbyr-requirements PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-lbyr-requirements.xml">
<!ENTITY I-D.thomson-geopriv-location-quality PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.thomson-geopriv-location-quality.xml">
<!ENTITY I-D.ietf-geopriv-http-location-delivery PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-http-location-delivery.xml">
<!ENTITY I-D.ietf-geopriv-l7-lcp-ps PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-l7-lcp-ps.xml">
<!ENTITY RFC4119   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4119.xml">
<!ENTITY RFC3693   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3693.xml">
<!ENTITY RFC3265   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3265.xml">
<!ENTITY RFC3023   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3023.xml">
<!ENTITY RFC3688   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml">
<!ENTITY RFC3261   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3261.xml">
<!ENTITY RFC3856   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3856.xml">
<!ENTITY RFC4079   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4079.xml">
<!ENTITY RFC4745   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4745.xml">
<!ENTITY RFC3859   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3859.xml">
<!ENTITY I-D.ietf-geopriv-policy PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-policy.xml">
<!ENTITY I-D.winterbottom-geopriv-held-context PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.winterbottom-geopriv-held-context.xml">
<!ENTITY I-D.ietf-geopriv-loc-filters PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-loc-filters.xml">
]>

<?rfc symrefs="yes" ?>
<?rfc sortrefs="no"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc toc="yes" ?>
<rfc category="std" ipr="full3978" docName="draft-winterbottom-sip-location-package-00.txt">
  <front>
    <title abbrev="Location Event Package">A Session Initiation Protocol (SIP) Event Package for
      Location Information</title>

    <author initials="J." surname="Winterbottom" fullname="James Winterbottom">
      <organization>Andrew Corporation</organization>

      <address>
        <postal>
          <street>PO Box U40</street>
          <city>Wollongong University Campus</city>
          <region>NSW</region>
          <code>2500</code>
          <country>AU</country>
        </postal>

        <phone>+61 2 4221 2938</phone>
        <email>james.winterbottom@andrew.com</email>
        <uri>http://www.andrew.com/</uri>
      </address>
    </author>

    <author initials="M." surname="Thomson" fullname="Martin Thomson">
      <organization>Andrew Corporation</organization>
      <address>
        <postal>
          <street>PO Box U40</street>
          <city>Wollongong University Campus</city>
          <region>NSW</region>
          <code>2500</code>
          <country>AU</country>
        </postal>
        <phone>+61 2 4221 2915</phone>
        <email>martin.thomson@andrew.com</email>
        <uri>http://www.andrew.com/</uri>
      </address>
    </author>

    <author initials="H." surname="Tschofenig" fullname="Hannes Tschofenig">
      <organization abbrev="Nokia Siemens Networks">Nokia Siemens Networks</organization>
      <address>
        <postal>
          <street>Linnoitustie 6</street>
          <city>Espoo</city>
          <region/>
          <code>02600</code>
          <country>Finland</country>
        </postal>
        <phone>+358 (50) 4871445</phone>
        <email>Hannes.Tschofenig@nsn.com</email>
        <uri>http://www.tschofenig.priv.at</uri>
      </address>
    </author>

    <date year="2008"/>
    <area>RAI</area>
    <workgroup>SIP</workgroup>
    <keyword>Internet-Draft</keyword>
    <abstract>
      <t>This document specifies a SIP event package allowing allowing a location receiptient to
        subscribe for location information when provided a location URI using the sip, sips, or pres
        URI schemes. The notification that results from the subscription is either the location of
        the Target or an error. </t>
    </abstract>
  </front>


  <middle>

    <section anchor="intro" title="Introduction">

      <t> Location information is generally recognized as being a subset of presence as described in
          <xref target="RFC4079"/>. It is also recognized that location information is most readily
        available from the local access network serving a specific end-device. The node in a local
        access network responsible for determining and desseminating an end-point's location is
        referred to as a location information server (LIS). Where the LIS is capable of supporting
        SIP SUBSCRIBE and NOTIFY messages <xref target="RFC3265"/> for the dissemination of location
        information it becomes a limited capability presence server. To support this limited
        capability a new SIP event package is defined specifically for the subscription to, and
        notification of, a Target's physical location. </t>

      <t> This document proposes the usage of the Session Initiation Protocol (SIP) <xref
          target="RFC3261"/> as a location dereference protocol. This is accomplished by defining a
        new subscription event package as described in RFC3265 <xref target="RFC3265"/>. </t>
      <t> This event package is based on the concept of a location information server (LIS), which
        resides in the same access network as a Target. the LIS is capable of accepting
        subscriptions, storing subscription state, and generating notifications either periodically
        or when the LIS detects changes in a Target's physical location. </t>

      <t>The event package defines a simple but extensible XML schema which allows a location
        recipient to subscribe to a LIS for a Target's location information. A base set of
        subscription criteria are defined in an XML schema. Extensions points are provided in the
        schema so that additional criteria can be specified for future application requirements. </t>
      <t> How the location recipient learns the location URI is out of scope for this document. The
        specification relies of existing SIP, presence, and georpiv mechansisms for the
        authentication of location recipients and the application of these mechanisms is deemed out
        of scope for this specification. Existing presence and location authorization policies such
        as those described in common policy <xref target="RFC4745"/> and geolocation policy <xref
          target="I-D.ietf-geopriv-policy"/> are assumed to be in place. Alternatively, specific
        constraints attached to the location URI itself, such as those described in <xref
          target="I-D.winterbottom-geopriv-held-context"/> are assumed to exist. </t>

    </section>

    <section anchor="terminology" title="Terminology">
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
        "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
          <xref target="RFC2119"/>. </t>
      <t>The terms Location Recipient and Target are used as defined in <xref target="RFC3693"/>
      </t>
      <t>The term location information (LIS) is used throughout this document as defined in <xref
          target="I-D.ietf-geopriv-l7-lcp-ps"/>. A presence server that distributes physical
        location to watchers may also be regarded as a LIS in the terms of reference for this
        document. </t>
    </section>

    <section title="Protocol Interaction">
      <t>Using a location URI that provides a Target's location to a recipient directly from the LIS
        is often preferable and more effient than requiring location information originate from the
        LIS and traverse the Target end-point before reaching the location recipient. This is
        especially true in environments where the Target can move and change points of network
        attachment without an interuption in service. The merits and requirements of using a
        location URI are addressed in detail in the location by reference requirements document
          <xref target="I-D.ietf-geopriv-lbyr-requirements"/>. </t>
      <t> Location configuration protocols, such as HELD, provide an end-point the ability to
        request a location URI that they can distribute to external entities and applications for
        the purpose of later location retrival. A scheme for dereferencing HELD URIs is described in
          <xref target="I-D.winterbottom-geopriv-deref-protocol"/>. This specification describes a
        location information event package that an
        application or entity can use this to request location information directly from a LIS or
        presence server using SIP. </t>
      <t>The SIP subscription functionality is described in <xref target="RFC3265"/>, along with
        general guidelines for defining new event packages for which subscriptions can be made. This
        specification defines a new event package that allows a recipient to specifically subscribe
        for location information. The event package consists of an XML schema that is included in
        the body of the SIP subscribe message, and a new subscribe event header. Both the schema and
        the subscribe event header are registered with IANA in <xref target="iana"/>. The general
        context and model for location subscription is shown in <xref target="fig1"/>. </t>

      <figure anchor="fig1" title="Context Diagram">
        <artwork><![CDATA[
                              +-----------+
  +------------+              | Location  |                +-----------+
  | End Device |              |Information|                | Location  |
  |  (Target)  |              |  Server   |                | Recipient |
  +-----+------+              +----+------+                +-----+-----+
        |                          |                             |
     +--+--------------------------+--+                          |
     |  |                          |  |                          |
     |  |===locationRequest(URI)==>0  |                          |
     |  |                          |  | Location                 |
     |  |                          |  | Configuration            |
     |  0<==locationResponse(URI)==|  | Protocol                 |
     |  |                          |  |                          |
     +--+--------------------------+--+                          |
        |                          |                             |
        |                          |                             |
        |~~~~~~~~~~~~Location Conveyance (URI)~~~~~~~~~~~~~~~~~~>0
        |                          |                             |
        |                       +--+-----------------------------+--+
        |                       |  |                             |  |
        |        Location       |  0<======SUBSCRIBE(loc)========|  |
        |        Event          |  |                             |  |
        |        Package        |  |========NOTIFY(PIDF-LO)=====>0  |
        |                       |  |========NOTIFY(PIDF-LO)=====>0  |
        |                       |  |========NOTIFY(PIDF-LO)=====>0  |
        |                       +--+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+--+
        |                          |                             |
        |                          |                             |
]]></artwork>
      </figure>

    </section>

    <section title="Overview of Operation">
      <t> In this section, an overview of the operation of this event package is presented. In order
        to provide clarity on this package the overview describes behavior that is documented in
        part here, partly in the SIP event framework <xref target="RFC3265"/>, and in the SIP
        specification <xref target="RFC3261"/>. However, the detailed semantics of this package
        require the reader to be familiar with SIP events and the SIP specification itself. </t>

      <t> When an entity, the subscriber, wishes to learn about the location from some user, it
        creates a SUBSCRIBE request. This request identifies the desired Target in the Request-URI,
        using a SIP URI, SIPS URI <xref target="RFC3261"/> or a presence (pres) URI <xref
          target="RFC3859"/>. The SUBSCRIBE request is carried along SIP proxies as any other SIP
        request would be and eventually arrives at a LIS, which will generate a response to the
        request. </t>
      <t> The LIS first authenticates the subscription, then authorizes it. The means for
        authorization are outside the scope of this protocol. If authorized, a 200 OK response is
        returned followed immediately by a NOTFIY message containing the location of the target. If
        authorization could not be obtained at this time, the subscription is considered
        &quot;terminated&quot; with a reason code of &quot;rejected&quot; and a
        $quot;403 Forbidden&quot; response is returned. Periodicially, or as the location of the
        Target changes, the LIS generates and sends NOTIFY messages containing the location
        information to all subscribers with authorized subscriptions. Changes in the state of the
        subscription itself can also trigger NOTIFY messages; that state is carried in the
        Subscription-State header field of the NOTIFY, and would typically indicate whether the
        subscription is active or terminated. No pending state for location information is
        considered. </t>

      <t> The SUBSCRIBE message establishes a "dialog" with the LIS. A dialog is defined in RFC 3261
          <xref target="RFC3261"/>, and it represents the SIP state between a pair of entities to
        facilitate peer-to-peer message exchanges. This state includes the sequence numbers for
        messages in both directions (SUBSCRIBE from the subscriber, NOTIFY from the LIS), in
        addition to a route set and remote target URI. The route set is a list of SIP (or SIPS) URIs
        which identify SIP proxy servers that are to be visited along the path of SUBSCRIBE
        refreshes or NOTIFY requests. The remote target URI is the SIP or SIPS URI that identifies
        the target of the message - the subscriber, in the case of NOTIFY, or the LIS, in the case
        of a SUBSCRIBE refresh. </t>

      <t> The subscription persists for a duration that is negotiated as part of the initial
        SUBSCRIBE. The subscriber will need to refresh the subscription before its expiration, if
        they wish to retain the subscription. This is accomplished by sending a SUBSCRIBE refresh
        within the same dialog established by the initial SUBSCRIBE. This SUBSCRIBE is nearly
        identical to the initial one, but contains a tag in the To header field and a higher CSeq
        header field value. </t>

      <t> The subscriber can terminate the subscription by sending a SUBSCRIBE, within the dialog,
        with an Expires header field (which indicates duration of the subscription) value of zero.
        This causes an immediate termination of the subscription. A NOTIFY request is then generated
        by the LIS with the most recent location information for the Target. </t>

      <t> The LIS can terminate the subscription at any time. To do so, it sends a NOTIFY request
        with a Subscription-State header field with a value of &quot;terminated&quot;. A
        reason parameter is also supplied which provides the reason for the termination. </t>

    </section>

    <section title="Event Package details">

      <section title="Event Package Name">
        <t> A SIP subscription specifies precisely which event or set events (event package) the
          subscriber is interested in being notified about. This specification deals with
          subscription for location information and specifies a new event package excplicitly for
          this purpose. The SIP event notification specification <xref target="RFC3265"/> stipulates
          that a new event package requires the registration of a new &quot;Event&quot;
          header token so that a subscriber can explcitly subscribe for these events. This
          specification defines the &quot;loc-event&quot; Event header token, and registers it in
            <xref target="iana"/>. All subscriptions for location information are expected to use
          this Event header token. </t>
      </section>

      <section title="Event Package Parameters">
        <t> The SIP event framework allows event packages to define additional parameters carried in
          the Event header field. This package, presence, does not define any additional parameters.
        </t>
      </section>

      <section title="Accept Header Value">
        <t> The Accept header in the SUBSCRIBE indicates to the LIS what type of information the
          location recipient is expecting. This event package requires that the Accept header bet
          set to &quot;application/held+xml&quot;. The rationale for resuing the HELD MIME
          type in the NOTIFY message is provide in <xref target="notify"/>. </t>
      </section>

      <section title="Subscription Duration">
        <t> Default is 24 hours. If the URI was generated using HELD Context management or some
          other policy-based mechansism then the LIS MUST provide and expires value that is equal to
          or less than the expiry time of the specified in the policy. </t>
        <t>Very short subscription times will be treated as though they are immediate notification
          requests. Assuming that the subscription is accepted, the LIS will respond with the
          fastest location that it is able to provide. </t>
      </section>

      <section title="Forked SUBSCRIBE Requests">
        <t> This event package does not support forked SUBSCRIBE requests. </t>
      </section>

      <section title="Subscribing for Location Information">

        <section title="SUBSCRIBE Message Body">
          <t>The characteristics of the subscription are defined in the XML schema which is conveyed
            from the subscriber to the LIS in the body of the SUBSCRIBE message. A new MIME type of
            application/loc-event+xml is defined for use with this schema and it is registered in <xref
              target="iana"/>. </t>
          <t> The schema is broken into two parts, a &quot;what&quot; part, and a
            &quot;when&quot; part. The &quot;what&quot; part defines what the
            subscriber requires, and the &quot;when&quot; part defines when the LIS should
            send it. These two components are described in more detail below. </t>

          <section title="What">
            <t> The &quot;what&quot; part of the location subscription comprises of two
              basic components. A location type element allows the subscriber to specify the type of
              location information that they wish to receive, geodetic, civic, or any. The LIS
              should try to provide location in the form subscribed for. If the LIS is unable to
              provide location in the form requested, then it may provide location in an alternative
              form. If the subscriber is unable to process the location form returned by the LIS,
              then the subscriber is expected to terminate the subscription. </t>

            <t> An extension point is included in the schema so that additional requirements of what
              is to be provided in notification responses can be specified. Examples of how to use
              this this extension point are providced in <xref target="appendixA"/>. Thes examples
              should be considered informative only. </t>

          </section>

          <section title="When">
            <t> The &quot;when&quot; part of the subscription tells the LIS when the
              subscriber would like to receive location information about the Target. Two basic
              components are provided. An interval, in seconds, tell the LIS how often to send a
              location update to the subscriber. An trigger for sending notifications when the
              Target's point of network attachment changes is also provided. The
              &quot;when&quot; elements operate in a logical OR manner, and a notification
              SHOULD be sent whenever one of these conditions occurs. </t>
            <t> An extension point exists in the schema so that additional notification triggers can
              be specified and added as they become required. </t>
          </section>
        </section>
      </section>

      <section title="Location Notification">
        <t> Location information and error messages are returned to the subscriber in the body of a
          SIP NOTIFY message. </t>
        <section anchor="notify" title="NOTIFY Bodies">
          <t> The NOTIFY body is either a HELD locationResponse, or a HELD error message, both are
            defined in <xref target="I-D.ietf-geopriv-http-location-delivery"/>. The rationale for
            reusing the location response and error messages from HELD is twofold. Firstly a
            location recipient cannot be assured ahead of time of the location URI type that a
            Target will provide it; this is largely determined by what the LIS in the local access
            network provides to the Target and so is out of the control of both the Target and
            recipient. So the recipient should be capable of dealing with HELD location responses in
            any event. Secondly, the HELD location response and error messages provide excellent
            containers for the information that the LIS needs to provide to the location recipient
            in a NOTIFY. Rules from HELD <xref target="I-D.ietf-geopriv-http-location-delivery"/>
            apply when constructing these messages, with the exception of the clarifications
            provided later. </t>
          <t> An error will, in some circumstances, result in a terminated subscription, however in
            other cases the error condition may be present for only one specific notification cycle
            in which case the subscription will remain active. The subscriber MUST examine the value
            of the Subscription-State header to determine if the subscription has been terminated or
            not. </t>
          <t> The LIS MUST send a NOTIFY with a Subscription-State header value of
            &quot;terminated&quot; and a reason code of &quot;noresource&quot;when
            it is no longer able to provide the Target's location though the subscribed URI. This
            informs the subscriber that no further attempts to subscribe to the resource should be
            attempted. The LIS MUST include a HELD error message with a code of
            &quot;locationUnknown&quot; in the NOTFIY body when this condition occurs. </t>
        </section>
        <section title="Rate of Notifications">
          <t> The rate at which notifications are generated is excplictly defined in the interval
            element of the &quot;when&quot; component in the SUBSCRIBE body. This element
            defines how often the subscriber wishes to receive notifications about a Target's
            location. The interval value is a positive integer respresenting seconds. </t>
          <t> A new HELD error token of &quot;intervalTooShort&quot; is regsitered in <xref
              target="iana"/> and MUST be used by the LIS when an inappropriately short notification
            interval is requested by the subscriber. When this error is returned the corresponding
            NOTIFY message MUST have a Subscription-State header value of
            &quot;termninated&quot;, reason code of &quot;giveup&quot; and a value
            for the retry-after parameter MAY be provided. </t>
        </section>
      </section>

      <!-- 
        <section title="Authentication">
          <t>
            TBD
          </t>
        </section>
        
        <section title="Authorization">
          <t>
            TBD
          </t>
        </section>
        -->

      <section title="State Agents">
        <t> The LIS is responsible for keeping track of where a Target is physically located in the
          access network. Stare, as it pertains to this event package, refers to the policies
          associated with the URI to which the subscription was made, and physical location of the
          Target. State is therefore maintained internal to the LIS and is explcitly resolved at the
          time that a notification is generated. </t>
      </section>


    </section>

    <section anchor="schema" title="Schema">

      <t>This section defines the schema that constitutes the body of this even package. </t>

      <figure anchor="schem" title="XML Schema for Subscription Body">
        <artwork><![CDATA[
 <?xml version="1.0" encoding="UTF-8"?>
<xs:schema
  targetNamespace="urn:ietf:params:xml:ns:loc-event"
  xmlns:loc-event="urn:ietf:params:xml:ns:loc-event"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:qop="urn:ietf:params:xml:ns:geopriv:lq"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
     
  <xs:element name="locationSubscription">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="what" type="loc-event:subscribeFor"
                    minOccurs="1" maxOccurs="1"/>
           
        <xs:element name="when" type="loc-event:trigger"
                    minOccurs="1" maxOccurs="1"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
 
  <xs:complexType name="subscribeFor">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:element name="locationType" 
                      type="loc-event:locationType"
                      minOccurs="1" maxOccurs="1"/>
           
          <xs:element name="QoP" type="qop:quality"
                      minOccurs="0" maxOccurs="1"/>

          <xs:any namespace="##other" processContents="lax"
                  minOccurs="0"  maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:simpleType name="locationType">
    <xs:restriction base="xs:token">
      <xs:enumeration value="any"/>
      <xs:enumeration value="civic"/>
      <xs:enumeration value="geodetic"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="trigger">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:element name="updateInterval" 
                 type="loc-event:intervalType"/>

          <xs:element name="attachmentChange" type="xs:boolean"
                      minOccurs="0" maxOccurs="1"/>

          <xs:any namespace="##other" processContents="lax"
                  minOccurs="0"  maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="intervalType">
    <xs:simpleContent>
      <xs:extension base="xs:positiveInteger">
        <xs:attribute name="notificationCount" 
          type="xs:positiveInteger"
                      use="optional" default="1"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>
]]></artwork>
      </figure>

    </section>

    <section title="Examples">
      <section title="Example 1">
        <t> In this example emergency application 1, emgapp1, is subscribing for the location
          information associated is xyzabc being service by the LIS at example.com. The emergency
          application would like to get geodetic location information, updated every 10 seconds or
          when xyzabc changes wireless access points. The subscription is for a duration of 30
          minutes. </t>

        <figure anchor="ex1-1" title="SUBSCRIBE Message">
          <artwork><![CDATA[
SUBSCRIBE sip:xyzabc@lis.example.com SIP/2.0
Via: SIP/2.0/TCP emergency.emergizone.com;branch=z9hG4bKnashds7
To: <sip:xyzabc@lis.example.com>
From: <sip:emgapp1@emergizone.com>;tag=xfg9
Call-ID: 2010@emergency.emergizone.com
CSeq: 17766 SUBSCRIBE
Max-Forwards: 70
Event: loc-event
Accept: application/held+xml
Contact: <sip:emgapp1@emergency.emergizone.com>
Expires: 1800
Content-Type: application/loc-event+xml
Content-Length: 330

<?xml version="1.0"?>
<locationSubscription xmlns="urn:ietf:params:xml:ns:loc-event">
  <what>
    <locationType>
      geodetic
    </locationType>
  </what>
  <when>
    <updateInterval>
      10
    </updateInterval>
    <attachmentChange>
      yes
    </attachmentChange>
  </when>
</locationSubscription>

]]></artwork>
        </figure>

        <t> The successful response to the subscription shown in <xref target="ex1-1"/> is a 200 OK
          followed almost immediately by a NOTIFY containing the requested location. This is shown
          in <xref target="ex1-2"/>. </t>
        <figure anchor="ex1-2" title="NOTIFY Message with Location Information">
          <artwork><![CDATA[
NOTIFY sip:emgapp1@emergizone.com SIP/2.0
Via: SIP/2.0/TCP lis.example.com;branch=z9hG4bKna998sk
From: <sip:xyzabc@lis.example.com>;tag=ffd2
To: <sip:emgapp1@emergizone.com>;tag=xfg9
Call-ID: 2010@emergency.emergizone.com
Event: loc-event
Subscription-State: active;expires=1790
Max-Forwards: 70
CSeq: 8775 NOTIFY
Contact: sip:lis.example.com
Content-Type: application/held+xml
Content-Length: 911

<?xml version="1.0"?>
<locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held">
  <presence xmlns="urn:ietf:params:xml:ns:pidf"
            entity="pres:xyzabc@lis.example.com">
    <tuple id="3b650sf789nd">
      <status>
        <geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
          <location-info>
            <Point xmlns="http://www.opengis.net/gml"
                   srsName="urn:ogc:def:crs:EPSG::4326">
              <pos>-34.407 150.88001</pos>
            </Point>
          </location-info>
          <usage-rules>
            <retention-expiry>
              2006-01-11T03:42:28+00:00
            </retention-expiry>
          </usage-rules>
          <method>
            Device-Assisted_A-GPS
          </method>
        </geopriv>
      </status>
      <timestamp>2008-03-31T03:42:28+00:00</timestamp>
    </tuple>
  </presence>
</locationResponse>

]]></artwork>
        </figure>

      </section>

      <section title="Example 2">
        <t> An error message is returned when a problem with the subscription is encountered, for
          example the location URI that the subscriber subscribed too has expired or its usage count
          has been exceeded. This error message may look something like the NOTIFY shown in <xref
            target="ex2-1"/>. </t>
        <figure anchor="ex2-1" title="NOTIFY Message with Error">
          <artwork><![CDATA[
NOTIFY sip:emgapp1@emergizone.com SIP/2.0
Via: SIP/2.0/TCP lis.example.com;branch=z9hG4bKna998sk
From: <sip:xyzabc@lis.example.com>;tag=ffd2
To: <sip:emgapp1@emergizone.com>;tag=xfg9
Call-ID: 2010@emergency.emergizone.com
Event: loc-event
Subscription-State: terminated;reason=noresource
Max-Forwards: 70
CSeq: 8775 NOTIFY
Contact: sip:lis.example.com
Content-Type: application/held+xml
Content-Length: 159

<?xml version="1.0"?>
<error xmlns="urn:ietf:params:xml:ns:geopriv:held"
       code="locationUnknown"
       message="Unable to determine location"/>

]]></artwork>
        </figure>


      </section>

    </section>

    <section anchor="security-considerations" title="Security Considerations">

      <t> TBD. </t>

    </section>

    <section anchor="iana" title="IANA Considerations">
      <section title="HELD Error Token Registration">
        <t> Reference: RFC-XXXX (i.e., this document) requires the following new HELD error code to
          be added to the HELD error code respository defined in <xref
            target="I-D.ietf-geopriv-http-location-delivery"/>. <list>
            <t>Error code: intervalTooShort</t>
          </list>
        </t>
      </section>

      <section title="URN Sub-Namespace Registration for urn:ietf:params:xml:ns:loc-event">
        <t> This section registers a new XML namespace, <spanx style="verb"
          >urn:ietf:params:xml:ns:loc-event</spanx>, as per the guidelines in <xref
            target="RFC3688"/>. <list style="empty">
              <t>URI: urn:ietf:params:xml:ns:loc-event</t>
            <t>Registrant Contact: IETF, SIP working group, (sip@ietf.org), James
              Winterbottom (james.winterbottom@andrew.com).</t>

            <t>XML: <figure>
                <artwork><![CDATA[
BEGIN
<?xml version="1.0"?>
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
    <head>
      <title>Location Information Subscription Event Package</title>
    </head>
    <body>
      <h1>Namespace for the Location Information 
          Subscription Application Event Package
      </h1>
      <h2>urn:ietf:params:xml:ns:loc-event</h2>
[[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX
    with the RFC number for this specification.]]
      <p>See <a href="[[RFC URL]]">RFCXXXX</a>.</p>
    </body>
  </html>
END
]]></artwork>
              </figure>
            </t>
          </list>
        </t>
      </section>

      <section title="XML Schema Registration">
        <t> This section registers an XML schema as per the guidelines in <xref target="RFC3688"/>.
            <list style="hanging">
              <t hangText="URI:">urn:ietf:params:xml:schema:loc-event</t>
            <t hangText="Registrant Contact:">IETF, SIP working group, (sip@ietf.org), James
              Winterbottom (james.winterbottom@andrew.com).</t>
            <t hangText="Schema:">The XML for this schema can be found as the entirety of <xref
                target="schema"/> of this document. </t>
          </list>
        </t>
      </section>

      <section title="MIME Media Type Registration for 'application/loc-event+xml'">
        <t>This section registers the <spanx style="verb">application/loc-event+xml</spanx> MIME type.
            <list style="hanging">
            <t hangText="To:">ietf-types@iana.org</t>
              <t hangText="Subject:">Registration of MIME media type application/loc-event+xml</t>
            <t hangText="MIME media type name:">application</t>
              <t hangText="MIME subtype name:">loc-event+xml</t>
            <t hangText="Required parameters:">(none)</t>
            <t hangText="Optional parameters:">charset<vspace/>Indicates the character encoding of
              enclosed XML. Default is UTF-8.</t>
            <t hangText="Encoding considerations:">Uses XML, which can employ 8-bit characters,
              depending on the character encoding used. See <xref target="RFC3023">RFC 3023</xref>,
              section 3.2.</t>
            <t hangText="Security considerations:">This content type is designed to carry protocol
              data related to the location of an entity, which could include information that is
              considered private. Appropriate precautions should be taken to limit disclosure of
              this information. </t>
            <t hangText="Interoperability considerations:">This content type provides a basis for a
              protocol</t>
            <t hangText="Published specification:">RFC XXXX [[NOTE TO IANA/RFC-EDITOR: Please
              replace XXXX with the RFC number for this specification.]]</t>
            <t hangText="Applications which use this media type:">Location information consumers.</t>
            <t hangText="Additional Information:">Magic Number(s): (none)<vspace/>File extension(s):
              .xml<vspace/>Macintosh File Type Code(s): (none)</t>
            <t hangText="Person &amp; email address to contact for further information:">James
              Winterbottom &lt;james.winterbottom@andrew.com&gt;</t>
            <t hangText="Intended usage:">LIMITED USE</t>
            <t hangText="Author/Change controller:">This specification is TBD</t>
            <t hangText="Other information:">This media type is a specialization of <xref
                target="RFC3023">application/xml</xref>, and many of the considerations described
              there also apply to application/loc-event+xml.</t>
          </list>
        </t>
      </section>

      <section title="Event Package Registration">
        <t> This specification registers an event package, based on the registration procedures
          defined in RFC3265 <xref target="RFC3265"/>. The following is the information required for
          such a registration: <list style="hanging">
            <t hangText="Package Name:">loc-event</t>
            <t hangText="Package or Template-Package:">This is a Package</t>
            <t hangText="Published Document:">RFC XXXX [[NOTE TO IANA/RFC-EDITOR: Please replace
              XXXX with the RFC number for this specification.]]</t>
            <t hangText="Person or Contact:">James Winterbottom, james.winterbottom@andrew.com</t>
          </list>
        </t>
      </section>

    </section>

    <section title="Acknowledgements">
      <t> We would like to thank Miguel Garcia and Brian Rosen for their comments.</t>
    </section>

  </middle>
  <back>
    <references title="Normative References"> &RFC2119; &RFC3693; &RFC3265;
      &RFC3023; &RFC3688; &RFC3859; &RFC3261;
      &I-D.ietf-geopriv-lbyr-requirements; &I-D.ietf-geopriv-http-location-delivery;
      &I-D.ietf-geopriv-l7-lcp-ps; </references>
    <references title="Informative References"> &RFC4079; &RFC3856;
      &I-D.ietf-geopriv-pdif-lo-profile; &I-D.winterbottom-geopriv-deref-protocol;
      &RFC4119; &RFC4745; &I-D.ietf-geopriv-policy;
      &I-D.winterbottom-geopriv-held-context; &I-D.thomson-geopriv-location-quality;
      &I-D.ietf-geopriv-loc-filters; </references>
    <section anchor="appendixA" title="Subscription Examples">
      <t> The exmaples in this appendix should be regarded as non-normative, that is that they are
        for informational purposes only. There intent is to demonstrate that other geoprive location
        request criteria can easily be included into the framework described in this document. </t>
      <section title="Requesting a Quality of Position">
        <t> It is quite common for applications to want loation to be provided as a set of
          coordinates, latitude, longitude and optionally alitutde, and an area of uncertainty. The
          document <xref target="I-D.thomson-geopriv-location-quality"/> describes a means by which
          location information of a specific accuracy and/or confidence can be requested. Together
          these characteristics are referred to as the Quality of Position (QoP). The following
          example show how a location subscription can be constructed including QoP
          parameters based on the scheme provided in <xref
            target="I-D.thomson-geopriv-location-quality"/>, the location provided in the subsequent
          location response messages should also comply with <xref
            target="I-D.thomson-geopriv-location-quality"/>. </t>
        <figure anchor="exAAP-QoP1" title="Subscribing for Location with a Quality of Position">
          <artwork><![CDATA[
<locationSubscription xmlns="urn:ietf:params:xml:ns:loc-event">
  <what>
    <locationType>geodetic</locationType>
    <quality xmlns="urn:ietf:params:xml:ns:geopriv:lq">
      <maxUncertainty confidence="95">
        <horizontal>150</horizontal>
        <vertical>1000</vertical>
      </maxUncertainty>
      <maxAge>PT30S</maxAge>
    </quality>
  </what>
  <when>
    <updateInterval>
      180
    </updateInterval>
    <attachmentChange>
      true
    </attachmentChange>
  </when>
</locationSubscription>

]]></artwork>
        </figure>
      </section>

      <section title="Inclusion of Mahy Loc-Filters">
        <t> Rohan Mahy produced an early specification <xref target="I-D.ietf-geopriv-loc-filters"/>
          that described how specific location events and triggers could be defined in an XML
          document. This work is easily included into the framework. </t>
        <t> In this example the LIS is to generate a noficiation if the Target moves horizontally by
          more than 20 metres, or vertical by more than 10 metres. The LIS should provide an update
          every 3 minutes regardless of the Target movements, or when the Target changes its point
          of attachment to the network. </t>
        <figure anchor="exAAP-LF-1" title="Subscribing for Location of Location Constrained Target">
          <artwork><![CDATA[
<locationSubscription xmlns="urn:ietf:params:xml:ns:loc-event">
  <what>
    <locationType>civic</locationType>
  </what>
  <when>
    <updateInterval>
      180
    </updateInterval>
    <attachmentChange>
      true
    </attachmentChange>
    <location-filter 
        xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:containment">
     <movedHoriz uom="urn:ogc:def:uom:EPSG::9001">20</movedHoriz>
     <movedVert uom="urn:ogc:def:uom:EPSG::9001">3</movedVert>
    </location-filter>
  </when>
</locationSubscription>
]]></artwork>
        </figure>

        <t> In this example LIS is to generate a noficiation if the Target exceeds a speed of 3 MPH.
          The LIS should provide an update every 3 minutes regardless of the Target movements, or
          when the Target changes its point of attachment to the network. </t>
        <figure anchor="exAAP-LF-2" title="Subscribing for Location of a Speed Limited Target">
          <artwork><![CDATA[
<locationSubscription xmlns="urn:ietf:params:xml:ns:loc-event">
  <what>
    <locationType>civic</locationType>
  </what>
  <when>
    <updateInterval>
      60
    </updateInterval>
    <location-filter 
      xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:containment">
      <speedExceeds uom="#mps">3</speedExceeds>
    </location-filter>
  </when>
</locationSubscription>
]]></artwork>
        </figure>

        <t> This final filters example shows how the entry or exit of a specific polygon by the
          Target can be subscribed to using the framework. </t>
        <figure anchor="exAAP-LF-3" title="Subscribing for Location of Target in a Polygon">
          <artwork><![CDATA[
<locationSubscription xmlns="urn:ietf:params:xml:ns:loc-event">
  <what>
    <locationType>civic</locationType>
  </what>
  <when>
    <updateInterval>
      60
    </updateInterval>
    <location-filter 
      xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:containment">
      <enterOrExit>
        <gml:Polygon
             srsName="urn:ogc:def:crs:EPSG::4326"
             xmlns:gml="http://www.opengis.net/gml">
          <gml:exterior>
            <gml:LinearRing>
              <gml:posList>
                37.41188 -121.93243
                37.41142 -121.93243
                37.41142 -121.93132
                37.41188 -121.93132
                37.41188 -121.93243
              </gml:posList>
            </gml:LinearRing>
          </gml:exterior>
        </gml:Polygon>
      </enterOrExit>
    </location-filter>
  </when>
</locationSubscription>

]]></artwork>
        </figure>

      </section>

    </section>
  </back>
</rfc>
