rfc4825-xcap.txt

关于XCAP协议的rfc文档

   Each document within the XCAP root is identified by its document
   selector.  The document selector is a sequence of path segments,
   separated by a slash ("/").  These path segments define a
   hierarchical structure for organizing documents within any XCAP root.
   The first path segment MUST be the XCAP AUID.  So, continuing the
   example above, all of the documents used by the resource lists
   application would be under "http://xcap.example.com/resource-lists".

   o  Implementors making use of HTTP servlets should be aware that XCAP
      may require them to get authorization from the server
      administrator to place resources within this specific subset of
      the URI namespace.




Rosenberg                   Standards Track                    [Page 16]

RFC 4825                          XCAP                          May 2007


   It is assumed that each application will have data that is set by
   users, and/or it will have global data that applies to all users.  As
   a result, beneath each AUID, there are two sub-trees.  One, called
   "users", holds the documents that are applicable to specific users,
   and the other, called "global", holds documents applicable to all
   users.  The sub-tree beneath "global" is called the global tree.  The
   path segment after the AUID MUST either be "global" or "users".

   Within the "users" tree are zero or more sub-trees, each of which
   identifies documents that apply to a specific user.  Each user known
   to the server is associated with a username, called the XCAP User
   Identifier (XUI).  Typically, an endpoint is provisioned with the
   value of the XUI.  For systems that support SIP applications, it is
   RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for
   the user (i.e., sip:[e-mail]).  Since SIP endpoints generally
   know their AOR, they will also know their XUI.  As a consequence, if
   no XUI is explicitly provisioned, a SIP User Agent SHOULD assume it
   is equal to their AOR.  This XUI MUST be used as the path segment
   beneath the "users" segment.  Since the SIP URI allows for characters
   that are not permitted in HTTP URI path segments (such as the '?' and
   '/' characters, which are permitted in the user part of the SIP URI),
   any such characters MUST be percent encoded.  The sub-tree beneath an
   XUI for a particular user is called their home directory.  "User" in
   this context should be interpreted loosely; a user might correspond
   to a device, for example.

   XCAP does not itself define what it means for documents to "apply" to
   a user, beyond specification of a baseline authorization policy,
   described below in Section 8.  Each application usage can specify
   additional authorization policies that depend on data used by the
   application itself.

   The remainder of the document selector (the path following "global"
   or the XUI) points to specific documents for that application usage.
   Subdirectories are permitted, but are NOT RECOMMENDED.  XCAP provides
   no way to create sub-directories or to list their contents, thus
   limiting their utility.  If subdirectories are used, there MUST NOT
   be a document in a directory with the same name as a sub-directory.

   The final path segment in the document selector identifies the actual
   document in the hierarchy.  This is equivalent to a filename, except
   that XCAP does not require that its document resources be stored as
   files in a file system.  However, the term "filename" is used to
   describe the final path segment in the document selector.  In
   traditional filesystems, the filename would have a filename
   extension, such as ".xml".  There is nothing in this specification
   that requires or prevents such extensions from being used in the
   filename.  In some cases, the application usage will specify a naming



Rosenberg                   Standards Track                    [Page 17]

RFC 4825                          XCAP                          May 2007


   convention for documents, and those naming conventions may or may not
   specify a file extension.  For example, in the RLS services
   application usage [22], documents in the user's home directory with
   the filename "index" will be used by the server to compute the global
   index, which is also a document with the filename "index".  Barring
   specific guidelines in the application usage, if a user has a single
   document for a particular application usage, this SHOULD be called
   "index".

   When the naming conventions in an application usage do not constrain
   the filename conventions (or, more generally, the document selector),
   an application will know the filename (or more generally, the
   document selector) because it is included as a reference in a
   document accessed by the client.  As another example, within the
   index document defined by RLS services, the <service> element has a
   child element called <resource-list> whose content is a URI pointing
   to a resource list within the users home directory.

   As a result, if the user creates a new document, and then references
   that document from a well-known document (such as the index document
   above), it doesn't matter whether or not the user includes an
   extension in the filename, as long as the user is consistent and
   maintains referential integrity.

   As an example, the path segment
   "/resource-lists/users/sip:[e-mail]/index" is a document
   selector.  Concatenating the XCAP root URI with the document selector
   produces the HTTP URI "http://xcap.example.com/resource-lists/users/
   sip:[e-mail]/index".  In this URI, the AUID is "resource-
   lists", and the document is in the user tree with the XUI
   "sip:[e-mail]" with filename "index".

