rfc2244.txt

RFC 的详细文档！

   The client is not required to wait for the completion result of a
   command before sending another command, subject to flow control
   constraints on the underlying data stream.  Similarly, a server is
   not required to process a command to completion before beginning
   processing of the next command, unless an ambiguity would result
   because of a command that would affect the results of other commands.
   If there is such an ambiguity, the server executes commands to
   completion in the order given by the client.

2.5.     Server Command Continuation Request

   The command continuation request is indicated by a "+" token instead
   of a tag.  This indicates that the server is ready to accept the
   continuation of a command from the client.

   This response is used in the AUTHENTICATE command to transmit server
   data to the client, and request additional client data.  This
   response is also used if an argument to any command is a
   synchronizing literal (see section 2.6.3).

   The client is not permitted to send the octets of a synchronizing
   literal unless the server indicates that it expects it.  This permits
   the server to process commands and reject errors on a line-by-line
   basis, assuming it checks for non-synchronizing literals at the end
   of each line.  The remainder of the command, including the CRLF that
   terminates a command, follows the octets of the literal.  If there
   are any additional command arguments the literal octets are followed
   by a space and those arguments.

   Example:    C: A099 FREECONTEXT {10}
               S: + "Ready for additional command text"
               C: FRED
               C: FOOB
               S: A099 OK "FREECONTEXT completed"
               C: A044 BLURDYBLOOP {102856}
               S: A044 BAD "No such command as 'BLURDYBLOOP'"


2.6.     Data Formats

   ACAP uses textual commands and responses.  Data in ACAP can be in one
   of five forms: atom, number, string, parenthesized list or NIL.







Newman & Myers              Standards Track                     [Page 8]

RFC 2244                          ACAP                     November 1997


2.6.1.   Atom

   An atom consists of one to 1024 non-special characters.  It must
   begin with a letter.  Atoms are used for protocol keywords.

2.6.2.   Number

   A number consists of one or more digit characters, and represents a
   numeric value.  Numbers are restricted to the range of an unsigned
   32-bit integer: 0 < number < 4,294,967,296.

