rfc3259.txt

RFC 的详细文档！

   indicate requirement levels for compliant Mbus implementations.

2.  Common Formal Syntax Rules

   This section contains definitions of common ABNF [13] syntax elements
   that are later referenced by other definitions in this document:

      base64          = base64_terminal /
                        ( 1*(4base64_CHAR) [base64_terminal] )

      base64_char     = UPALPHA / LOALPHA / DIGIT / "+" / "/"
                        ;; Case-sensitive

      base64_terminal = (2base64_char "==") / (3base64_char "=")

      UPALPHA         = %x41-5A            ;; Uppercase: A-Z




Ott, et. al.                 Informational                      [Page 6]

RFC 3259          A Message Bus for Local Coordination        April 2002


      LOALPHA         = %x61-7A            ;; Lowercase: a-z


      ALPHA           =  %x41-5A / %x61-7A   ; A-Z / a-z

      CHAR            =  %x01-7E
                         ; any 7-bit US-ASCII character,
                          excluding NUL and delete

      OCTET           =  %x00-FF
                         ; 8 bits of data

      CR              =  %x0D
                         ; carriage return

      CRLF            =  CR LF
                         ; Internet standard newline

      DIGIT           =  %x30-39
                         ; 0-9

      DQUOTE          =  %x22
                         ; " (Double Quote)

      HTAB            =  %x09
                         ; horizontal tab

      LF              =  %x0A
                         ; linefeed

      LWSP            =  *(WSP / CRLF WSP)
                         ; linear white space (past newline)

      SP              =  %x20
                         ; space

      WSP             =  SP / HTAB
                         ; white space

   Taken from RFC 2234 [13] and RFC 2554 [14].

3.  Message Format

   An Mbus message comprises a header and a body.  The header is used to
   indicate how and where a message should be delivered and the body
   provides information and commands to the destination entity.  The
   following pieces of information are included in the header:




Ott, et. al.                 Informational                      [Page 7]

RFC 3259          A Message Bus for Local Coordination        April 2002


      A fixed ProtocolID field identifies the version of the message bus
      protocol used.  The protocol defined in this document is
      "mbus/1.0" (case-sensitive).

      A sequence number (SeqNum) is contained in each message.  The
      first message sent by a source SHOULD set SeqNum to zero, and it
      MUST increment by one for each message sent by that source.  A
      single sequence number is used for all messages from a source,
      irrespective of the intended recipients and the reliability mode
      selected. The value range of a sequence number is (0,4294967295).
      An implementation MUST re-set its sequence number to 0 after
      reaching 4294967295.  Implementations MUST take into account that
      the SeqNum of other entities may wrap-around.

      SeqNums are decimal numbers in ASCII representation.

      The TimeStamp field is also contained in each message and SHOULD
      contain a decimal number representing the time of the message
      construction in milliseconds since 00:00:00, UTC, January 1, 1970.

      A MessageType field indicates the kind of message being sent.  The
      value "R" indicates that the message is to be transmitted reliably
      and MUST be acknowledged by the recipient, "U" indicates an
      unreliable message which MUST NOT be acknowledged.

      The SrcAddr field identifies the sender of a message.  This MUST
      be a complete address, with all address elements specified.  The
      addressing scheme is described in Section 4.

      The DestAddr field identifies the intended recipient(s) of the
      message.  This field MAY be wildcarded by omitting address
      elements and hence address any number (including zero) of
      application entities.  The addressing scheme is described in
      Section 4.

      The AckList field comprises a list of SeqNums for which this
      message is an acknowledgment.  See Section 7 for details.

   The header is followed by the message body which contains zero or
   more commands to be delivered to the destination entity.  The syntax
   for a complete message is given in Section 5.

   If multiple commands are contained within the same Mbus message
   payload, they MUST to be delivered to the Mbus application in the
   same sequence in which they appear in the message payload.






Ott, et. al.                 Informational                      [Page 8]

RFC 3259          A Message Bus for Local Coordination        April 2002