6.3.  Node Selector

   The node selector specifies specific nodes of the XML document that
   are to be accessed.  A node refers to an XML element, an attribute of
   an element, or a set of namespace bindings.  The node selector is an
   expression that identifies an element, attribute, or set of namespace
   bindings.  Its grammar is:

   node-selector          = element-selector ["/" terminal-selector]
   terminal-selector      = attribute-selector / namespace-selector /
                            extension-selector
   element-selector       = step *( "/" step)
   step                   = by-name / by-pos / by-attr / by-pos-attr /
                            extension-selector
   by-name                = NameorAny
   by-pos                 = NameorAny "[" position "]"



Rosenberg                   Standards Track                    [Page 18]

RFC 4825                          XCAP                          May 2007


   position               = 1*DIGIT
   attr-test              = "@" att-name "=" att-value
   by-attr                = NameorAny "[" attr-test "]"
   by-pos-attr            = NameorAny "[" position "]" "[" attr-test "]"
   NameorAny              = QName / "*"   ; QName from XML Namespaces
   att-name               = QName
   att-value              = AttValue      ; from XML specification
   attribute-selector     = "@" att-name
   namespace-selector     = "namespace::*"
   extension-selector     = 1*( %x00-2e / %x30-ff )  ; anything but "/"

   The QName grammar is defined in the XML namespaces [3] specification,
   and the AttValue grammar is defined in the XML specification XML 1.0
   [1].

   The extension-selector is included for purposes of extensibility.  It
   can be composed of any character except the slash, which is the
   delimiter amongst steps.  Any characters in an extension that cannot
   be represented in a URI MUST be percent-encoded before placement into
   a URI.

   Note that the double quote, left square bracket and right square
   bracket characters, which are meaningful to XCAP, cannot be directly
   represented in the HTTP URI.  As a result, they are percent-encoded
   when placed within the HTTP URI.  In addition to these characters, an
   apostrophe (') character can be used as a delimiter within XPath
   expressions.  Furthermore, since XML allows for non-ASCII characters,
   the names of elements and attributes may not be directly
   representable in a URI.  Any such characters MUST be represented by
   converting them to an octet sequence corresponding to their
   representation in UTF-8, and then percent-encoding that sequence of
   octets.

   Similarly, the XML specification defines the QName production for the
   grammar for element and attribute names, and the AttValue production
   for the attribute values.  Unfortunately, the characters permitted by
   these productions include some that are not allowed for pchar, which
   is the production for the allowed set of characters in path segments
   in the URI.  The AttValue production allows many such characters
   within the US-ASCII set, including the space.  Those characters MUST
   be percent-encoded when placed in the URI.  Furthermore, QName and
   AttValue allow many Unicode characters, outside of US-ASCII.  When
   these characters need to be represented in the HTTP URI, they are
   percent-encoded.  To do this, the data should be encoded first as
   octets according to the UTF-8 character encoding [18], and then only
   those octets that do not correspond to characters in the pchar set
   should be percent-encoded.  For example, the character A would be
   represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE



Rosenberg                   Standards Track                    [Page 19]

RFC 4825                          XCAP                          May 2007


   would be represented as "%C3%80", and the character KATAKANA LETTER A
   would be represented as "%E3%82%A2".

   As a result, the grammar above represents the expressions processed
   by the XCAP server internally after it has decoded the URI.  The on-
   the-wire format is dictated by RFC 3986 [13].  In the discussions and
   examples below, when the node selectors are not part of an HTTP URI,
   they are presented in their internal format prior to encoding.  If an
   example includes a node selector within an HTTP URI, it is presented
   in its percent-encoded form.

   The node selector is based on the concepts in XPath [10].  Indeed,
   the node selector expression, before it is percent-encoded for
   representation in the HTTP URI, happens to be a valid XPath
   expression.  However, XPath provides a set of functionality far
   richer than is needed here, and its breadth would introduce much
   unneeded complexity into XCAP.

   To determine the XML element, attribute, or namespace bindings
   selected by the node selector, processing begins at the root node of
   the XML document.  The first step in the element selector is then
   taken.  Each step chooses a single XML element within the current
   document context.  The document context is the point within the XML
   document from which a specific step is evaluated.  The document
   context begins at the root node of the document.  When a step
   determines an element within that context, that element becomes the
   new context for evaluation of the next step.  Each step can select an
   element by its name (expanded), by a combination of name and
   attribute value, by name and position, or by name, position and
   attribute.  In all cases, the name can be wildcarded, so that all
   elements get selected.

   The selection operation operates as follows.  Within the current
   document context, the children of that context are enumerated in
   document order.  If the context is the root node of the document, its
   child element is the root element of the document.  If the context is
   an element, its children are all of the children of that element
   (naturally).  Next, those elements whose name is not a match for
   NameorAny are discarded.  An element name is a match if NameorAny is
   the wildcard, or if it is not a wildcard, the element name matches
   NameorAny.  Matching is discussed below.  The result is an ordered
   list of elements.

   The elements in the list are further filtered by the predicates,
   which are the expressions in square brackets following NameorAny.
   Each predicate further prunes the elements from the current ordered
   list.  These predicates are evaluated in order.  If the content of
   the predicate is a position, the position-th element is selected



Rosenberg                   Standards Track                    [Page 20]

RFC 4825                          XCAP                          May 2007


   (that is, treat "position" as a variable, and take the element whose
   position equals that variable), and all others are discarded.  If
   there are fewer elements in the list than the value of position, the
   result is a no-match.

   If the content of the predicate is an attribute name and value, all
   elements possessing an attribute with that name and value are
   selected, and all others are discarded.  Note that, although a
   document can have namespace declarations within elements, those
   elements cannot be selected using a namespace declaration as a
   predicate.  That is, a step like "el-name[@xmlns='namespace']" will
   never match an element, even if there is an element in the list that
   specifies a default namespace of "namespace".  In other words, a
   namespace node is NOT an attribute.  If the namespaces in scope for
   an element are needed, they can be selected using the namespace-
   selector described below.  If there are no elements with attributes
   having the given name and value, the result is a no-match.

   After the predicates have been applied, the result will be a
   no-match, one element, or multiple elements.  If the result is
   multiple elements, the node selector is invalid.  Each step in a node
   selector MUST produce a single element to form the context for the
   next step.  This is more restrictive than general XPath expressions,
   which allow a context to contain multiple nodes.  If the result is a
   no-match, the node selector is invalid.  The node selector is only
   valid if a single element was selected.  This element becomes the
   context for the evaluation of the next step in the node selector
   expression.

   The last location step is either the previously described element
   selector or a "terminal selector".  If the terminal selector is an
   attribute selector, the server checks to see if there is an attribute
   with the same expanded name in the current element context.  If there
   is not, the result is considered a no-match.  Otherwise, that
   attribute is selected.  If the terminal selector is a namespace
   selector, the result is equal to the set of namespace bindings in
   scope for the element, including the possible default namespace
   declaration.  This specification defines a syntax for representing
   namespace bindings, so they can be returned to the client in an HTTP
   response.

   As a result, once the entire node selector is evaluated against the
   document, the result will either be a no-