2.6.3.   String

   A string is in one of two forms: literal and quoted string.  The
   literal form is the general form of string.  The quoted string form
   is an alternative that avoids the overhead of processing a literal at
   the cost of restrictions of what may be in a quoted string.

   A literal is a sequence of zero or more octets (including CR and LF),
   prefix-quoted with an octet count in the form of an open brace ("{"),
   the number of octets, close brace ("}"), and CRLF.  In the case of
   literals transmitted from server to client, the CRLF is immediately
   followed by the octet data.

   There are two forms of literals transmitted from client to server.
   The form where the open brace ("{") and number of octets is
   immediately followed by a close brace ("}") and CRLF is called a
   synchronizing literal.  When sending a synchronizing literal, the
   client must wait to receive a command continuation request before
   sending the octet data (and the remainder of the command).  The other
   form of literal, the non-synchronizing literal, is used to transmit a
   string from client to server without waiting for a command
   continuation request.  The non-synchronizing literal differs from the
   synchronizing literal by having a plus ("+") between the number of
   octets and the close brace ("}") and by having the octet data
   immediately following the CRLF.

   A quoted string is a sequence of zero to 1024 octets excluding NUL,
   CR and LF, with double quote (<">) characters at each end.

   The empty string is represented as "" (a quoted string with zero
   characters between double quotes), as {0} followed by CRLF (a
   synchronizing literal with an octet count of 0), or as {0+} followed
   by a CRLF (a non-synchronizing literal with an octet count of 0).

        Note: Even if the octet count is 0, a client transmitting a
        synchronizing literal must wait to receive a command
        continuation request.



Newman & Myers              Standards Track                     [Page 9]

RFC 2244                          ACAP                     November 1997


2.6.3.1. 8-bit and Binary Strings

   Most strings in ACAP are restricted to UTF-8 characters and may not
   contain NUL octets.  Attribute values MAY contain any octets
   including NUL.

2.6.4.   Parenthesized List

   Data structures are represented as a "parenthesized list"; a sequence
   of data items, delimited by space, and bounded at each end by
   parentheses.  A parenthesized list can contain other parenthesized
   lists, using multiple levels of parentheses to indicate nesting.

   The empty list is represented as () -- a parenthesized list with no
   members.

2.6.5.   NIL

   The special atom "NIL" represents the non-existence of a particular
   data item that is represented as a string or parenthesized list, as
   distinct from the empty string "" or the empty parenthesized list ().

3.       Protocol Elements

   This section defines data formats and other protocol elements used
   throughout the ACAP protocol.

3.1.     Entries and Attributes

   Within a dataset, each entry name is made up of zero or more UTF-8
   characters other than slash ("/").  A slash separated list of
   entries, one at each level of the hierarchy, forms the full path to
   an entry.

   Each entry is made up of a set of attributes.  Each attribute has a
   hierarchical name in UTF-8, with each component of the name separated
   by a period (".").

   The value of an attribute is either single or multi-valued.  A single
   value is NIL (has no value), or a string of zero or more octets.  A
   multi-value is a list of zero or more strings, each of zero or more
   octets.

   Attribute names are not permitted to contain asterisk ("*") or
   percent ("%") and MUST be valid UTF-8 strings which do not contain
   NUL.  Invalid attribute names result in a BAD response.  Entry names





Newman & Myers              Standards Track                    [Page 10]

RFC 2244                          ACAP                     November 1997


   are not permitted to begin with "." or contain slash ("/") and MUST
   be valid UTF-8 strings which do not contain NUL.  Invalid entry names
   in the entry field of a command result in a BAD response.

   Use of non-visible UTF-8 characters in attribute and entry names is
   discouraged.

3.1.1.   Predefined Attributes

   Attribute names which do not contain a dot (".") are reserved for
   standardized attributes which have meaning in any dataset.  The
   following attributes are defined by the ACAP protocol.

   entry
        Contains the name of the entry.  MUST be single valued.
        Attempts to use illegal or multi-valued values for the entry
        attribute are protocol errors and MUST result in a BAD
        completion response.  This is a special case.

   modtime
        Contains the date and time any read-write metadata in the entry
        was last modified.  This value MUST be in UTC, MUST be
        automatically updated by the server.

        The value consists of 14 or more US-ASCII digits.  The first
        four indicate the year, the next two indicate the month, the
        next two indicate the day of month, the next two indicate the
        hour (0 - 23), the next two indicate the minute, and the next
        two indicate the second.  Any further digits indicate fractions
        of a second.

        The time, particularly fractions of a second, need not be
        accurate.  It is REQUIRED, however, that any two entries in a
        dataset changed by successive modifications have strictly
        ascending modtime values.  In addition, each STORE command
        within a dataset (including simultaneous stores from different
        connections) MUST use different modtime values.

        This attribute has enforced validation, so any attempt to STORE
        a value in this attribute MAY result in a NO response with an
        INVALID response code.

   subdataset
        If this attribute is set, it indicates the existence of a sub-
        dataset of this entry.






Newman & Myers              Standards Track                    [Page 11]

RFC 2244                          ACAP                     November 1997


        The value consists of a list of relative ACAP URLs (see section
        3.2) which may be used to locate the sub-dataset.  The base URL
        is the full path to the entry followed by a slash ("/").  The
        value "." indicates a subdataset is located directly under this
        one.  Multiple values indicate replicated copies of the
        subdataset.

        For example, if the dataset "/folder/site/" has an entry
        "public-folder" with a subdataset attribute of ".", then there
        exists a dataset "/folder/site/public-folder/".  If the value of
        the subdataset attribute was instead
        "//other.acap.domain//folder/site/public-folder/", that would
        indicate the dataset is actually located on a different ACAP
        server.

        A dataset can be created by storing a "subdataset" attribute
        including ".", and a sub-hierarchy of datasets is deleted by
        storing a NIL value to the "subdataset" attribute on the entry
        in the parent dataset.

        This attribute has enforced syntax validation.  Specifically, if
        an attempt is made to STORE a non-list value (other than NIL),
        an empty list, or one of the values does not follow the URL
        syntax rules [BASIC-URL, REL-URL], then this will result in a NO
        response with an INVALID response code.

3.1.2.   Attribute Metadata

   Each attribute is made up of metadata items which describe that
   attribute, its value and any associated access controls.  Metadata
   items may be either read-only, in which case the client is never
   permitted to modify the item, or read-write, in which case the client
   may modify the item if the access control list (ACL) permits.

   The following metadata items are defined in this specification:

   acl    The access control list for the attribute, if one exists.  If
          the attribute does not have an ACL, NIL is returned.
          Read-write.  See section 3.5 for the contents of an ACL.

   attribute
          The attribute name.  Read-only.

   myrights
          The set of rights that the client has to the attribute.
          Read-only.  See section 3.5 for the possible rights.





Newman & Myers              Standards Track                    [Page 12]

RFC 2244                          ACAP                     November 1997


   size   This is the length of the value.  In the case of a
          multi-value, this is a list of lengths for each of the values.
          Read-only.

   value  The value.  For a multi-value, this is a list of single
          values.  Read-write.

   Additional items of metadata may be defined in extensions to this
   protocol.  Servers MUST respond to unrecognized metadata by returning
   a BAD command completion result.

3.2.     ACAP URL scheme

   ACAP URLs are used within the ACAP protocol for the "subdataset"
   attribute, referrals and inheritance.  They provide a convenient
   syntax for referring to other ACAP datasets.  The ACAP URL follows
   the common Internet scheme syntax as defined in [BASIC-URL] except
   that plaintext passwords are not permitted.  If :<port> is omitted,
   the port defaults to 674.

   An ACAP URL has the following general form:

   url-acap  = "acap://" url-server "/" url-enc-entry [url-filter]
               [url-extension]

   The <url-server> element includes the hostname, and optional user
   name, authentication mechanism and port number.  The <url-enc-entry>
   element contains the name of an entry path encoded according to the
   rules in [BASIC-URL].

   The <url-filter> element is an optional list of interesting attribute
   names.  If omitted, the URL refers to all attributes of the named