4.  Addressing

   Each entity in the message has a unique Mbus address that is used to
   identify the entity.  Mbus addresses are sequences of address
   elements that are tag/value pairs.  The tag and the value are
   separated by a colon and tag/value pairs are separated by whitespace,
   like this:

      (tag:value tag:value ...)

   The formal ABNF syntax definition for Mbus addresses and their
   elements is as follows:

      mbus_address    = "(" *WSP *1address_list *WSP ")"
      address_list    = address_element
                      / address_element 1*WSP address_list

      address_element = address_tag ":" address_value

      address_tag     = 1*32(ALPHA)

      address_value   = 1*64(%x21-27 / %x2A-7E)
                        ; any 7-bit US-ASCII character
                        ; excluding white space, delete,
                        ; control characters, "(" and ")"

   Note that this and other ABNF definitions in this document use the
   non-terminal symbols defined in Section 2.

   An address_tag MUST be unique within an Mbus address, i.e., it MUST
   only occur once.

   Each entity has a fixed sequence of address elements constituting its
   address and MUST only process messages sent to addresses that either
   match all elements or consist of a subset of its own address
   elements.  The order of address elements in an address sequence is
   not relevant.  Two address elements match if both their tags and
   their values are equivalent.  Equivalence for address element and
   address value strings means that each octet in the one string has the
   same value as the corresponding octet in the second string.  For
   example, an entity with an address of:

   (conf:test media:audio module:engine app:rat id:4711-1@192.168.1.1)

   will process messages sent to

   (media:audio module:engine)




Ott, et. al.                 Informational                      [Page 9]

RFC 3259          A Message Bus for Local Coordination        April 2002


   and

   (module:engine)

   but must ignore messages sent to

   (conf:test media:audio module:engine app:rat id:123-4@192.168.1.1
   foo:bar)

   and

   (foo:bar)

   A message that should be processed by all entities requires an empty
   set of address elements.

4.1  Mandatory Address Elements

   Each Mbus entity MUST provide one mandatory address element that
   allows it to identify the entity.  The element tag is "id" and the
   value MUST be be composed of the following components:

   o  The IP address of the interface that is used for sending messages
      to the Mbus.  For IPv4 this is the address in dotted decimal
      notation.  For IPv6 the interface-ID-part of the node's link-local
      address in textual representation as specified in RFC 2373 [3]
      MUST be used.

      In this specification, this part is called the "host-ID".

   o  An identifier ("entity-ID") that is unique within the scope of a
      single host-ID.  The entity comprises two parts.  For systems
      where the concept of a process ID is applicable it is RECOMMENDED
      that this identifier be composed using a process-ID and a per-
      process disambiguator for different Mbus entities of a process.
      If a process ID is not available, this part of the entity-ID may
      be randomly chosen (it is recommended that at least a 32 bit
      random number is chosen).  Both numbers are represented in decimal
      textual form and MUST be separated by a '-' (ASCII x2d) character.

   Note that the entity-ID cannot be the port number of the endpoint
   used for sending messages to the Mbus because implementations MAY use
   the common Mbus port number for sending to and receiving from the
   multicast group (as specified in Section 6).

   The complete syntax definition for the entity identifier is as
   follows:




Ott, et. al.                 Informational                     [Page 10]

RFC 3259          A Message Bus for Local Coordination        April 2002


      id-element   = "id:" id-value

      id-value     = entity-id "@" host-id

      entity-id    = 1*10DIGIT "-" 1*5DIGIT

      host-id      = (IPv4address / IPv6address)

   Please refer to [3] for the productions of IPv4address and IPv6address.

   An example for an id element:

      id:4711-99@192.168.1.1

5.  Message Syntax

5.1  Message Encoding

   All messages MUST use the UTF-8 character encoding.  Note that US
   ASCII is a subset of UTF-8 and requires no additional encoding, and
   that a message encoded with UTF-8 will not contain zero bytes.

   Each Message MAY be encrypted using a secret key algorithm as
   defined in Section 11.

5.2  Message Header

   The fields in the header are separated by white space characters,
   and followed by CRLF.  The format of the header is as follows:

   msg_header = "mbus/1.0" 1*WSP SeqNum 1*WSP TimeStamp 1*WSP
                MessageType 1*WSP SrcAddr 1*WSP DestAddr 1*WSP AckList

   The header fields are explained in Message Format (Section 3).  Here
   are the ABNF syntax definitions for the header fields:

      SeqNum      = 1*10DIGIT     ; numeric range 0 - 2^32-1

      TimeStamp   = 1*13DIGIT

      MessageType = "R" / "U"

      ScrAddr     = mbus_address

      DestAddr    = mbus_address






Ott, et. al.                 Informational                     [Page 11]

RFC 3259          A Message Bus for Local Coordination        April 2002


      AckList     = "(" *WSP *1(1*DIGIT *(1*WSP 1*10DIGIT)) *WSP ")"

      See Section 4 for a definition of "mbus_address".

   The syntax definition of a complete message is as follows:

      mbus_message = msg_header *1(CRLF msg_payload)

      msg_payload  = mbus_command *(CRLF mbus_command)

   The definition of production rules for an Mbus command is given in
   Section 5.3.