Google Git
Sign in
apache / qpid / ebfd9ff053b04ab379acfc0fefedee5a31b6d8a5 / . / ruby / lib / qpid / specs / amqp.0-10-qpid-errata.xml
blob: 365928ea4e357bfc85cacbfc900f8fd2199025dc [file] [log] [blame]
<?xml version="1.0"?>
<!--
Copyright Notice
================
(c) Copyright Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,
Goldman Sachs, IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A,
Novell, Rabbit Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc.
2006, 2007. All rights reserved.
License
=======
Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,Goldman Sachs,
IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A, Novell, Rabbit
Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc. (collectively,
the "Authors") each hereby grants to you a worldwide, perpetual, royalty-free, nontransferable,
nonexclusive license to (i) copy, display, distribute and implement the Advanced Messaging Queue
Protocol ("AMQP") Specification and (ii) the Licensed Claims that are held by the Authors, all for
the purpose of implementing the Advanced Messaging Queue Protocol Specification. Your license and
any rights under this Agreement will terminate immediately without notice from any Author if you
bring any claim, suit, demand, or action related to the Advanced Messaging Queue Protocol
Specification against any Author. Upon termination, you shall destroy all copies of the Advanced
Messaging Queue Protocol Specification in your possession or control.
As used hereunder, "Licensed Claims" means those claims of a patent or patent application,
throughout the world, excluding design patents and design registrations, owned or controlled, or
that can be sublicensed without fee and in compliance with the requirements of this Agreement, by
an Author or its affiliates now or at any future time and which would necessarily be infringed by
implementation of the Advanced Messaging Queue Protocol Specification. A claim is necessarily
infringed hereunder only when it is not possible to avoid infringing it because there is no
plausible non-infringing alternative for implementing the required portions of the Advanced
Messaging Queue Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not
include any claims other than as set forth above even if contained in the same patent as Licensed
Claims; or that read solely on any implementations of any portion of the Advanced Messaging Queue
Protocol Specification that are not required by the Advanced Messaging Queue Protocol
Specification, or that, if licensed, would require a payment of royalties by the licensor to
unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling
technologies that may be necessary to make or use any Licensed Product but are not themselves
expressly set forth in the Advanced Messaging Queue Protocol Specification (e.g., semiconductor
manufacturing technology, compiler technology, object oriented technology, networking technology,
operating system technology, and the like); or (ii) the implementation of other published
standards developed elsewhere and merely referred to in the body of the Advanced Messaging Queue
Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or
function of which is not required for compliance with the Advanced Messaging Queue Protocol
Specification. For purposes of this definition, the Advanced Messaging Queue Protocol
Specification shall be deemed to include both architectural and interconnection requirements
essential for interoperability and may also include supporting source code artifacts where such
architectural, interconnection requirements and source code artifacts are expressly identified as
being required or documentation to achieve compliance with the Advanced Messaging Queue Protocol
Specification.
As used hereunder, "Licensed Products" means only those specific portions of products (hardware,
software or combinations thereof) that implement and are compliant with all relevant portions of
the Advanced Messaging Queue Protocol Specification.
The following disclaimers, which you hereby also acknowledge as to any use you may make of the
Advanced Messaging Queue Protocol Specification:
THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO
REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS
OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
IMPLEMENTATION OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD
PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED
MESSAGING QUEUE PROTOCOL SPECIFICATION.
The name and trademarks of the Authors may NOT be used in any manner, including advertising or
publicity pertaining to the Advanced Messaging Queue Protocol Specification or its contents
without specific, written prior permission. Title to copyright in the Advanced Messaging Queue
Protocol Specification will at all times remain with the Authors.
No other rights are granted by implication, estoppel or otherwise.
Upon termination of your license or rights under this Agreement, you shall destroy all copies of
the Advanced Messaging Queue Protocol Specification in your possession or control.
Trademarks
==========
"JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are
trademarks of JPMorgan Chase & Co.
IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
IONA, IONA Technologies, and the IONA logos are trademarks of IONA Technologies PLC and/or its
subsidiaries.
LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered trademarks of Red Hat,
Inc. in the US and other countries.
Java, all Java-based trademarks and OpenOffice.org are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
Links to full AMQP specification:
=================================
http://www.envoytech.org/spec/amq/
http://www.iona.com/opensource/amqp/
http://www.redhat.com/solutions/specifications/amqp/
http://www.twiststandards.org/tiki-index.php?page=AMQ
http://www.imatix.com/amqp
-->
<!--
XML Notes
=========
We use entities to indicate repetition; attributes to indicate properties.
We use the "name" attribute as an identifier, usually within the context of the surrounding
entities.
We use hyphens (minus char '-') to seperate words in names.
We do not enforce any particular validation mechanism but we support all mechanisms. The protocol
definition conforms to a formal grammar that is published seperately in several technologies.
-->
<!DOCTYPE amqp SYSTEM "amqp.0-10.dtd">
<amqp xmlns="http://www.amqp.org/schema/amqp.xsd"
major="0" minor="10" port="5672">
<!--
====================== == type definitions == ======================
-->
<!--
0x00 - 0x0f: Fixed width, 1 octet
-->
<type name="bin8" code="0x00" fixed-width="1" label="octet of unspecified encoding">
<doc>
The bin8 type consists of exactly one octet of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET
+----------+
| bin8 |
+----------+
</doc>
<doc type="bnf">
bin8 = OCTET
</doc>
</type>
<type name="int8" code="0x01" fixed-width="1" label="8-bit signed integral value (-128 - 127)">
<doc>
The int8 type is a signed integral value encoded using an 8-bit two's complement
representation.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET
+----------+
| int8 |
+----------+
</doc>
<doc type="bnf">
int8 = OCTET
</doc>
</type>
<type name="uint8" code="0x02" fixed-width="1" label="8-bit unsigned integral value (0 - 255)">
<doc>
The uint8 type is an 8-bit unsigned integral value.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET
+---------+
| uint8 |
+---------+
</doc>
<doc type="bnf">
uint8 = OCTET
</doc>
</type>
<type name="char" code="0x04" fixed-width="1" label="an iso-8859-15 character">
<doc>
The char type encodes a single character from the iso-8859-15 character set.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET
+----------+
| char |
+----------+
</doc>
<doc type="bnf">
char = OCTET
</doc>
</type>
<type name="boolean" code="0x08" fixed-width="1"
label="boolean value (zero represents false, nonzero represents true)">
<doc>
The boolean type is a single octet that encodes a true or false value. If the octet is zero,
then the boolean is false. Any other value represents true.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET
+---------+
| boolean |
+---------+
</doc>
<doc type="bnf">
boolean = OCTET
</doc>
</type>
<!--
0x10 - 0x1f: Fixed width, 2 octets
-->
<type name="bin16" code="0x10" fixed-width="2" label="two octets of unspecified binary encoding">
<doc>
The bin16 type consists of two consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET
+-----------+-----------+
| octet-one | octet-two |
+-----------+-----------+
</doc>
<doc type="bnf">
bin16 = 2 OCTET
</doc>
</type>
<type name="int16" code="0x11" fixed-width="2" label="16-bit signed integral value">
<doc>
The int16 type is a signed integral value encoded using a 16-bit two's complement
representation in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET
+-----------+----------+
| high-byte | low-byte |
+-----------+----------+
</doc>
<doc type="bnf">
int16 = high-byte low-byte
high-byte = OCTET
low-byte = OCTET
</doc>
</type>
<type name="uint16" code="0x12" fixed-width="2" label="16-bit unsigned integer">
<doc>
The uint16 type is a 16-bit unsigned integral value encoded in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET
+-----------+----------+
| high-byte | low-byte |
+-----------+----------+
</doc>
<doc type="bnf">
uint16 = high-byte low-byte
high-byte = OCTET
low-byte = OCTET
</doc>
</type>
<!--
0x20 - 0x2f: Fixed width, 4 octets
-->
<type name="bin32" code="0x20" fixed-width="4" label="four octets of unspecified binary encoding">
<doc>
The bin32 type consists of 4 consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-------------+------------+
| octet-one | octet-two | octet-three | octet-four |
+-----------+-----------+-------------+------------+
</doc>
<doc type="bnf">
bin32 = 4 OCTET
</doc>
</type>
<type name="int32" code="0x21" fixed-width="4" label="32-bit signed integral value">
<doc>
The int32 type is a signed integral value encoded using a 32-bit two's complement
representation in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+------------+----------+----------+
| byte-four | byte-three | byte-two | byte-one |
+-----------+------------+----------+----------+
MSB LSB
</doc>
<doc type="bnf">
int32 = byte-four byte-three byte-two byte-one
byte-four = OCTET ; most significant byte (MSB)
byte-three = OCTET
byte-two = OCTET
byte-one = OCTET ; least significant byte (LSB)
</doc>
</type>
<type name="uint32" code="0x22" fixed-width="4" label="32-bit unsigned integral value">
<doc>
The uint32 type is a 32-bit unsigned integral value encoded in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+------------+----------+----------+
| byte-four | byte-three | byte-two | byte-one |
+-----------+------------+----------+----------+
MSB LSB
</doc>
<doc type="bnf">
uint32 = byte-four byte-three byte-two byte-one
byte-four = OCTET ; most significant byte (MSB)
byte-three = OCTET
byte-two = OCTET
byte-one = OCTET ; least significant byte (LSB)
</doc>
</type>
<type name="float" code="0x23" fixed-width="4"
label="single precision IEEE 754 32-bit floating point">
<doc>
The float type encodes a single precision 32-bit floating point number. The format and
operations are defined by the IEEE 754 standard for 32-bit floating point numbers.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs
+-----------------------+
| float |
+-----------------------+
IEEE 754 32-bit float
</doc>
<doc type="bnf">
float = 4 OCTET ; IEEE 754 32-bit floating point number
</doc>
</type>
<type name="char-utf32" code="0x27" fixed-width="4"
label="single unicode character in UTF-32 encoding">
<doc>
The char-utf32 type consists of a single unicode character in the UTF-32 encoding.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs
+------------------+
| char-utf32 |
+------------------+
UTF-32 character
</doc>
<doc type="bnf">
char-utf32 = 4 OCTET ; single UTF-32 character
</doc>
</type>
<type name="sequence-no" fixed-width="4" label="serial number defined in RFC-1982">
<doc>
The sequence-no type encodes, in network byte order, a serial number as defined in RFC-1982.
The arithmetic, operators, and ranges for numbers of this type are defined by RFC-1982.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs
+------------------------+
| sequence-no |
+------------------------+
RFC-1982 serial number
</doc>
<doc type="bnf">
sequence-no = 4 OCTET ; RFC-1982 serial number
</doc>
</type>
<!--
0x30 - 0x3f: Fixed width types - 8 octets
-->
<type name="bin64" code="0x30" fixed-width="8"
label="eight octets of unspecified binary encoding">
<doc>
The bin64 type consists of eight consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+-------------+-------------+
| octet-one | octet-two | ... | octet-seven | octet-eight |
+-----------+-----------+-----+-------------+-------------+
</doc>
<doc type="bnf">
bin64 = 8 OCTET
</doc>
</type>
<type name="int64" code="0x31" fixed-width="8" label="64-bit signed integral value">
<doc>
The int64 type is a signed integral value encoded using a 64-bit two's complement
representation in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+------------+------------+-----+----------+----------+
| byte-eight | byte-seven | ... | byte-two | byte-one |
+------------+------------+-----+----------+----------+
MSB LSB
</doc>
<doc type="bnf">
int64 = byte-eight byte-seven byte-six byte-five
byte-four byte-three byte-two byte-one
byte-eight = 1 OCTET ; most significant byte (MSB)
byte-seven = 1 OCTET
byte-six = 1 OCTET
byte-five = 1 OCTET
byte-four = 1 OCTET
byte-three = 1 OCTET
byte-two = 1 OCTET
byte-one = 1 OCTET ; least significant byte (LSB)
</doc>
</type>
<type name="uint64" code="0x32" fixed-width="8" label="64-bit unsigned integral value">
<doc>
The uint64 type is a 64-bit unsigned integral value encoded in network byte order.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+------------+------------+-----+----------+----------+
| byte-eight | byte-seven | ... | byte-two | byte-one |
+------------+------------+-----+----------+----------+
MSB LSB
</doc>
<doc type="bnf">
uint64 = byte-eight byte-seven byte-six byte-five
byte-four byte-three byte-two byte-one
byte-eight = 1 OCTET ; most significant byte (MSB)
byte-seven = 1 OCTET
byte-six = 1 OCTET
byte-five = 1 OCTET
byte-four = 1 OCTET
byte-three = 1 OCTET
byte-two = 1 OCTET
byte-one = 1 OCTET ; least significant byte (LSB)
</doc>
</type>
<type name="double" code="0x33" fixed-width="8" label="double precision IEEE 754 floating point">
<doc>
The double type encodes a double precision 64-bit floating point number. The format and
operations are defined by the IEEE 754 standard for 64-bit double precision floating point
numbers.
</doc>
<doc type="picture" title="Wire Format">
8 OCTETs
+-----------------------+
| double |
+-----------------------+
IEEE 754 64-bit float
</doc>
<doc type="bnf">
double = 8 OCTET ; double precision IEEE 754 floating point number
</doc>
</type>
<type name="datetime" code="0x38" fixed-width="8" label="datetime in 64 bit POSIX time_t format">
<doc>
The datetime type encodes a date and time using the 64 bit POSIX time_t format.
</doc>
<doc type="picture" title="Wire Format">
8 OCTETs
+---------------------+
| datetime |
+---------------------+
posix time_t format
</doc>
<doc type="bnf">
datetime = 8 OCTET ; 64 bit posix time_t format
</doc>
</type>
<!--
0x40 - 0x4f: Fixed width types - 16 octets
-->
<type name="bin128" code="0x40" fixed-width="16"
label="sixteen octets of unspecified binary encoding">
<doc>
The bin128 type consists of 16 consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+---------------+---------------+
| octet-one | octet-two | ... | octet-fifteen | octet-sixteen |
+-----------+-----------+-----+---------------+---------------+
</doc>
<doc type="bnf">
bin128 = 16 OCTET
</doc>
</type>
<type name="uuid" code="0x48" fixed-width="16" label="UUID (RFC-4122 section 4.1.2) - 16 octets">
<doc>
The uuid type encodes a universally unique id as defined by RFC-4122. The format and
operations for this type can be found in section 4.1.2 of RFC-4122.
</doc>
<doc type="picture" title="Wire Format">
16 OCTETs
+---------------+
| uuid |
+---------------+
RFC-4122 UUID
</doc>
<doc type="bnf">
uuid = 16 OCTET ; RFC-4122 section 4.1.2
</doc>
</type>
<!--
0x50 - 0x5f: Fixed width types - 32 octets
-->
<type name="bin256" code="0x50" fixed-width="32"
label="thirty two octets of unspecified binary encoding">
<doc>
The bin256 type consists of thirty two consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+------------------+------------------+
| octet-one | octet-two | ... | octet-thirty-one | octet-thirty-two |
+-----------+-----------+-----+------------------+------------------+
</doc>
<doc type="bnf">
bin256 = 32 OCTET
</doc>
</type>
<!--
0x60 - 0x6f: Fixed width types - 64 octets
-->
<type name="bin512" code="0x60" fixed-width="64"
label="sixty four octets of unspecified binary encoding">
<doc>
The bin512 type consists of sixty four consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+-------------------+------------------+
| octet-one | octet-two | ... | octet-sixty-three | octet-sixty-four |
+-----------+-----------+-----+-------------------+------------------+
</doc>
<doc type="bnf">
bin512 = 64 OCTET
</doc>
</type>
<!--
0x70 - 0x7f: Fixed width types - 128 octets
-->
<type name="bin1024" code="0x70" fixed-width="128"
label="one hundred and twenty eight octets of unspecified binary encoding">
<doc>
The bin1024 type consists of one hundred and twenty eight octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+------------------------+------------------------+
| octet-one | octet-two | ... | octet-one-twenty-seven | octet-one-twenty-eight |
+-----------+-----------+-----+------------------------+------------------------+
</doc>
<doc type="bnf">
bin1024 = 128 OCTET
</doc>
</type>
<!--
0x80 - 0x8f: Variable length - one byte length field (up to 255 octets)
-->
<type name="vbin8" code="0x80" variable-width="1" label="up to 255 octets of opaque binary data">
<doc>
The vbin8 type encodes up to 255 octets of opaque binary data. The number of octets is first
encoded as an 8-bit unsigned integral value. This is followed by the actual data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET size OCTETs
+---------+-------------+
| size | octets |
+---------+-------------+
uint8
</doc>
<doc type="bnf">
vbin8 = size octets
size = uint8
octets = 0*255 OCTET ; size OCTETs
</doc>
</type>
<type name="str8-latin" code="0x84" variable-width="1" label="up to 255 iso-8859-15 characters">
<doc>
The str8-latin type encodes up to 255 octets of iso-8859-15 characters. The number of octets
is first encoded as an 8-bit unsigned integral value. This is followed by the actual
characters.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET size OCTETs
+---------+------------------------+
| size | characters |
+---------+------------------------+
uint16 iso-8859-15 characters
</doc>
<doc type="bnf">
str8-latin = size characters
size = uint8
characters = 0*255 OCTET ; size OCTETs
</doc>
</type>
<type name="str8" code="0x85" variable-width="1" label="up to 255 octets worth of UTF-8 unicode">
<doc>
The str8 type encodes up to 255 octets worth of UTF-8 unicode. The number of octets of unicode
is first encoded as an 8-bit unsigned integral value. This is followed by the actual UTF-8
unicode. Note that the encoded size refers to the number of octets of unicode, not necessarily
the number of characters since the UTF-8 unicode may include multi-byte character sequences.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET size OCTETs
+---------+--------------+
| size | utf8-unicode |
+---------+--------------+
uint8
</doc>
<doc type="bnf">
str8 = size utf8-unicode
size = uint8
utf8-unicode = 0*255 OCTET ; size OCTETs
</doc>
</type>
<type name="str8-utf16" code="0x86" variable-width="1"
label="up to 255 octets worth of UTF-16 unicode">
<doc>
The str8-utf16 type encodes up to 255 octets worth of UTF-16 unicode. The number of octets of
unicode is first encoded as an 8-bit unsigned integral value. This is followed by the actual
UTF-16 unicode. Note that the encoded size refers to the number of octets of unicode, not the
number of characters since the UTF-16 unicode will include at least two octets per unicode
character.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET size OCTETs
+---------+---------------+
| size | utf16-unicode |
+---------+---------------+
uint8
</doc>
<doc type="bnf">
str8-utf16 = size utf16-unicode
size = uint8
utf16-unicode = 0*255 OCTET ; size OCTETs
</doc>
</type>
<!--
0x90 - 0x9f: Variable length types - two byte length field (up to 65535 octets)
-->
<type name="vbin16" code="0x90" variable-width="2"
label="up to 65535 octets of opaque binary data">
<doc>
The vbin16 type encodes up to 65535 octets of opaque binary data. The number of octets is
first encoded as a 16-bit unsigned integral value in network byte order. This is followed by
the actual data.
</doc>
<doc type="picture" title="Wire Format">
2 OCTETs size OCTETs
+----------+-------------+
| size | octets |
+----------+-------------+
uint16
</doc>
<doc type="bnf">
vbin16 = size octets
size = uint16
octets = 0*65535 OCTET ; size OCTETs
</doc>
</type>
<type name="str16-latin" code="0x94" variable-width="2"
label="up to 65535 iso-8859-15 characters">
<doc>
The str16-latin type encodes up to 65535 octets of is-8859-15 characters. The number of octets
is first encoded as a 16-bit unsigned integral value in network byte order. This is followed
by the actual characters.
</doc>
<doc type="picture" title="Wire Format">
2 OCTETs size OCTETs
+----------+------------------------+
| size | characters |
+----------+------------------------+
uint16 iso-8859-15 characters
</doc>
<doc type="bnf">
str16-latin = size characters
size = uint16
characters = 0*65535 OCTET ; size OCTETs
</doc>
</type>
<type name="str16" code="0x95" variable-width="2"
label="up to 65535 octets worth of UTF-8 unicode">
<doc>
The str16 type encodes up to 65535 octets worth of UTF-8 unicode. The number of octets is
first encoded as a 16-bit unsigned integral value in network byte order. This is followed by
the actual UTF-8 unicode. Note that the encoded size refers to the number of octets of
unicode, not necessarily the number of unicode characters since the UTF-8 unicode may include
multi-byte character sequences.
</doc>
<doc type="picture" title="Wire Format">
2 OCTETs size OCTETs
+----------+--------------+
| size | utf8-unicode |
+----------+--------------+
uint16
</doc>
<doc type="bnf">
str16 = size utf8-unicode
size = uint16
utf8-unicode = 0*65535 OCTET ; size OCTETs
</doc>
</type>
<type name="str16-utf16" code="0x96" variable-width="2"
label="up to 65535 octets worth of UTF-16 unicode">
<doc>
The str16-utf16 type encodes up to 65535 octets worth of UTF-16 unicode. The number of octets
is first encoded as a 16-bit unsigned integral value in network byte order. This is followed
by the actual UTF-16 unicode. Note that the encoded size refers to the number of octets of
unicode, not the number of unicode characters since the UTF-16 unicode will include at least
two octets per unicode character.
</doc>
<doc type="picture" title="Wire Format">
2 OCTETs size OCTETs
+----------+---------------+
| size | utf16-unicode |
+----------+---------------+
uint16
</doc>
<doc type="bnf">
str16-utf16 = size utf16-unicode
size = uint16
utf16-unicode = 0*65535 OCTET ; size OCTETs
</doc>
</type>
<type name="byte-ranges" variable-width="2" label="byte ranges within a 64-bit payload">
<doc>
The byte-ranges type encodes up to 65535 octets worth of non-overlapping, non-touching,
ascending byte ranges within a 64-bit sequence of bytes. Each range is represented as an
inclusive lower and upper bound that identifies all the byte offsets included within a given
range.
</doc>
<doc>
The number of octets of data is first encoded as a 16-bit unsigned integral value in network
byte order. This is then followed by the encoded representation of the ranges included in the
set. These MUST be encoded in ascending order, and any two ranges included in a given set MUST
NOT include overlapping or touching byte offsets.
</doc>
<doc>
Each range is encoded as a pair of 64-bit unsigned integral values in network byte order
respectively representing the lower and upper bounds for that range. Note that because each
range is exactly 16 octets, the size in octets of the encoded ranges will always be 16 times
the number of ranges in the set.
</doc>
<doc type="picture" title="Wire Format">
+----= size OCTETs =----+
| |
2 OCTETs | 16 OCTETs |
+----------+-----+-----------+-----+
| size | .../| range |\... |
+----------+---/ +-----------+ \---+
uint16 / / \ \
/ / \ \
/ 8 OCTETs 8 OCTETs \
+-----------+-----------+
| lower | upper |
+-----------+-----------+
uint64 uint64
</doc>
<doc type="bnf">
byte-ranges = size *range
size = uint16
range = lower upper
lower = uint64
upper = uint64
</doc>
</type>
<type name="sequence-set" variable-width="2" label="ranged set representation">
<doc>
The sequence-set type is a set of pairs of RFC-1982 numbers representing a discontinuous range
within an RFC-1982 sequence. Each pair represents a closed interval within the list.
</doc>
<doc>
Sequence-sets can be represented as lists of pairs of positive 32-bit numbers, each pair
representing a closed interval that does not overlap or touch with any other interval in the
list. For example, a set containing words 0, 1, 2, 5, 6, and 15 can be represented:
</doc>
<doc type="picture">
[(0, 2), (5, 6), (15, 15)]
</doc>
<doc>
1) The list-of-pairs representation is sorted ascending (as defined by RFC 1982
(http://www.ietf.org/rfc/rfc1982.txt) ) by the first elements of each pair.
</doc>
<doc>
2) The list-of-pairs is flattened into a list-of-words.
</doc>
<doc>
3) Each word in the list is packed into ascending locations in memory with network byte
ordering.
</doc>
<doc>
4) The size in bytes, represented as a 16-bit network-byte-order unsigned value, is prepended.
</doc>
<doc>
For instance, the example from above would be encoded:
</doc>
<doc type="picture">
[(0, 2), (5, 6), (15, 15)] -- already sorted.
[0, 2, 5, 6, 15, 15] -- flattened.
000000000000000200000005000000060000000F0000000F -- bytes in hex
0018000000000000000200000005000000060000000F0000000F -- bytes in hex,
length (24) prepended
</doc>
<doc type="picture" title="Wire Format">
+----= size OCTETs =----+
| |
2 OCTETs | 8 OCTETs |
+----------+-----+-----------+-----+
| size | .../| range |\... |
+----------+---/ +-----------+ \---+
uint16 / / \ \
/ / \ \
/ / \ \
/ / \ \
/ 4 OCTETs 4 OCTETs \
+-------------+-------------+
| lower | upper |
+-------------+-------------+
sequence-no sequence-no
</doc>
<doc type="bnf">
sequence-set = size *range
size = uint16 ; length of variable portion in bytes
range = lower upper ; inclusive
lower = sequence-no
upper = sequence-no
</doc>
</type>
<!--
0xa0 - 0xaf: Variable length types - four byte length field (up to 4294967295 octets)
-->
<type name="vbin32" code="0xa0" variable-width="4"
label="up to 4294967295 octets of opaque binary data">
<doc>
The vbin32 type encodes up to 4294967295 octets of opaque binary data. The number of octets is
first encoded as a 32-bit unsigned integral value in network byte order. This is followed by
the actual data.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs size OCTETs
+----------+-------------+
| size | octets |
+----------+-------------+
uint32
</doc>
<doc type="bnf">
vbin32 = size octets
size = uint32
octets = 0*4294967295 OCTET ; size OCTETs
</doc>
</type>
<type name="map" code="0xa8" variable-width="4" label="a mapping of keys to typed values">
<doc>
A map is a set of distinct keys where each key has an associated (type,value) pair. The triple
of the key, type, and value, form an entry within a map. Each entry within a given map MUST
have a distinct key. A map is encoded as a size in octets, a count of the number of entries,
followed by the encoded entries themselves.
</doc>
<doc>
An encoded map may contain up to (4294967295 - 4) octets worth of encoded entries. The size is
encoded as a 32-bit unsigned integral value in network byte order equal to the number of
octets worth of encoded entries plus 4. (The extra 4 octets is added for the entry count.) The
size is then followed by the number of entries encoded as a 32-bit unsigned integral value in
network byte order. Finally the entries are encoded sequentially.
</doc>
<doc>
An entry is encoded as the key, followed by the type, and then the value. The key is always a
string encoded as a str8. The type is a single octet that may contain any valid AMQP type
code. The value is encoded according to the rules defined by the type code for that entry.
</doc>
<doc type="picture" title="Wire Format">
+------------= size OCTETs =-----------+
| |
4 OCTETs | 4 OCTETs |
+----------+----------+-----+---------------+-----+
| size | count | .../| entry |\... |
+----------+----------+---/ +---------------+ \---+
uint32 uint32 / / \ \
/ / \ \
/ / \ \
/ / \ \
/ / \ \
/ k OCTETs 1 OCTET n OCTETs \
+-----------+---------+-----------+
| key | type | value |
+-----------+---------+-----------+
str8 *type*
</doc>
<doc type="bnf">
map = size count *entry
size = uint32 ; size of count and entries in octets
count = uint32 ; number of entries in the map
entry = key type value
key = str8
type = OCTET ; type code of the value
value = *OCTET ; the encoded value
</doc>
</type>
<type name="list" code="0xa9" variable-width="4" label="a series of consecutive type-value pairs">
<doc>
A list is an ordered sequence of (type, value) pairs. The (type, value) pair forms an item
within the list. The list may contain items of many distinct types. A list is encoded as a
size in octets, followed by a count of the number of items, followed by the items themselves
encoded in their defined order.
</doc>
<doc>
An encoded list may contain up to (4294967295 - 4) octets worth of encoded items. The size is
encoded as a 32-bit unsigned integral value in network byte order equal to the number of
octets worth of encoded items plus 4. (The extra 4 octets is added for the item count.) The
size is then followed by the number of items encoded as a 32-bit unsigned integral value in
network byte order. Finally the items are encoded sequentially in their defined order.
</doc>
<doc>
An item is encoded as the type followed by the value. The type is a single octet that may
contain any valid AMQP type code. The value is encoded according to the rules defined by the
type code for that item.
</doc>
<doc type="picture" title="Wire Format">
+---------= size OCTETs =---------+
| |
4 OCTETs | 4 OCTETs |
+----------+----------+-----+----------+-----+
| size | count | .../| item |\... |
+----------+----------+---/ +----------+ \---+
uint32 uint32 / / \ \
/ / \ \
/ 1 OCTET n OCTETs \
+----------+-----------+
| type | value |
+----------+-----------+
*type*
</doc>
<doc type="bnf">
list = size count *item
size = uint32 ; size of count and items in octets
count = uint32 ; number of items in the list
item = type value
type = OCTET ; type code of the value
value = *OCTET ; the encoded value
</doc>
</type>
<type name="array" code="0xaa" variable-width="4"
label="a defined length collection of values of a single type">
<doc>
An array is an ordered sequence of values of the same type. The array is encoded in as a size
in octets, followed by a type code, then a count of the number values in the array, and
finally the values encoded in their defined order.
</doc>
<doc>
An encoded array may contain up to (4294967295 - 5) octets worth of encoded values. The size
is encoded as a 32-bit unsigned integral value in network byte order equal to the number of
octets worth of encoded values plus 5. (The extra 5 octets consist of 4 octets for the count
of the number of values, and one octet to hold the type code for the items in the array.) The
size is then followed by a single octet that may contain any valid AMQP type code. The type
code is then followed by the number of values encoded as a 32-bit unsigned integral value in
network byte order. Finally the values are encoded sequentially in their defined order
according to the rules defined by the type code for the array.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs 1 OCTET 4 OCTETs (size - 5) OCTETs
+----------+---------+----------+-------------------------+
| size | type | count | values |
+----------+---------+----------+-------------------------+
uint32 uint32 *count* encoded *types*
</doc>
<doc type="bnf">
array = size type count values
size = uint32 ; size of type, count, and values in octets
type = OCTET ; the type of the encoded values
count = uint32 ; number of items in the array
values = 0*4294967290 OCTET ; (size - 5) OCTETs
</doc>
</type>
<type name="struct32" code="0xab" variable-width="4" label="a coded struct with a 32-bit size">
<doc>
The struct32 type describes any coded struct with a 32-bit (4 octet) size. The type is
restricted to be only coded structs with a 32-bit size, consequently the first six octets of
any encoded value for this type MUST always contain the size, class-code, and struct-code in
that order.
</doc>
<doc>
The size is encoded as a 32-bit unsigned integral value in network byte order that is equal to
the size of the encoded field-data, packing-flags, class-code, and struct-code. The class-code
is a single octet that may be set to any valid class code. The struct-code is a single octet
that may be set to any valid struct code within the given class-code.
</doc>
<doc>
The first six octets are then followed by the packing flags and encoded field data. The
presence and quantity of packing-flags, as well as the specific fields are determined by the
struct definition identified with the encoded class-code and struct-code.
</doc>
<doc type="picture" title="Wire Format">
4 OCTETs 1 OCTET 1 OCTET pack-width OCTETs n OCTETs
+----------+------------+-------------+-------------------+------------+
| size | class-code | struct-code | packing-flags | field-data |
+----------+------------+-------------+-------------------+------------+
uint32
n = (size - 2 - pack-width)
</doc>
<doc type="bnf">
struct32 = size class-code struct-code packing-flags field-data
size = uint32
class-code = OCTET ; zero for top-level structs
struct-code = OCTET ; together with class-code identifies the struct
; definition which determines the pack-width and
; fields
packing-flags = 0*4 OCTET ; pack-width OCTETs
field-data = *OCTET ; (size - 2 - pack-width) OCTETs
</doc>
</type>
<!--
0xb0 - 0xbf: Reserved
-->
<!--
0xc0 - 0xcf:Fixed width types - 5 octets
-->
<type name="bin40" code="0xc0" fixed-width="5" label="five octets of unspecified binary encoding">
<doc>
The bin40 type consists of five consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-------------+------------+------------+
| octet-one | octet-two | octet-three | octet-four | octet-five |
+-----------+-----------+-------------+------------+------------+
</doc>
<doc type="bnf">
bin40 = 5 OCTET
</doc>
</type>
<type name="dec32" code="0xc8" fixed-width="5"
label="32-bit decimal value (e.g. for use in financial values)">
<doc>
The dec32 type is decimal value with a variable number of digits following the decimal point.
It is encoded as an 8-bit unsigned integral value representing the number of decimal places.
This is followed by the signed integral value encoded using a 32-bit two's complement
representation in network byte order.
</doc>
<doc>
The former value is referred to as the exponent of the divisor. The latter value is the
mantissa. The decimal value is given by: mantissa / 10^exponent.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 4 OCTETs
+----------+----------+
| exponent | mantissa |
+----------+----------+
uint8 int32
</doc>
<doc type="bnf">
dec32 = exponent mantissa
exponent = uint8
mantissa = int32
</doc>
</type>
<!--
0xd0 - 0xdf: Fixed width types - 9 octets
-->
<type name="bin72" code="0xd0" fixed-width="9"
label="nine octets of unspecified binary encoding">
<doc>
The bin72 type consists of nine consecutive octets of opaque binary data.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 1 OCTET 1 OCTET 1 OCTET
+-----------+-----------+-----+-------------+------------+
| octet-one | octet-two | ... | octet-eight | octet-nine |
+-----------+-----------+-----+-------------+------------+
</doc>
<doc type="bnf">
bin64 = 9 OCTET
</doc>
</type>
<type name="dec64" code="0xd8" fixed-width="9"
label="64-bit decimal value (e.g. for use in financial values)">
<doc>
The dec64 type is decimal value with a variable number of digits following the decimal point.
It is encoded as an 8-bit unsigned integral value representing the number of decimal places.
This is followed by the signed integral value encoded using a 64-bit two's complement
representation in network byte order.
</doc>
<doc>
The former value is referred to as the exponent of the divisor. The latter value is the
mantissa. The decimal value is given by: mantissa / 10^exponent.
</doc>
<doc type="picture" title="Wire Format">
1 OCTET 8 OCTETs
+----------+----------+
| exponent | mantissa |
+----------+----------+
uint8 int64
</doc>
<doc type="bnf">
dec64 = exponent mantissa
exponent = uint8
mantissa = int64
</doc>
</type>
<!--
0xe0 - 0xef: Reserved
-->
<!--
0xf0 - 0xff: Zero-length types
-->
<type name="void" code="0xf0" fixed-width="0" label="the void type">
<doc>
The void type is used within tagged data structures such as maps and lists to indicate an
empty value. The void type has no value and is encoded as an empty sequence of octets.
</doc>
</type>
<type name="bit" code="0xf1" fixed-width="0" label="presence indicator">
<doc>
The bit type is used to indicate that a packing flag within a packed struct is being used to
represent a boolean value based on the presence of an empty value. The bit type has no value
and is encoded as an empty sequence of octets.
</doc>
</type>
<!--
======================================================
== CONSTANTS
======================================================
-->
<!-- Protocol constants -->
<constant name="MIN-MAX-FRAME-SIZE" value="4096" label="The minimum size (in bytes) which can be
agreed upon as the maximum frame size.">
<doc>
During the initial connection negotiation, the two peers must agree upon a maximum frame size.
This constant defines the minimum value to which the maximum frame size can be set. By
defining this value, the peers can guarantee that they can send frames of up to this size
until they have agreed a definitive maximum frame size for that connection.
</doc>
</constant>
<!--
======================================================
== DOMAIN TYPES
======================================================
-->
<!-- Segment types -->
<domain name="segment-type" type="uint8" label="valid values for the frame type indicator.">
<doc>
Segments are defined in <xref ref="specification.transport.assemblies_segments_and_frames"/>.
The segment domain defines the valid values that may be used for the segment indicator within
the frame header.
</doc>
<enum>
<choice name="control" value="0">
<doc>
The frame type indicator for Control segments (see <xref
ref="specification.formal_notation.controls"/>).
</doc>
</choice>
<choice name="command" value="1">
<doc>
The frame type indicator for Command segments (see <xref
ref="specification.formal_notation.commands"/>).
</doc>
</choice>
<choice name="header" value="2" >
<doc>
The frame type indicator for Header segments (see <xref
ref="specification.formal_notation.segments.header"/>).
</doc>
</choice>
<choice name="body" value="3" >
<doc>
The frame type indicator for Body segments (see <xref
ref="specification.formal_notation.segments.body"/>).
</doc>
</choice>
</enum>
</domain>
<!-- Tracks -->
<domain name="track" type="uint8" label="Valid values for transport level tracks">
<doc> Tracks are defined in <xref ref="specification.transport.channels_and_tracks"/>. The
track domain defines the valid values that may used for the track indicator within the frame
header</doc>
<enum>
<choice name="control" value="0">
<doc>
The track used for all controls. All controls defined in this specification MUST be sent
on track 0.
</doc>
</choice>
<choice name="command" value="1">
<doc>
The track used for all commands. All commands defined in this specification MUST be sent
on track 1.
</doc>
</choice>
</enum>
</domain>
<domain name="str16-array" type="array" label="An array of values of type str16.">
<doc>
An array of values of type str16.
</doc>
</domain>
<!-- == Class: connection ==================================================================== -->
<class name="connection" code="0x1" label="work with connections">
<doc>
The connection class provides controls for a client to establish a network connection to a
server, and for both peers to operate the connection thereafter.
</doc>
<doc type="grammar">
connection = open-connection
*use-connection
close-connection
open-connection = C:protocol-header
S:START C:START-OK
*challenge
S:TUNE C:TUNE-OK
C:OPEN S:OPEN-OK | S:REDIRECT
challenge = S:SECURE C:SECURE-OK
use-connection = *channel
close-connection = C:CLOSE S:CLOSE-OK
/ S:CLOSE C:CLOSE-OK
</doc>
<role name="server" implement="MUST" />
<role name="client" implement="MUST" />
<domain name="close-code" type="uint16" label="code used in the connection.close control to
indicate reason for closure">
<enum>
<choice name="normal" value="200">
<doc>
The connection closed normally.
</doc>
</choice>
<choice name="connection-forced" value="320">
<doc>
An operator intervened to close the connection for some reason. The client may retry at
some later date.
</doc>
</choice>
<choice name="invalid-path" value="402">
<doc>
The client tried to work with an unknown virtual host.
</doc>
</choice>
<choice name="framing-error" value="501">
<doc>
A valid frame header cannot be formed from the incoming byte stream.
</doc>
</choice>
</enum>
</domain>
<domain name="amqp-host-url" type="str16" label="URL for identifying an AMQP Server">
<doc>
The amqp-url domain defines a format for identifying an AMQP Server. It is used to provide
alternate hosts in the case where a client has to reconnect because of failure, or because
the server requests the client to do so upon initial connection.
</doc>
<doc type="bnf"><![CDATA[
amqp_url = "amqp:" prot_addr_list
prot_addr_list = [prot_addr ","]* prot_addr
prot_addr = tcp_prot_addr | tls_prot_addr
tcp_prot_addr = tcp_id tcp_addr
tcp_id = "tcp:" | ""
tcp_addr = [host [":" port] ]
host = <as per http://www.ietf.org/rfc/rfc3986.txt>
port = number]]>
</doc>
</domain>
<domain name="amqp-host-array" type="array" label="An array of values of type amqp-host-url">
<doc>
Used to provide a list of alternate hosts.
</doc>
</domain>
<!-- - Control: connection.start - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="start" code="0x1" label="start connection negotiation">
<doc>
This control starts the connection negotiation process by telling the client the supported
security mechanisms and locales from which the client can choose.
</doc>
<rule name="protocol-name">
<doc>
If the server cannot support the protocol specified in the protocol header, it MUST close
the socket connection without sending any response control.
</doc>
<doc type="scenario">
The client sends a protocol header containing an invalid protocol name. The server must
respond by closing the connection.
</doc>
</rule>
<rule name="client-support">
<doc>
If the client cannot handle the protocol version suggested by the server it MUST close the
socket connection.
</doc>
<doc type="scenario">
The server sends a protocol version that is lower than any valid implementation, e.g. 0.1.
The client must respond by closing the connection.
</doc>
</rule>
<implement role="client" handle="MUST" />
<response name="start-ok" />
<field name="server-properties" type="map" label="server properties">
<rule name="required-fields">
<doc>
The properties SHOULD contain at least these fields: "host", specifying the server host
name or address, "product", giving the name of the server product, "version", giving the
name of the server version, "platform", giving the name of the operating system,
"copyright", if appropriate, and "information", giving other general information.
</doc>
<doc type="scenario">
Client connects to server and inspects the server properties. It checks for the presence
of the required fields.
</doc>
</rule>
</field>
<field name="mechanisms" type="str16-array" label="available security mechanisms"
required="true">
<doc>
A list of the security mechanisms that the server supports.
</doc>
</field>
<field name="locales" type="str16-array" label="available message locales" required="true">
<doc>
A list of the message locales that the server supports. The locale defines the language in
which the server will send reply texts.
</doc>
<rule name="required-support">
<doc>
The server MUST support at least the en_US locale.
</doc>
<doc type="scenario">
Client connects to server and inspects the locales field. It checks for the presence of
the required locale(s).
</doc>
</rule>
</field>
</control>
<!-- - Control: connection.start-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="start-ok" code="0x2" label="select security mechanism and locale">
<doc>
This control selects a SASL security mechanism.
</doc>
<implement role="server" handle="MUST" />
<field name="client-properties" type="map" label="client properties">
<rule name="required-fields">
<!-- This rule is not testable from the client side -->
<doc>
The properties SHOULD contain at least these fields: "product", giving the name of the
client product, "version", giving the name of the client version, "platform", giving the
name of the operating system, "copyright", if appropriate, and "information", giving
other general information.
</doc>
</rule>
</field>
<field name="mechanism" type="str8" label="selected security mechanism" required="true">
<doc>
A single security mechanisms selected by the client, which must be one of those specified
by the server.
</doc>
<rule name="security">
<doc>
The client SHOULD authenticate using the highest-level security profile it can handle
from the list provided by the server.
</doc>
</rule>
<rule name="validity">
<doc>
If the mechanism field does not contain one of the security mechanisms proposed by the
server in the Start control, the server MUST close the connection without sending any
further data.
</doc>
<doc type="scenario">
Client connects to server and sends an invalid security mechanism. The server must
respond by closing the connection (a socket close, with no connection close
negotiation).
</doc>
</rule>
</field>
<field name="response" type="vbin32" label="security response data" required="true">
<doc>
A block of opaque data passed to the security mechanism. The contents of this data are
defined by the SASL security mechanism.
</doc>
</field>
<field name="locale" type="str8" label="selected message locale" required="true">
<doc>
A single message locale selected by the client, which must be one of those specified by
the server.
</doc>
</field>
</control>
<!-- - Control: connection.secure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="secure" code="0x3" label="security mechanism challenge">
<doc>
The SASL protocol works by exchanging challenges and responses until both peers have
received sufficient information to authenticate each other. This control challenges the
client to provide more information.
</doc>
<implement role="client" handle="MUST" />
<response name="secure-ok" />
<field name="challenge" type="vbin32" label="security challenge data" required="true">
<doc>
Challenge information, a block of opaque binary data passed to the security mechanism.
</doc>
</field>
</control>
<!-- - Control: connection.secure-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="secure-ok" code="0x4" label="security mechanism response">
<doc>
This control attempts to authenticate, passing a block of SASL data for the security
mechanism at the server side.
</doc>
<implement role="server" handle="MUST" />
<field name="response" type="vbin32" label="security response data" required="true">
<doc>
A block of opaque data passed to the security mechanism. The contents of this data are
defined by the SASL security mechanism.
</doc>
</field>
</control>
<!-- - Control: connection.tune - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="tune" code="0x5" label="propose connection tuning parameters">
<doc>
This control proposes a set of connection configuration values to the client. The client can
accept and/or adjust these.
</doc>
<implement role="client" handle="MUST" />
<response name="tune-ok" />
<field name="channel-max" type="uint16" label="proposed maximum channels">
<doc>
The maximum total number of channels that the server allows per connection. If this is not
set it means that the server does not impose a fixed limit, but the number of allowed
channels may be limited by available server resources.
</doc>
</field>
<field name="max-frame-size" type="uint16" label="proposed maximum frame size">
<doc>
The largest frame size that the server proposes for the connection. The client can
negotiate a lower value. If this is not set means that the server does not impose any
specific limit but may reject very large frames if it cannot allocate resources for them.
</doc>
<rule name="minimum">
<doc>
Until the max-frame-size has been negotiated, both peers MUST accept frames of up to
MIN-MAX-FRAME-SIZE octets large, and the minimum negotiated value for max-frame-size is
also MIN-MAX-FRAME-SIZE.
</doc>
<doc type="scenario">
Client connects to server and sends a large properties field, creating a frame of
MIN-MAX-FRAME-SIZE octets. The server must accept this frame.
</doc>
</rule>
</field>
<field name="heartbeat-min" type="uint16" label="the minimum supported heartbeat delay">
<doc>
The minimum delay, in seconds, of the connection heartbeat supported by the server. If
this is not set it means the server does not support sending heartbeats.
</doc>
</field>
<field name="heartbeat-max" type="uint16" label="the maximum supported heartbeat delay">
<doc>
The maximum delay, in seconds, of the connection heartbeat supported by the server. If
this is not set it means the server has no maximum.
</doc>
<rule name="permitted-range">
<doc>
The heartbeat-max value must be greater than or equal to the value supplied in the
heartbeat-min field.
</doc>
</rule>
<rule name="no-heartbeat-min">
<doc>
If no heartbeat-min is supplied, then the heartbeat-max field MUST remain empty.
</doc>
</rule>
</field>
</control>
<!-- - Control: connection.tune-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="tune-ok" code="0x6" label="negotiate connection tuning parameters">
<doc>
This control sends the client's connection tuning parameters to the server. Certain fields
are negotiated, others provide capability information.
</doc>
<implement role="server" handle="MUST" />
<field name="channel-max" type="uint16" label="negotiated maximum channels" required="true">
<doc>
The maximum total number of channels that the client will use per connection.
</doc>
<rule name="upper-limit">
<doc>
If the client specifies a channel max that is higher than the value provided by the
server, the server MUST close the connection without attempting a negotiated close. The
server may report the error in some fashion to assist implementers.
</doc>
</rule>
<rule name="available-channels">
<doc>
If the client agrees to a channel-max of N channels, then the channels available for
communication between client and server are precisely the channels numbered 0 to (N-1).
</doc>
</rule>
</field>
<field name="max-frame-size" type="uint16" label="negotiated maximum frame size">
<doc>
The largest frame size that the client and server will use for the connection. If it is
not set means that the client does not impose any specific limit but may reject very large
frames if it cannot allocate resources for them. Note that the max-frame-size limit
applies principally to content frames, where large contents can be broken into frames of
arbitrary size.
</doc>
<rule name="minimum">
<doc>
Until the max-frame-size has been negotiated, both peers MUST accept frames of up to
MIN-MAX-FRAME-SIZE octets large, and the minimum negotiated value for max-frame-size is
also MIN-MAX-FRAME-SIZE.
</doc>
</rule>
<rule name="upper-limit">
<doc>
If the client specifies a max-frame-size that is higher than the value provided by the
server, the server MUST close the connection without attempting a negotiated close. The
server may report the error in some fashion to assist implementers.
</doc>
</rule>
<rule name="max-frame-size">
<doc>
A peer MUST NOT send frames larger than the agreed-upon size. A peer that receives an
oversized frame MUST close the connection with the framing-error close-code.
</doc>
</rule>
</field>
<field name="heartbeat" type="uint16" label="negotiated heartbeat delay">
<doc>
The delay, in seconds, of the connection heartbeat chosen by the client. If it is not set
it means the client does not want a heartbeat.
</doc>
<rule name="permitted-range">
<doc>
The chosen heartbeat MUST be in the range supplied by the heartbeat-min and
heartbeat-max fields of connection.tune.
</doc>
</rule>
<rule name="no-heartbeat-min">
<doc>
The heartbeat field MUST NOT be set if the heartbeat-min field of connection.tune was
not set by the server.
</doc>
</rule>
</field>
</control>
<!-- - Control: connection.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="open" code="0x7" label="open connection to virtual host">
<doc>
This control opens a connection to a virtual host, which is a collection of resources, and
acts to separate multiple application domains within a server. The server may apply
arbitrary limits per virtual host, such as the number of each type of entity that may be
used, per connection and/or in total.
</doc>
<implement role="server" handle="MUST" />
<response name="open-ok" />
<response name="redirect" />
<field name="virtual-host" type="str8" label="virtual host name" required="true">
<doc>
The name of the virtual host to work with.
</doc>
<rule name="separation">
<doc>
If the server supports multiple virtual hosts, it MUST enforce a full separation of
exchanges, queues, and all associated entities per virtual host. An application,
connected to a specific virtual host, MUST NOT be able to access resources of another
virtual host.
</doc>
</rule>
<rule name="security">
<doc>
The server SHOULD verify that the client has permission to access the specified virtual
host.
</doc>
</rule>
</field>
<field name="capabilities" type="str16-array" label="required capabilities">
<doc>
The client can specify zero or more capability names. The server can use this to determine
how to process the client's connection request.
</doc>
</field>
<field name="insist" type="bit" label="insist on connecting to server">
<doc>
In a configuration with multiple collaborating servers, the server may respond to a
connection.open control with a Connection.Redirect. The insist option tells the server
that the client is insisting on a connection to the specified server.
</doc>
<rule name="behavior">
<doc>
When the client uses the insist option, the server MUST NOT respond with a
Connection.Redirect control. If it cannot accept the client's connection request it
should respond by closing the connection with a suitable reply code.
</doc>
</rule>
</field>
</control>
<!-- - Control: connection.open-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="open-ok" code="0x8" label="signal that connection is ready">
<doc>
This control signals to the client that the connection is ready for use.
</doc>
<implement role="client" handle="MUST" />
<field name="known-hosts" type="amqp-host-array" label="alternate hosts which may be used in
the case of failure">
<doc>
Specifies an array of equivalent or alternative hosts that the server knows about, which
will normally include the current server itself. Each entry in the array will be in the
form of an IP address or DNS name, optionally followed by a colon and a port number.
Clients can cache this information and use it when reconnecting to a server after a
failure. This field may be empty.
</doc>
</field>
</control>
<!-- - Control: connection.redirect - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="redirect" code="0x9" label="redirects client to other server">
<doc>
This control redirects the client to another server, based on the requested virtual host
and/or capabilities.
</doc>
<rule name="usage">
<doc>
When getting the connection.redirect control, the client SHOULD reconnect to the host
specified, and if that host is not present, to any of the hosts specified in the
known-hosts list.
</doc>
</rule>
<implement role="client" handle="MUST" />
<field name="host" type="amqp-host-url" label="server to connect to" required="true">
<doc>
Specifies the server to connect to.
</doc>
</field>
<field name="known-hosts" type="amqp-host-array" label="alternate hosts to try in case of
failure">
<doc>
An array of equivalent or alternative hosts that the server knows about.
</doc>
</field>
</control>
<!-- - Control: connection.heartbeat - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="heartbeat" code="0xa" label="indicates connection is still alive">
<doc>
The heartbeat control may be used to generate artificial network traffic when a connection
is idle. If a connection is idle for more than twice the negotiated heartbeat delay, the
peers MAY be considered disconnected.
</doc>
<implement role="client" handle="MAY" />
<implement role="server" handle="MAY" />
</control>
<!-- - Control: connection.close - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="close" code="0xb" label="request a connection close">
<doc>
This control indicates that the sender wants to close the connection. The reason for close
is indicated with the reply-code and reply-text. The channel this control is sent on MAY be
used to indicate which channel caused the connection to close.
</doc>
<implement role="client" handle="MUST" />
<implement role="server" handle="MUST" />
<response name="close-ok" />
<field name="reply-code" type="close-code" label="the numeric reply code"
required="true">
<doc>
Indicates the reason for connection closure.
</doc>
</field>
<field name="reply-text" type="str8" label="the localized reply text">
<doc>
This text can be logged as an aid to resolving issues.
</doc>
</field>
</control>
<!-- - Control: connection.close-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<control name="close-ok" code="0xc" label="confirm a connection close">
<doc>
This control confirms a connection.close control and tells the recipient that it is safe to
release resources for the connection and close the socket.
</doc>
<rule name="reporting">
<doc>
A peer that detects a socket closure without having received a Close-Ok handshake control
SHOULD log the error.
</doc>
</rule>
<implement role="client" handle="MUST" />
<implement role="server" handle="MUST" />
</control>
</class>
<!-- == Class: session ======================================================================= -->
<class name="session" code="0x2" label="session controls">
<doc>
A session is a named interaction between two peers. Session names are chosen by the upper
layers and may be used indefinitely. The model layer may associate long-lived or durable state
with a given session name. The session layer provides transport of commands associated with
this interaction.
</doc>
<doc>
The controls defined within this class are specified in terms of the "sender" of commands and
the "receiver" of commands. Since both client and server send and receive commands, the
overall session dialog is symmetric, however the semantics of the session controls are defined
in terms of a single sender/receiver pair, and it is assumed that the client and server will
each contain both a sender and receiver implementation.
</doc>
<rule name="attachment">
<doc>
The transport MUST be attached in order to use any control other than "attach", "attached",
"detach", or "detached". A peer receiving any other control on a detached transport MUST
discard it and send a session.detached with the "not-attached" reason code.
</doc>
</rule>
<role name="server" implement="MUST" />
<role name="client" implement="MUST" />
<role name="sender" implement="MUST">
<doc>
The sender of commands.
</doc>
</role>
<role name="receiver" implement="MUST">
<doc>
The receiver of commands.
</doc>
</role>
<domain name="name" type="vbin16" label="opaque session name">
<doc>
The session name uniquely identifies an interaction between two peers. It is scoped to a
given authentication principal.
</doc>
</domain>
<domain name="detach-code" type="uint8" label="reason for detach">
<enum>
<choice name="normal" value="0">
<doc>
The session was detached by request.
</doc>
</choice>
<choice name="session-busy" value="1">
<doc>
The session is currently attached to another transport.
</doc>
</choice>
<choice name="transport-busy" value="2">
<doc>
The transport is currently attached to another session.
</doc>
</choice>
<choice name="not-attached" value="3">
<doc>
The transport is not currently attached to any session.
</doc>
</choice>
<choice name="unknown-ids" value="4">
<doc>
Command data was received prior to any use of the command-point control.
</doc>
</choice>
</enum>
</domain>
<domain name="commands" type="sequence-set" label="identifies a set of commands">
</domain>
<struct name="header" size="1" pack="1">
<doc>
The session header appears on commands after the class and command id, but prior to command
arguments.
</doc>
<field name="sync" type="bit" label="request notification of completion">
<doc>
Request notification of completion for this command.
</doc>
</field>
</struct>
<struct name="command-fragment" size="0" pack="0" label="byte-ranges within a set of commands">
<field name="command-id" type="sequence-no" required="true">
</field>
<field name="byte-ranges" type="byte-ranges" required="true">
</field>
</struct>
<domain name="command-fragments" type="array" label="an array of values of type
command-fragment"/>
<control name="attach" code="0x1" label="attach to the named session">
<doc>
Requests that the current transport be attached to the named session. Success or failure
will be indicated with an attached or detached response. This control is idempotent.
</doc>
<rule name="one-transport-per-session">
<doc>
A session MUST NOT be attached to more than one transport at a time.
</doc>
</rule>
<rule name="one-session-per-transport">
<doc>
A transport MUST NOT be attached to more than one session at a time.
</doc>
</rule>
<rule name="idempotence">
<doc>
Attaching a session to its current transport MUST succeed and result in an attached
response.
</doc>
</rule>
<rule name="scoping">
<doc>
Attachment to the same session name from distinct authentication principals MUST succeed.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MAY" />
<response name="attached"/>
<response name="detached"/>
<field name="name" type="name" label="the session name" required="true">
<doc>
Identifies the session to be attached to the current transport.
</doc>
</field>
<field name="force" type="bit" label="force attachment to a busy session">
<doc>
If set then a busy session will be forcibly detached from its other transport and
reattached to the current transport.
</doc>
</field>
</control>
<control name="attached" code="0x2" label="confirm attachment to the named session">
<doc>
Confirms successful attachment of the transport to the named session.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="name" type="name" label="the session name" required="true">
<doc>
Identifies the session now attached to the current transport.
</doc>
</field>
</control>
<control name="detach" code="0x3" label="detach from the named session">
<doc>
Detaches the current transport from the named session.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<response name="detached"/>
<field name="name" type="name" label="the session name" required="true">
<doc>
Identifies the session to detach.
</doc>
</field>
</control>
<control name="detached" code="0x4" label="confirm detachment from the named session">
<doc>
Confirms detachment of the current transport from the named session.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="name" type="name" label="the session name" required="true">
<doc>
Identifies the detached session.
</doc>
</field>
<field name="code" type="detach-code" label="the reason for detach" required="true">
<doc>
Identifies the reason for detaching from the named session.
</doc>
</field>
</control>
<!--
Execution state is the set of confirmed, and completed incoming commands, as well as the set
of outgoing in-doubt commands held for replay.
-->
<control name="request-timeout" code="0x5" label="requests the execution timeout be changed">
<doc>
This control may be sent by either the sender or receiver of commands. It requests that the
execution timeout be changed. This is the minimum amount of time that a peer must preserve
execution state for a detached session.
</doc>
<rule name="maximum-granted-timeout">
<doc>
The handler of this request MUST set his timeout to the maximum allowed value less than or
equal to the requested timeout, and MUST convey the chosen timeout in the response.
</doc>
</rule>
<implement role="sender" handle="MUST" />
<implement role="receiver" handle="MUST" />
<response name="timeout"/>
<field name="timeout" type="uint32" label="the requested timeout">
<doc>
The requested timeout for execution state in seconds. If not set, this control requests
that execution state is preserved indefinitely.
</doc>
</field>
</control>
<control name="timeout" code="0x6" label="the granted timeout">
<doc>
This control may be sent by the either the sender or receiver of commands. It is a
one-to-one reply to the request-timeout control that indicates the granted timeout for
execution state.
</doc>
<implement role="sender" handle="MUST" />
<implement role="receiver" handle="MUST" />
<field name="timeout" type="uint32" label="the execution timeout">
<doc>
The timeout for execution state. If not set, then execution state is preserved
indefinitely.
</doc>
</field>
</control>
<control name="command-point" code="0x7"
label="the command id and byte offset of subsequent data">
<doc>
This control is sent by the sender of commands and handled by the receiver of commands. This
establishes the sequence numbers associated with all subsequent command data sent from the
sender to the receiver. The subsequent command data will be numbered starting with the
values supplied in this control and proceeding sequentially. This must be used at least once
prior to sending any command data on newly attached transports.
</doc>
<rule name="newly-attached-transports">
<doc>
If command data is sent on a newly attached transport the session MUST be detached with an
"unknown-id" reason-code.
</doc>
</rule>
<rule name="zero-offset">
<doc>
If the offset is zero, the next data frame MUST have the first-frame and first-segment
flags set. Violation of this is a framing error.
</doc>
</rule>
<rule name="nonzero-offset">
<doc>
If the offset is nonzero, the next data frame MUST NOT have both the first-frame and
first-segment flag set. Violation of this is a framing error.
</doc>
</rule>
<implement role="receiver" handle="MUST" />
<field name="command-id" type="sequence-no" label="the command-id of the next command"
required="true"/>
<field name="command-offset" type="uint64" label="the byte offset within the command"
required="true"/>
</control>
<control name="expected" code="0x8" label="informs the peer of expected commands">
<doc>
This control is sent by the receiver of commands and handled by the sender of commands. It
informs the sender of what commands and command fragments are expected at the receiver.
This control is only sent in response to a flush control with the expected flag set. The
expected control is never sent spontaneously.
</doc>
<rule name="include-next-command">
<doc>
The set of expected commands MUST include the next command after the highest seen command.
</doc>
</rule>
<rule name="commands-empty-means-new-session">
<doc>
The set of expected commands MUST have zero elements if and only if the sender holds no
execution state for the session (i.e. it is a new session).
</doc>
</rule>
<rule name="no-overlaps">
<doc>
If a command-id appears in the commands field, it MUST NOT appear in the fragments field.
</doc>
</rule>
<rule name="minimal-fragments">
<doc>
When choice is permitted, a command MUST appear in the commands field rather than the
fragments field.
</doc>
</rule>
<implement role="sender" handle="MUST" />
<field name="commands" type="commands" label="expected commands" required="true"/>
<field name="fragments" type="command-fragments" label="expected fragments" />
</control>
<control name="confirmed" code="0x9" label="notifies of confirmed commands">
<doc>
This control is sent by the receiver of commands and handled by the sender of commands. This
sends the set of commands that will definitely be completed by this peer to the sender. This
excludes commands known by the receiver to be considered confirmed or complete at the
sender.
</doc>
<doc>
This control must be sent if the partner requests the set of confirmed commands using the
session.flush control with the confirmed flag set.
</doc>
<doc>
This control may be sent spontaneously. One reason for separating confirmation from
completion is for large persistent messages, where the receipt (and storage to a durable
store) of part of the message will result in less data needing to be replayed in the case of
transport failure during transmission.
</doc>
<doc>
A simple implementation of an AMQP client or server may be implemented to take no action on
receipt of session.confirmed controls, and take action only when receiving
session.completed controls.
</doc>
<doc>
A simple implementation of an AMQP client or server may be implemented such that it never
spontaneously sends session.confirmed and that when requested for the set of confirmed
commands (via the session.flush control) it responds with the same set of commands as it
would to when the set of completed commands was requested (trivially all completed commands
are confirmed).
</doc>
<rule name="durability">
<doc>
If a command has durable implications, it MUST NOT be confirmed until the fact of the
command has been recorded on durable media.
</doc>
</rule>
<rule name="no-overlaps">
<doc>
If a command-id appears in the commands field, it MUST NOT appear in the fragments field.
</doc>
</rule>
<rule name="minimal-fragments">
<doc>
When choice is permitted, a command MUST appear in the commands field rather than the
fragments field.
</doc>
</rule>
<implement role="sender" handle="MUST" />
<field name="commands" type="commands" label="entirely confirmed commands">
<rule name="exclude-known-complete">
<doc>
Command-ids included in prior known-complete replies MUST be excluded from the set of
all confirmed commands.
</doc>
</rule>
</field>
<field name="fragments" type="command-fragments" label="partially confirmed commands"/>
</control>
<control name="completed" code="0xa" label="notifies of command completion">
<doc>
This control is sent by the receiver of commands, and handled by the sender of commands. It
informs the sender of all commands completed by the receiver. This excludes commands known
by the receiver to be considered complete at the sender.
</doc>
<rule name="known-completed-reply">
<doc>
The sender MUST eventually reply with a known-completed set that covers the completed ids.
</doc>
</rule>
<rule name="delayed-reply">
<doc>
The known-complete reply MAY be delayed at the senders discretion if the timely-reply
field is not set.
</doc>
</rule>
<rule name="merged-reply">
<doc>
Multiple replies may be merged by sending a single known-completed that includes the union
of the merged command-id sets.
</doc>
</rule>
<implement role="sender" handle="MUST" />
<field name="commands" type="commands" label="completed commands">
<doc>
The ids of all completed commands. This excludes commands known by the receiver to be
considered complete at the sender.
</doc>
<rule name="completed-implies-confirmed">
<doc>
The sender MUST consider any completed commands to also be confirmed.
</doc>
</rule>
<rule name="exclude-known-complete">
<doc>
Command-ids included in prior known-complete replies MUST be excluded from the set of
all completed commands.
</doc>
</rule>
</field>
<field name="timely-reply" type="bit">
<doc>
If set, the sender is no longer free to delay the known-completed reply.
</doc>
</field>
</control>
<control name="known-completed" code="0xb" label="Inform peer of which commands are known to be
completed">
<doc>
This control is sent by the sender of commands, and handled by the receiver of commands. It
is sent in reply to one or more completed controls from the receiver. It informs the
receiver that commands are known to be completed by the sender.
</doc>
<rule name="stateless">
<doc>
The sender need not keep state to generate this reply. It is sufficient to reply to any
completed control with an exact echo of the completed ids.
</doc>
</rule>
<implement role="receiver" handle="MUST" />
<field name="commands" type="commands" label="commands known to be complete">
<doc>
The set of completed commands for one or more session.completed controls.
</doc>
<rule name="known-completed-implies-known-confirmed">
<doc>
The receiver MUST treat any of the specified commands to be considered by the sender as
confirmed as well as completed.
</doc>
</rule>
</field>
</control>
<control name="flush" code="0xc" label="requests a session.completed">
<doc>
This control is sent by the sender of commands and handled by the receiver of commands. It
requests that the receiver produce the indicated command sets. The receiver should issue the
indicated sets at the earliest possible opportunity.
</doc>
<implement role="receiver" handle="MUST" />
<field name="expected" type="bit" label="request notification of expected commands"/>
<field name="confirmed" type="bit" label="request notification of confirmed commands"/>
<field name="completed" type="bit" label="request notification of completed commands"/>
</control>
<control name="gap" code="0xd" label="indicates missing segments in the stream">
<doc>
This control is sent by the sender of commands and handled by the receiver of commands. It
sends command ranges for which there will be no further data forthcoming. The receiver
should proceed with the next available commands that arrive after the gap.
</doc>
<rule name="gap-confirmation-and-completion">
<doc>
The command-ids covered by a session.gap MUST be added to the completed and confirmed sets
by the receiver.
</doc>
</rule>
<rule name="aborted-commands">
<doc>
If a session.gap covers a partially received command, the receiving peer MUST treat the
command as aborted.
</doc>
</rule>
<rule name="completed-or-confirmed-commands">
<doc>
If a session.gap covers a completed or confirmed command, the receiving peer MUST continue
to treat the command as completed or confirmed.
</doc>
</rule>
<implement role="receiver" handle="MUST" />
<field name="commands" type="commands">
<doc>
The set of command-ids that are contained in this gap.
</doc>
</field>
</control>
</class>
<!-- == Class: execution ===================================================================== -->
<class name="execution" code="0x3" label="execution commands">
<doc>
The execution class provides commands that carry execution information about other model level
commands.
</doc>
<role name="server" implement="MUST"/>
<role name="client" implement="MUST"/>
<domain name="error-code" type="uint16">
<enum>
<choice name="unauthorized-access" value="403">
<doc>
The client attempted to work with a server entity to which it has no access due to
security settings.
</doc>
</choice>
<choice name="not-found" value="404">
<doc>
The client attempted to work with a server entity that does not exist.
</doc>
</choice>
<choice name="resource-locked" value="405">
<doc>
The client attempted to work with a server entity to which it has no access because
another client is working with it.
</doc>
</choice>
<choice name="precondition-failed" value="406">
<doc>
The client requested a command that was not allowed because some precondition failed.
</doc>
</choice>
<choice name="resource-deleted" value="408">
<doc>
A server entity the client is working with has been deleted.
</doc>
</choice>
<choice name="illegal-state" value="409">
<doc>
The peer sent a command that is not permitted in the current state of the session.
</doc>
</choice>
<choice name="command-invalid" value="503">
<doc>
The command segments could not be decoded.
</doc>
</choice>
<choice name="resource-limit-exceeded" value="506">
<doc>
The client exceeded its resource allocation.
</doc>
</choice>
<choice name="not-allowed" value="530">
<doc>
The peer tried to use a command a manner that is inconsistent with the rules described
in the specification.
</doc>
</choice>
<choice name="illegal-argument" value="531">
<doc>
The command argument is malformed, i.e. it does not fall within the specified domain.
The illegal-argument exception can be raised on execution of any command which has
domain valued fields.
</doc>
</choice>
<choice name="not-implemented" value="540">
<doc>
The peer tried to use functionality that is not implemented in its partner.
</doc>
</choice>
<choice name="internal-error" value="541">
<doc>
The peer could not complete the command because of an internal error. The peer may
require intervention by an operator in order to resume normal operations.
</doc>
</choice>
<choice name="invalid-argument" value="542">
<doc>
An invalid argument was passed to a command, and the operation could not
proceed. An invalid argument is not illegal (see illegal-argument), i.e. it matches
the domain definition; however the particular value is invalid in this context.
</doc>
</choice>
</enum>
</domain>
<!-- - Command: execution.sync - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="sync" code="0x1" label="request notification of completion for issued commands">
<doc>
This command is complete when all prior commands are completed.
</doc>
<implement role="server" handle="MUST"/>
<implement role="client" handle="MUST"/>
</command>
<!-- - Command: execution.result - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="result" code="0x2" label="carries execution results">
<doc>
This command carries data resulting from the execution of a command.
</doc>
<implement role="server" handle="MUST"/>
<implement role="client" handle="MUST"/>
<field name="command-id" type="sequence-no" required="true"/>
<field name="value" type="struct32"/>
</command>
<!-- - Command: execution.exception - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="exception" code="0x3" label="notifies a peer of an execution error">
<doc>
This command informs a peer of an execution exception. The command-id, when given,
correlates the error to a specific command.
</doc>
<implement role="client" handle="MUST"/>
<implement role="server" handle="MUST"/>
<field name="error-code" type="error-code" required="true" label="error code indicating the
type of error"/>
<field name="command-id" type="sequence-no" label="exceptional command">
<doc>
The command-id of the command which caused the exception. If the exception was not caused
by a specific command, this value is not set.
</doc>
</field>
<field name="class-code" type="uint8" label="the class code of the command whose execution
gave rise to the error (if appropriate)"/>
<field name="command-code" type="uint8" label="the class code of the command whose execution
gave rise to the error (if appropriate)"/>
<field name="field-index" type="uint8" label="index of the exceptional field">
<doc>
The zero based index of the exceptional field within the arguments to the exceptional
command. If the exception was not caused by a specific field, this value is not set.
</doc>
</field>
<field name="description" type="str16" label="descriptive text on the exception">
<doc>
The description provided is implementation defined, but MUST be in the language
appropriate for the selected locale. The intention is that this description is suitable
for logging or alerting output.
</doc>
</field>
<field name="error-info" type="map" label="map to carry additional information about the
error"/>
</command>
</class>
<!-- == Class: message ======================================================================= -->
<class name="message" code="0x4" label="message transfer">
<doc>
The message class provides commands that support an industry-standard messaging model.
</doc>
<doc type="picture" title="Transfer States">
START:
The message has yet to be sent to the recipient.
NOT-ACQUIRED:
The message has been sent to the recipient, but is not
acquired by the recipient.
ACQUIRED:
The message has been sent to and acquired by the recipient.
END:
The transfer is complete.
</doc>
<doc type="picture" title="State Transitions"><![CDATA[
*:TRANSFER (accept-mode=none) *:TRANSFER (acquire-mode=pre-acquired)
+---------------------------------START------------------------------------------+
| | |
| | *:TRANSFER (acquire-mode=not-acquired) |
| | |
| R:RELEASE \|/ |
| +-------------NOT-ACQUIRED<--+ |
| | | | | R:ACQUIRE (if unavailable) |
| | | +-----+ |
| | | |
| | | R:ACQUIRE (if available) |
| | | |
| | \|/ |
| | ACQUIRED<-------------------------------------------+
| | |
| | | R:ACCEPT / R:REJECT / R:RELEASE
| | |
| | \|/
| +------------->END]]>
| /|\
| |
+-------------------------------+
</doc>
<doc type="grammar">
message = *:TRANSFER [ R:ACQUIRE ] [ R:ACCEPT / R:REJECT / R:RELEASE ]
/ *:RESUME
/ *:SET-FLOW-MODE
/ *:FLOW
/ *:STOP
/ C:SUBSCRIBE
/ C:CANCEL
/ C:FLUSH
</doc>
<rule name="persistent-message">
<doc>
The server SHOULD respect the delivery-mode property of messages and SHOULD make a
best-effort to hold persistent messages on a reliable storage mechanism.
</doc>
<doc type="scenario">
Send a persistent message to queue, stop server, restart server and then verify whether
message is still present. Assumes that queues are durable. Persistence without durable
queues makes no sense.
</doc>
</rule>
<rule name="no-persistent-message-discard">
<doc>
The server MUST NOT discard a persistent message in case of a queue overflow.
</doc>
<doc type="scenario">
Create a queue overflow situation with persistent messages and verify that messages do not
get lost (presumably the server will write them to disk).
</doc>
</rule>
<rule name="throttling">
<doc>
The server MAY use the message.flow command to slow or stop a message publisher when
necessary.
</doc>
</rule>
<rule name="non-persistent-message-overflow">
<doc>
The server MAY overflow non-persistent messages to persistent storage.
</doc>
</rule>
<rule name="non-persistent-message-discard">
<doc>
The server MAY discard or dead-letter non-persistent messages on a priority basis if the
queue size exceeds some configured limit.
</doc>
</rule>
<rule name="min-priority-levels">
<doc>
The server MUST implement at least 2 priority levels for messages, where priorities 0 and
9 are treated as two distinct levels.
</doc>
</rule>
<rule name="priority-level-implementation">
<doc>
The server SHOULD implement distinct priority levels in the following manner:
</doc>
<doc>
If the server implements n distinct priorities then priorities 0 to 5 - ceiling(n/2) should
be treated equivalently and should be the lowest effective priority. The priorities 4 +
floor(n/2) should be treated equivalently and should be the highest effective priority. The
priorities (5 - ceiling(n/2)) to (4 + floor(n/2)) inclusive must be treated as distinct
priorities.
</doc>
<doc>
Thus, for example, if 2 distinct priorities are implemented, then levels 0 to 4 are
equivalent, and levels 5 to 9 are equivalent and levels 4 and 5 are distinct. If 3 distinct
priorities are implements the 0 to 3 are equivalent, 5 to 9 are equivalent and 3, 4 and 5
are distinct.
</doc>
<doc>
This scheme ensures that if two priorities are distinct for a server which implements m
separate priority levels they are also distinct for a server which implements n different
priority levels where n > m.
</doc>
</rule>
<rule name="priority-delivery">
<doc>
The server MUST deliver messages of the same priority in order irrespective of their
individual persistence.
</doc>
<doc type="scenario">
Send a set of messages with the same priority but different persistence settings to a queue.
Subscribe and verify that messages arrive in same order as originally published.
</doc>
</rule>
<role name="server" implement="MUST" />
<role name="client" implement="MUST" />
<domain name="destination" type="str8" label="destination for a message">
<doc>
Specifies the destination to which the message is to be transferred.
</doc>
</domain>
<domain name="accept-mode" type="uint8" label="indicates a confirmation mode">
<doc>
Controls how the sender of messages is notified of successful transfer.
</doc>
<enum>
<choice name="explicit" value="0">
<doc>
Successful transfer is signaled by message.accept. An acquired message (whether
acquisition was implicit as in pre-acquired mode or explicit as in not-acquired mode) is
not considered transferred until a message.accept that includes the transfer command is
received.
</doc>
</choice>
<choice name="none" value="1">
<doc>
Successful transfer is assumed when accept-mode is "pre-acquired". Messages transferred
with an accept-mode of "not-acquired" cannot be acquired when accept-mode is "none".
</doc>
</choice>
</enum>
</domain>
<domain name="acquire-mode" type="uint8" label="indicates the transfer mode">
<doc>
Indicates whether a transferred message can be considered as automatically acquired or
whether an explicit request is necessary in order to acquire it.
</doc>
<enum>
<choice name="pre-acquired" value="0">
<doc>
the message is acquired when the transfer starts
</doc>
</choice>
<choice name="not-acquired" value="1">
<doc>
the message is not acquired when it arrives, and must be explicitly acquired by the
recipient
</doc>
</choice>
</enum>
</domain>
<domain name="reject-code" type="uint16" label="reject code for transfer">
<doc>
Code specifying the reason for a message reject.
</doc>
<enum>
<choice name="unspecified" value="0">
<doc>
Rejected for an unspecified reason.
</doc>
</choice>
<choice name="unroutable" value="1">
<doc>
Delivery was attempted but there were no queues which the message could be routed to.
</doc>
</choice>
<choice name="immediate" value="2">
<doc>
The rejected message had the immediate flag set to true, but at the time of the transfer
at least one of the queues to which it was to be routed did not have any subscriber able
to take the message.
</doc>
</choice>
</enum>
</domain>
<domain name="resume-id" type="str16">
<doc>
A resume-id serves to identify partially transferred message content. The id is chosen by
the sender, and must be unique to a given user. A resume-id is not expected to be unique
across users.
</doc>
</domain>
<domain name="delivery-mode" type="uint8"
label="indicates whether a message should be treated as transient or durable">
<doc>
Used to set the reliability requirements for a message which is transferred to the server.
</doc>
<enum>
<choice name="non-persistent" value="1">
<doc>
A non-persistent message may be lost in event of a failure, but the nature of the
communication is such that an occasional message loss is tolerable. This is the lowest
overhead mode. Non-persistent messages are delivered at most once only.
</doc>
</choice>
<choice name="persistent" value="2">
<doc>
A persistent message is one which must be stored on a persistent medium (usually hard
drive) at every stage of delivery so that it will not be lost in event of failure (other
than of the medium itself). This is normally accomplished with some additional overhead.
A persistent message may be delivered more than once if there is uncertainty about the
state of its delivery after a failure and recovery.
</doc>
</choice>
</enum>
</domain>
<domain name="delivery-priority" type="uint8"
label="indicates the desired priority to assign to a message transfer">
<doc>
Used to assign a priority to a message transfer. Priorities range from 0 (lowest) to 9
(highest).
</doc>
<enum>
<choice name="lowest" value="0">
<doc>
Lowest possible priority message.
</doc>
</choice>
<choice name="lower" value="1">
<doc>
Very low priority message
</doc>
</choice>
<choice name="low" value="2">
<doc>
Low priority message.
</doc>
</choice>
<choice name="below-average" value="3">
<doc>
Below average priority message.
</doc>
</choice>
<choice name="medium" value="4">
<doc>
Medium priority message.
</doc>
</choice>
<choice name="above-average" value="5">
<doc>
Above average priority message
</doc>
</choice>
<choice name="high" value="6">
<doc>
High priority message
</doc>
</choice>
<choice name="higher" value="7">
<doc>
Higher priority message
</doc>
</choice>
<choice name="very-high" value="8">
<doc>
Very high priority message.
</doc>
</choice>
<choice name="highest" value="9">
<doc>
Highest possible priority message.
</doc>
</choice>
</enum>
</domain>
<struct name="delivery-properties" size="4" code="0x1" pack="2">
<field name="discard-unroutable" type="bit" label="controls discard of unroutable messages">
<doc>
If set on a message that is not routable the broker can discard it. If not set, an
unroutable message should be handled by reject when accept-mode is explicit; or by routing
to the alternate-exchange if defined when accept-mode is none.
</doc>
</field>
<field name="immediate" type="bit" label="Consider message unroutable if it cannot be
processed immediately">
<doc>
If the immediate flag is set to true on a message transferred to a Server, then the
message should be considered unroutable (and not delivered to any queues) if, for any
queue that it is to be routed to according to the standard routing behavior, there is not
a subscription on that queue able to receive the message. The treatment of unroutable
messages is dependent on the value of the discard-unroutable flag.
</doc>
<doc>
The immediate flag is ignored on transferred to a Client.
</doc>
</field>
<field name="redelivered" type="bit" label="redelivery flag">
<doc>
This boolean flag indicates that the message may have been previously delivered to this
or another client.
</doc>
<doc>
If the redelivered flag is set on transfer to a Server, then any delivery of the message
from that Server to a Client must also have the redelivered flag set to true.
</doc>
<rule name="implementation">
<doc>
The server MUST try to signal redelivered messages when it can. When redelivering a
message that was not successfully accepted, the server SHOULD deliver it to the original
client if possible.
</doc>
<doc type="scenario">
Create a shared queue and publish a message to the queue. Subscribe using explicit
accept-mode, but do not accept the message. Close the session, reconnect, and subscribe
to the queue again. The message MUST arrive with the redelivered flag set.
</doc>
</rule>
<rule name="hinting">
<doc>
The client should not rely on the redelivered field to detect duplicate messages where
publishers may themselves produce duplicates. A fully robust client should be able to
track duplicate received messages on non-transacted, and locally-transacted sessions.
</doc>
</rule>
</field>
<field name="priority" type="delivery-priority" label="message priority, 0 to 9"
required="true">
<doc> Message priority, which can be between 0 and 9. Messages with higher priorities may be
delivered before those with lower priorities. </doc>
</field>
<field name="delivery-mode" type="delivery-mode" label="message persistence requirement"
required="true">
<doc> The delivery mode may be non-persistent or persistent. </doc>
</field>
<field name="ttl" type="uint64" label="time to live in ms">
<doc> Duration in milliseconds for which the message should be considered "live". If this is
set then a message expiration time will be computed based on the current time plus this
value. Messages that live longer than their expiration time will be discarded (or dead
lettered).</doc>
<rule name="ttl-decrement">
<doc>
If a message is transferred between brokers before delivery to a final subscriber the
ttl should be decremented before peer to peer transfer and both timestamp and expiration
should be cleared.
</doc>
</rule>
</field>
<field name="timestamp" type="datetime" label="message timestamp">
<doc>
The timestamp is set by the broker on arrival of the message.
</doc>
</field>
<field name="expiration" type="datetime" label="message expiration time">
<doc>
The expiration header assigned by the broker. After receiving the message the broker sets
expiration to the sum of the ttl specified in the publish command and the current time.
(ttl=expiration - timestamp)
</doc>
</field>
<field name="exchange" type="exchange.name" label="originating exchange">
<doc>
Identifies the exchange specified in the destination field of the message.transfer used to
publish the message. This MUST be set by the broker upon receipt of a message.
</doc>
</field>
<field name="routing-key" type="str8" label="message routing key">
<doc>
The value of the key determines to which queue the exchange will send the message. The way
in which keys are used to make this routing decision depends on the type of exchange to
which the message is sent. For example, a direct exchange will route a message to a queue
if that queue is bound to the exchange with a binding-key identical to the routing-key of
the message.
</doc>
</field>
<field name="resume-id" type="resume-id" label="global id for message transfer">
<doc>
When a resume-id is provided the recipient MAY use it to retain message data should the
session expire while the message transfer is still incomplete.
</doc>
</field>
<field name="resume-ttl" type="uint64" label="ttl in ms for interrupted message data">
<doc>
When a resume-ttl is provided the recipient MAY use it has a guideline for how long to
retain the partially complete data when a resume-id is specified. If no resume-id is
specified then this value should be ignored.
</doc>
</field>
</struct>
<struct name="fragment-properties" size="4" code="0x2" pack="2">
<doc>
These properties permit the transfer of message fragments. These may be used in conjunction
with byte level flow control to limit the rate at which large messages are received. Only
the first fragment carries the delivery-properties and message-properties.
Syntactically each fragment appears as a complete message to the lower layers of the
protocol, however the model layer is required to treat all the fragments as a single
message. For example all fragments must be delivered to the same client. In pre-acquired
mode, no message fragments can be delivered by the broker until the entire message has been
received.
</doc>
<field name="first" type="bit" default="1">
<doc>True if this fragment contains the start of the message, false otherwise.</doc>
</field>
<field name="last" type="bit" default="1">
<doc>True if this fragment contains the end of the message, false otherwise.</doc>
</field>
<field name="fragment-size" type="uint64">
<doc>This field may optionally contain the size of the fragment.</doc>
</field>
</struct>
<struct name="reply-to" size="2" pack="2">
<doc>The reply-to domain provides a simple address structure for replying to to a message to a
destination within the same virtual-host.</doc>
<field name="exchange" type="exchange.name" label="the name of the exchange to reply to"/>
<field name="routing-key" type="str8" label="the routing-key to use when replying"/>
</struct>
<struct name="message-properties" size="4" code="0x3" pack="2">
<field name="content-length" type="uint64" label="length of the body segment in bytes">
<doc>
The length of the body segment in bytes.
</doc>
</field>
<field name="message-id" type="uuid" label="application message identifier">
<doc>
Message-id is an optional property of UUID type which uniquely identifies a message within
the message system. The message producer is usually responsible for setting the
message-id. The server MAY discard a message as a duplicate if the value of the message-id
matches that of a previously received message. Duplicate messages MUST still be accepted
if transferred with an accept-mode of "explicit".
</doc>
<rule name="unique">
<doc>
A message-id MUST be unique within a given server instance. A message-id SHOULD be
globally unique (i.e. across different systems).
</doc>
</rule>
<rule name="immutable">
<doc>
A message ID is immutable. Once set, a message-id MUST NOT be changed or reassigned,
even if the message is replicated, resent or sent to multiple queues.
</doc>
</rule>
</field>
<field name="correlation-id" type="vbin16" label="application correlation identifier">
<doc>
This is a client-specific id that may be used to mark or identify messages between
clients. The server ignores this field.
</doc>
</field>
<field name="reply-to" type="reply-to" label="destination to reply to">
<doc>
The destination of any message that is sent in reply to this message.
</doc>
</field>
<field name="content-type" type="str8" label="MIME content type">
<doc>
The RFC-2046 MIME type for the message content (such as "text/plain"). This is set by the
originating client.
</doc>
</field>
<field name="content-encoding" type="str8" label="MIME content encoding">
<doc>
The encoding for character-based message content. This is set by the originating client.
Examples include UTF-8 and ISO-8859-15.
</doc>
</field>
<field name="user-id" type="vbin16" label="creating user id">
<doc>
The identity of the user responsible for producing the message. The client sets this
value, and it is authenticated by the broker.
</doc>
<rule name="authentication">
<doc>
The server MUST produce an unauthorized-access exception if the user-id field is set to
a principle for which the client is not authenticated.
</doc>
</rule>
</field>
<field name="app-id" type="vbin16" label="creating application id">
<doc>
The identity of the client application responsible for producing the message.
</doc>
</field>
<field name="application-headers" type="map" label="application specific headers table">
<doc>
This is a collection of user-defined headers or properties which may be set by the
producing client and retrieved by the consuming client.
</doc>
</field>
</struct>
<domain name="flow-mode" type="uint8" label="the flow-mode for allocating flow credit">
<enum>
<choice name="credit" value="0">
<doc>
Credit based flow control.
</doc>
</choice>
<choice name="window" value="1">
<doc>
Window based flow control.
</doc>
</choice>
</enum>
</domain>
<domain name="credit-unit" type="uint8" label="specifies the unit of credit balance">
<enum>
<choice name="message" value="0">
<doc>Indicates a value specified in messages.</doc>
</choice>
<choice name="byte" value="1">
<doc>Indicates a value specified in bytes.</doc>
</choice>
</enum>
</domain>
<!-- - Command: message.transfer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="transfer" code="0x1" label="transfer a message">
<doc>
This command transfers a message between two peers. When a client uses this command to
publish a message to a broker, the destination identifies a specific exchange. The message
will then be routed to queues as defined by the exchange configuration.
The client may request a broker to transfer messages to it, from a particular queue, by
issuing a subscribe command. The subscribe command specifies the destination that the broker
should use for any resulting transfers.
</doc>
<rule name="transactional-publish">
<doc>
If a transfer to an exchange occurs within a transaction, then it is not available from
the queue until the transaction commits. It is not specified whether routing takes place
when the transfer is received or when the transaction commits.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="destination" type="destination" label="message destination">
<doc>
Specifies the destination to which the message is to be transferred.
</doc>
<rule name="blank-destination">
<doc>
The server MUST accept a blank destination to mean the default exchange.
</doc>
</rule>
<exception name="nonexistent-exchange" error-code="not-found">
<doc>
If the destination refers to an exchange that does not exist, the peer MUST raise a
session exception.
</doc>
</exception>
</field>
<field name="accept-mode" type="accept-mode" required="true">
<doc>
Indicates whether message.accept, session.complete, or nothing at all is required to
indicate successful transfer of the message.
</doc>
</field>
<field name="acquire-mode" type="acquire-mode" required="true">
<doc>
Indicates whether or not the transferred message has been acquired.
</doc>
</field>
<segments>
<header>
<entry type="delivery-properties"/>
<entry type="fragment-properties"/>
<entry type="message-properties"/>
</header>
<body/>
</segments>
</command>
<!-- - Command: message.accept - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="accept" code="0x2" label="reject a message">
<doc>
Accepts the message. Once a transfer is accepted, the command-id may no longer be referenced
from other commands.
</doc>
<rule name="acquisition">
<doc>
The recipient MUST have acquired a message in order to accept it.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="transfers" type="session.commands" required="true">
<doc>
Identifies the messages previously transferred that should be accepted.
</doc>
</field>
</command>
<!-- - Command: message.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="reject" code="0x3" label="reject a message">
<doc>
Indicates that the message transfers are unprocessable in some way. A server may reject a
message if it is unroutable. A client may reject a message if it is invalid. A message may
be rejected for other reasons as well. Once a transfer is rejected, the command-id may no
longer be referenced from other commands.
</doc>
<rule name="alternate-exchange">
<doc>
When a client rejects a message, the server MUST deliver that message to the
alternate-exchange on the queue from which it was delivered. If no alternate-exchange is
defined for that queue the broker MAY discard the message.
</doc>
</rule>
<rule name="acquisition">
<doc>
The recipient MUST have acquired a message in order to reject it. If the message is not
acquired any reject MUST be ignored.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="transfers" type="session.commands" required="true">
<doc>
Identifies the messages previously transferred that should be rejected.
</doc>
</field>
<field name="code" type="reject-code" required="true">
<doc>
Code describing the reason for rejection.
</doc>
</field>
<field name="text" type="str8" label="informational text for message reject">
<doc>
Text describing the reason for rejection.
</doc>
</field>
</command>
<!-- - Command: message.release - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="release" code="0x4" label="release a message">
<doc>
Release previously transferred messages. When acquired messages are released, they become
available for acquisition by any subscriber. Once a transfer is released, the command-id may
no longer be referenced from other commands.
</doc>
<rule name="ordering">
<doc>
Acquired messages that have been released MAY subsequently be delivered out of order.
Implementations SHOULD ensure that released messages keep their position with respect to
undelivered messages of the same priority.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MAY" />
<field name="transfers" type="session.commands" required="true">
<doc>
Indicates the messages to be released.
</doc>
</field>
<field name="set-redelivered" type="bit" label="mark the released messages as redelivered">
<doc>
By setting set-redelivered to true, any acquired messages released to a queue with this
command will be marked as redelivered on their next transfer from that queue. If this flag
is not set, then an acquired message will retain its original redelivered status on the
queue. Messages that are not acquired are unaffected by the value of this flag.
</doc>
</field>
</command>
<!-- - Command: message.acquire - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="acquire" code="0x5" label="acquire messages for consumption">
<doc>
Acquires previously transferred messages for consumption. The acquired ids (if any) are
sent via message.acquired.
</doc>
<rule name="one-to-one">
<doc>
Each acquire MUST produce exactly one message.acquired even if it is empty.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="transfers" type="session.commands" required="true">
<doc>
Indicates the messages to be acquired.
</doc>
</field>
<result>
<struct name="acquired" size="4" code="0x4" pack="2" label="indicates acquired messages">
<doc>
Identifies a set of previously transferred messages that have now been acquired.
</doc>
<field name="transfers" type="session.commands" required="true">
<doc>
Indicates the acquired messages.
</doc>
</field>
</struct>
</result>
</command>
<!-- - Command: message.resume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="resume" code="0x6" label="resume an interrupted message transfer">
<doc>
This command resumes an interrupted transfer. The recipient should return the amount of
partially transferred data associated with the given resume-id, or zero if there is no data
at all. If a non-zero result is returned, the recipient should expect to receive message
fragment(s) containing the remainder of the interrupted message.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="destination" type="destination">
<doc>
The destination to which the remaining message fragments are transferred.
</doc>
<exception name="destination-not-found" error-code="not-found">
<doc>If the destination does not exist, the recipient MUST close the session.</doc>
</exception>
</field>
<field name="resume-id" type="resume-id" required="true">
<doc>
The name of the transfer being resumed.
</doc>
<rule name="unknown-resume-id">
<doc>If the resume-id is not known, the recipient MUST return an offset of zero.</doc>
</rule>
</field>
<result>
<struct name="message-resume-result" size="4" code="0x5" pack="2">
<field name="offset" type="uint64">
<doc>
Indicates the amount of data already transferred.
</doc>
</field>
</struct>
</result>
</command>
<!-- - Command: message.subscribe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="subscribe" code="0x7" label="start a queue subscription">
<doc> This command asks the server to start a "subscription", which is a request for messages
from a specific queue. Subscriptions last as long as the session they were created on, or
until the client cancels them. </doc>
<rule name="simultaneous-subscriptions">
<doc> The server SHOULD support at least 16 subscriptions per queue, and ideally, impose no
limit except as defined by available resources. </doc>
<doc type="scenario"> Create a queue and create subscriptions on that queue until the server
closes the connection. Verify that the number of subscriptions created was at least
sixteen and report the total number. </doc>
</rule>
<rule name="default-flow-mode">
<doc> The default flow mode for new subscriptions is window-mode. </doc>
</rule>
<exception name="queue-deletion" error-code="resource-deleted">
<doc>
If the queue for this subscription is deleted, any subscribing sessions MUST be closed.
This exception may occur at any time after the subscription has been completed.
</doc>
</exception>
<exception name="queue-not-found" error-code="not-found">
<doc> If the queue for this subscription does not exist, then the subscribing session MUST
be closed. </doc>
</exception>
<rule name="initial-credit">
<doc>
Immediately after a subscription is created, the initial byte and message credit for that
destination is zero.
</doc>
</rule>
<implement role="server" handle="MUST"/>
<field name="queue" type="queue.name" required="true">
<doc> Specifies the name of the subscribed queue. </doc>
</field>
<field name="destination" type="destination" label="incoming message destination">
<doc> The client specified name for the subscription. This is used as the destination for
all messages transferred from this subscription. The destination is scoped to the session.
</doc>
<exception name="unique-subscriber-destination" error-code="not-allowed">
<doc> The client MUST NOT specify a destination that refers to an existing subscription on
the same session. </doc>
<doc type="scenario"> Attempt to create two subscriptions on the same session with the
same non-empty destination. </doc>
</exception>
</field>
<field name="accept-mode" type="accept-mode" required="true">
<doc> The accept-mode to use for messages transferred from this subscription. </doc>
</field>
<field name="acquire-mode" type="acquire-mode" required="true">
<doc> The acquire-mode to use for messages transferred from this subscription. </doc>
</field>
<field name="exclusive" type="bit" label="request exclusive access">
<doc> Request an exclusive subscription. This prevents other subscribers from subscribing to
the queue. </doc>
<exception name="in-use" error-code="resource-locked">
<doc> The server MUST NOT grant an exclusive subscription to a queue that already has
subscribers. </doc>
<doc type="scenario"> Open two connections to a server, and in one connection create a
shared (non-exclusive) queue and then subscribe to the queue. In the second connection
attempt to subscribe to the same queue using the exclusive option. </doc>
</exception>
</field>
<field name="resume-id" type="resume-id">
<doc> Requests that the broker use the supplied resume-id when transferring messages for
this subscription. </doc>
</field>
<field name="resume-ttl" type="uint64">
<doc> Requested duration in milliseconds for the broker use as resume-ttl when transferring
messages for this subscription. </doc>
</field>
<field name="arguments" type="map" label="arguments for vendor extensions">
<doc> The syntax and semantics of these arguments depends on the providers implementation.
</doc>
</field>
</command>
<!-- - Command: message.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="cancel" code="0x8" label="end a queue subscription">
<doc>
This command cancels a subscription. This does not affect already delivered messages, but it
does mean the server will not send any more messages for that subscription. The client may
receive an arbitrary number of messages in between sending the cancel command and receiving
notification that the cancel command is complete.
</doc>
<rule name="post-cancel-transfer-resolution">
<doc>
Canceling a subscription MUST NOT affect pending transfers. A transfer made prior to
canceling transfers to the destination MUST be able to be accepted, released, acquired, or
rejected after the subscription is canceled.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="destination" type="destination" required="true">
<exception name="subscription-not-found" error-code="not-found">
<doc>
If the subscription specified by the destination is not found, the server MUST close the
session.
</doc>
</exception>
</field>
</command>
<!-- - Command: message.set-flow-mode - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="set-flow-mode" code="0x9" label="set the flow control mode">
<doc>
Sets the mode of flow control used for a given destination to either window or credit based
flow control.
With credit based flow control, the sender of messages continually maintains its current
credit balance with the recipient. The credit balance consists of two values, a message
count, and a byte count. Whenever message data is sent, both counts must be decremented.
If either value reaches zero, the flow of message data must stop. Additional credit is
received via the message.flow command.
The sender MUST NOT send partial assemblies. This means that if there is not enough byte
credit available to send a complete message, the sender must either wait or use message
fragmentation (see the fragment-properties header struct) to send the first part of the
message data in a complete assembly.
Window based flow control is identical to credit based flow control, however message
transfer completion implicitly grants a single unit of message credit, and the size of the
message in byte credits for each completed message transfer. Completion of the transfer
command with session.completed is the only way credit is implicitly updated; message.accept,
message.release, message.reject, tx.commit and tx.rollback have no effect on the outstanding
credit balances.
</doc>
<rule name="byte-accounting">
<doc>
The byte count is decremented by the payload size of each transmitted frame with segment
type header or body appearing within a message.transfer command. Note that the payload
size is the frame size less the frame header size.
</doc>
</rule>
<rule name="mode-switching">
<doc>
Mode switching may only occur if both the byte and message credit balance are zero. There
are three ways for a recipient of messages to be sure that the sender's credit balances
are zero:
1) The recipient may send a message.stop command to the sender. When the recipient
receives notification of completion for the message.stop command, it knows that the
sender's credit is zero.
2) The recipient may perform the same steps described in (1) with the message.flush
command substituted for the message.stop command.
3) Immediately after a subscription is created with message.subscribe, the credit for
that destination is zero.
</doc>
</rule>
<rule name="default-flow-mode">
<doc>
Prior to receiving an explicit set-flow-mode command, a peer MUST consider the flow-mode
to be window.
</doc>
</rule>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="destination" type="destination"/>
<field name="flow-mode" type="flow-mode" required="true">
<doc>
The new flow control mode.
</doc>
</field>
</command>
<!-- - Command: message.flow - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="flow" code="0xa" label="control message flow">
<doc>
This command controls the flow of message data to a given destination. It is used by the
recipient of messages to dynamically match the incoming rate of message flow to its
processing or forwarding capacity. Upon receipt of this command, the sender must add "value"
number of the specified unit to the available credit balance for the specified destination.
A value of (0xFFFFFFFF) indicates an infinite amount of credit. This disables any limit for
the given unit until the credit balance is zeroed with message.stop or message.flush.
</doc>
<!-- throws no-such-destination -->
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="destination" type="destination"/>
<field name="unit" type="credit-unit" required="true">
<doc>
The unit of value.
</doc>
</field>
<field name="value" type="uint32">
<doc>
If the value is not set then this indicates an infinite amount of credit.
</doc>
</field>
</command>
<!-- - Command: message.flush - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="flush" code="0xb" label="force the sending of available messages">
<doc>
Forces the sender to exhaust his credit supply. The sender's credit will always be zero when
this command completes. The command completes when immediately available message data has
been transferred, or when the credit supply is exhausted.
</doc>
<implement role="server" handle="MUST" />
<field name="destination" type="destination"/>
</command>
<!-- - Command: message.stop - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="stop" code="0xc" label="stop the sending of messages">
<doc>
On receipt of this command, a producer of messages MUST set his credit to zero for the given
destination. When notifying of completion, credit MUST be zero and no further messages will
be sent until such a time as further credit is received.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<field name="destination" type="destination"/>
</command>
</class>
<!-- == Class: tx ============================================================================ -->
<class name="tx" code="0x5" label="work with standard transactions">
<doc>
Standard transactions provide so-called "1.5 phase commit". We can ensure that work is never
lost, but there is a chance of confirmations being lost, so that messages may be resent.
Applications that use standard transactions must be able to detect and ignore duplicate
messages.
</doc>
<doc type="grammar">
tx = C:SELECT
/ C:COMMIT
/ C:ROLLBACK
</doc>
<!-- XXX: this isn't really a rule, as stated there is no way for
a client library to implement this -->
<rule name="duplicate-tracking">
<doc>
An client using standard transactions SHOULD be able to track all messages received within a
reasonable period, and thus detect and reject duplicates of the same message. It SHOULD NOT
pass these to the application layer.
</doc>
</rule>
<role name="server" implement="SHOULD" />
<!-- - Command: tx.select - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="select" code="0x1" label="select standard transaction mode">
<doc>
This command sets the session to use standard transactions. The client must use this command
exactly once on a session before using the Commit or Rollback commands.
</doc>
<exception name="exactly-once" error-code="illegal-state">
<doc>
A client MUST NOT select standard transactions on a session that is already transactional.
</doc>
</exception>
<exception name="no-dtx" error-code="illegal-state">
<doc>
A client MUST NOT select standard transactions on a session that is already enlisted in a
distributed transaction.
</doc>
</exception>
<exception name="explicit-accepts" error-code="not-allowed">
<doc>
On a session on which tx.select has been issued, a client MUST NOT issue a
message.subscribe command with the accept-mode property set to any value other than
explicit. Similarly a tx.select MUST NOT be issued on a session on which a there is a non
cancelled subscriber with accept-mode of none.
</doc>
</exception>
<implement role="server" handle="MUST" />
</command>
<!-- - Command: tx.commit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="commit" code="0x2" label="commit the current transaction">
<doc>
This command commits all messages published and accepted in the current transaction. A
new transaction starts immediately after a commit.
</doc>
<doc>
In more detail, the commit acts on all messages which have been transferred from the Client
to the Server, and on all acceptances of messages sent from Server to Client. Since the
commit acts on commands sent in the same direction as the commit command itself, there is no
ambiguity on the scope of the commands being committed. Further, the commit will not be
completed until all preceding commands which it affects have been completed.
</doc>
<doc>
Since transactions act on explicit accept commands, the only valid accept-mode for message
subscribers is explicit. For transferring messages from Client to Server (publishing) all
accept-modes are permitted.
</doc>
<exception name="select-required" error-code="illegal-state">
<doc>
A client MUST NOT issue tx.commit on a session that has not been selected for standard
transactions with tx.select.
</doc>
</exception>
<implement role="server" handle="MUST" />
</command>
<!-- - Command: tx.rollback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="rollback" code="0x3" label="abandon the current transaction">
<doc>
This command abandons the current transaction. In particular the transfers from Client to
Server (publishes) and accepts of transfers from Server to Client which occurred in the
current transaction are discarded. A new transaction starts immediately after a rollback.
</doc>
<doc>
In more detail, when a rollback is issued, any the effects of transfers which occurred from
Client to Server are discarded. The Server will issue completion notification for all such
transfers prior to the completion of the rollback. Similarly the effects of any
message.accept issued from Client to Server prior to the issuance of the tx.rollback will be
discarded; and notification of completion for all such commands will be issued before the
issuance of the completion for the rollback.
</doc>
<doc>
After the completion of the rollback, the client will still hold the messages which it has
not yet accepted (including those for which accepts were previously issued within the
transaction); i.e. the messages remain "acquired". If the Client wishes to release those
messages back to the Server, then appropriate message.release commands must be issued.
</doc>
<exception name="select-required" error-code="illegal-state">
<doc>
A client MUST NOT issue tx.rollback on a session that has not been selected for standard
transactions with tx.select.
</doc>
</exception>
<implement role="server" handle="MUST" />
</command>
</class>
<!-- == Class: dtx =========================================================================== -->
<class name="dtx" code="0x6" label="Demarcates dtx branches">
<doc>
This provides the X-Open XA distributed transaction protocol support. It allows a session
to be selected for use with distributed transactions, the transactional boundaries for work on
that session to be demarcated and allows the transaction manager to coordinate transaction
outcomes.
</doc>
<doc type="grammar">
dtx-demarcation = C:SELECT *demarcation
demarcation = C:START C:END
</doc>
<doc type="grammar">
dtx-coordination = *coordination
coordination = command
/ outcome
/ recovery
command = C:SET-TIMEOUT
/ C:GET-TIMEOUT
outcome = one-phase-commit
/ one-phase-rollback
/ two-phase-commit
/ two-phase-rollback
one-phase-commit = C:COMMIT
one-phase-rollback = C:ROLLBACK
two-phase-commit = C:PREPARE C:COMMIT
two-phase-rollback = C:PREPARE C:ROLLBACK
recovery = C:RECOVER *recovery-outcome
recovery-outcome = one-phase-commit
/ one-phase-rollback
/ C:FORGET
</doc>
<rule name="transactionality">
<doc>
Enabling XA transaction support on a session requires that the server MUST manage
transactions demarcated by start-end blocks. That is to say that on this XA-enabled session,
work undergone within transactional blocks is performed on behalf a transaction branch
whereas work performed outside of transactional blocks is NOT transactional.
</doc>
</rule>
<role name="server" implement="MAY" />
<role name="client" implement="MAY" />
<!-- XA domains -->
<domain name="xa-status" type="uint16" label="XA return codes">
<enum>
<choice name="xa-ok" value="0">
<doc>
Normal execution completion (no error).
</doc>
</choice>
<choice name="xa-rbrollback" value="1">
<doc>
The rollback was caused for an unspecified reason.
</doc>
</choice>
<choice name="xa-rbtimeout" value="2">
<doc>
A transaction branch took too long.
</doc>
</choice>
<choice name="xa-heurhaz" value="3">
<doc>
The transaction branch may have been heuristically completed.
</doc>
</choice>
<choice name="xa-heurcom" value="4">
<doc>
The transaction branch has been heuristically committed.
</doc>
</choice>
<choice name="xa-heurrb" value="5">
<doc>
The transaction branch has been heuristically rolled back.
</doc>
</choice>
<choice name="xa-heurmix" value="6">
<doc>
The transaction branch has been heuristically committed and rolled back.
</doc>
</choice>
<choice name="xa-rdonly" value="7">
<doc>
The transaction branch was read-only and has been committed.
</doc>
</choice>
</enum>
</domain>
<struct name="xa-result" size="4" code="0x1" pack="2">
<field name="status" type="xa-status" required="true"/>
</struct>
<!-- Struct for xid -->
<struct name="xid" size="4" code="0x4" pack="2" label="dtx branch identifier">
<doc>
An xid uniquely identifies a transaction branch.
</doc>
<field name="format" type="uint32" label="implementation specific format code"
required="true"/>
<field name="global-id" type="vbin8" label="global transaction id" required="true"/>
<field name="branch-id" type="vbin8" label="branch qualifier" required="true"/>
</struct>
<!-- - Command: dtx.select - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="select" code="0x1" label="Select dtx mode">
<doc>
This command sets the session to use distributed transactions. The client must use this
command at least once on a session before using XA demarcation operations.
</doc>
<implement role="server" handle="MAY" />
</command>
<!-- - Command: dtx.start - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="start" code="0x2" label="Start a dtx branch">
<doc>
This command is called when messages should be produced and consumed on behalf a transaction
branch identified by xid.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
send a session exception.
</doc>
</exception>
<exception name="already-known" error-code="not-allowed">
<doc>
If neither join nor resume is specified is specified and the transaction branch specified
by xid has previously been seen then the server MUST raise an exception.
</doc>
</exception>
<exception name="join-and-resume" error-code="not-allowed">
<doc>
If join and resume are specified then the server MUST raise an exception.
</doc>
</exception>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch to be started.
</doc>
<exception name="unknown-xid" error-code="not-allowed">
<doc>
If xid is already known by the broker then the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="join" type="bit" label="Join with existing xid flag">
<doc>
Indicate whether this is joining an already associated xid. Indicate that the start
applies to joining a transaction previously seen.
</doc>
<exception name="unsupported" error-code="not-implemented">
<doc>
If the broker does not support join the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="resume" type="bit" label="Resume flag">
<doc>
Indicate that the start applies to resuming a suspended transaction branch specified.
</doc>
</field>
<result type="xa-result">
<doc>
This confirms to the client that the transaction branch is started or specify the error
condition.
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
</result>
</command>
<!-- - Command: dtx.end - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="end" code="0x3" label="End a dtx branch">
<doc>
This command is called when the work done on behalf a transaction branch finishes or needs
to be suspended.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
raise an exception.
</doc>
</exception>
<exception name="suspend-and-fail" error-code="not-allowed">
<doc>
If suspend and fail are specified then the server MUST raise an exception.
</doc>
</exception>
<rule name="success">
<doc>
If neither fail nor suspend are specified then the portion of work has completed
successfully.
</doc>
</rule>
<rule name="session-closed">
<doc>
When a session is closed then the currently associated transaction branches MUST be marked
rollback-only.
</doc>
</rule>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch to be ended.
</doc>
<exception name="not-associated" error-code="illegal-state">
<doc>
The session MUST be currently associated with the given xid (through an earlier start
call with the same xid).
</doc>
</exception>
</field>
<field name="fail" type="bit" label="Failure flag">
<doc>
If set, indicates that this portion of work has failed; otherwise this portion of work has
completed successfully.
</doc>
<rule name="failure">
<doc>
An implementation MAY elect to roll a transaction back if this failure notification is
received. Should an implementation elect to implement this behavior, and this bit is
set, then then the transaction branch SHOULD be marked as rollback-only and the end
result SHOULD have the xa-rbrollback status set.
</doc>
</rule>
</field>
<field name="suspend" type="bit" label="Temporary suspension flag">
<doc>
Indicates that the transaction branch is temporarily suspended in an incomplete state.
</doc>
<rule name="resume">
<doc>
The transaction context is in a suspended state and must be resumed via the start
command with resume specified.
</doc>
</rule>
</field>
<result type="xa-result">
<doc>
This command confirms to the client that the transaction branch is ended or specify the
error condition.
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason. If an implementation chooses to implement rollback-on-failure behavior, then
this value should be selected if the dtx.end.fail bit was set.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
</result>
</command>
<!-- - Command: dtx.commit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="commit" code="0x4" label="Commit work on dtx branch">
<doc>
Commit the work done on behalf a transaction branch. This command commits the work
associated with xid. Any produced messages are made available and any consumed messages are
discarded.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
raise an exception.
</doc>
</exception>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch to be committed.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
<exception name="not-disassociated" error-code="illegal-state">
<doc>
If this command is called when xid is still associated with a session then the server
MUST raise an exception.
</doc>
</exception>
</field>
<field name="one-phase" type="bit" label="One-phase optimization flag">
<doc>
Used to indicate whether one-phase or two-phase commit is used.
</doc>
<exception name="one-phase" error-code="illegal-state">
<doc>
The one-phase bit MUST be set if a commit is sent without a preceding prepare.
</doc>
</exception>
<exception name="two-phase" error-code="illegal-state">
<doc>
The one-phase bit MUST NOT be set if the commit has been preceded by prepare.
</doc>
</exception>
</field>
<result type="xa-result">
<doc>
This confirms to the client that the transaction branch is committed or specify the
error condition.
The value of this field may be one of the following constants:
xa-ok: Normal execution
xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction
branch may have been heuristically completed.
xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was committed.
xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was rolled back.
xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was partially committed and partially rolled back.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
</result>
</command>
<!-- - Command: dtx.forget - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="forget" code="0x5" label="Discard dtx branch">
<doc>
This command is called to forget about a heuristically completed transaction branch.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
raise an exception.
</doc>
</exception>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch to be forgotten.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
<exception name="not-disassociated" error-code="illegal-state">
<doc>
If this command is called when xid is still associated with a session then the server
MUST raise an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: dtx.get-timeout - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="get-timeout" code="0x6" label="Obtain dtx timeout in seconds">
<doc>
This command obtains the current transaction timeout value in seconds. If set-timeout was
not used prior to invoking this command, the return value is the default timeout; otherwise,
the value used in the previous set-timeout call is returned.
</doc>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch for getting the timeout.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
</field>
<result>
<struct name="get-timeout-result" size="4" code="0x2" pack="2">
<doc> Returns the value of the timeout last specified through set-timeout. </doc>
<field name="timeout" type="uint32" label="The current transaction timeout value"
required="true">
<doc> The current transaction timeout value in seconds. </doc>
</field>
</struct>
</result>
</command>
<!-- - Command: dtx.prepare - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="prepare" code="0x7" label="Prepare a dtx branch">
<doc>
This command prepares for commitment any message produced or consumed on behalf of xid.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
raise an exception.
</doc>
</exception>
<rule name="obligation-1">
<doc>
Once this command successfully returns it is guaranteed that the transaction branch may be
either committed or rolled back regardless of failures.
</doc>
</rule>
<rule name="obligation-2">
<doc>
The knowledge of xid cannot be erased before commit or rollback complete the branch.
</doc>
</rule>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch that can be prepared.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
<exception name="not-disassociated" error-code="illegal-state">
<doc>
If this command is called when xid is still associated with a session then the server
MUST raise an exception.
</doc>
</exception>
</field>
<result type="xa-result">
<doc>
This command confirms to the client that the transaction branch is prepared or specify the
error condition.
The value of this field may be one of the following constants:
xa-ok: Normal execution.
xa-rdonly: The transaction branch was read-only and has been committed.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
</result>
</command>
<!-- - Command: dtx.recover - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="recover" code="0x8" label="Get prepared or completed xids">
<doc>
This command is called to obtain a list of transaction branches that are in a prepared or
heuristically completed state.
</doc>
<implement role="server" handle="MAY" />
<result>
<struct name="recover-result" size="4" code="0x3" pack="2">
<doc>
Returns to the client a table with single item that is a sequence of transaction xids
that are in a prepared or heuristically completed state.
</doc>
<field name="in-doubt" type="array" label="array of xids to be recovered" required="true">
<doc> Array containing the xids to be recovered (xids that are in a prepared or
heuristically completed state). </doc>
</field>
</struct>
</result>
</command>
<!-- - Command: dtx.rollback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="rollback" code="0x9" label="Rollback a dtx branch">
<doc>
This command rolls back the work associated with xid. Any produced messages are discarded
and any consumed messages are re-enqueued.
</doc>
<exception name="illegal-state" error-code="illegal-state">
<doc>
If the command is invoked in an improper context (see class grammar) then the server MUST
raise an exception.
</doc>
</exception>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch that can be rolled back.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
<exception name="not-disassociated" error-code="illegal-state">
<doc>
If this command is called when xid is still associated with a session then the server
MUST raise an exception.
</doc>
</exception>
</field>
<result type="xa-result">
<doc>
This command confirms to the client that the transaction branch is rolled back or specify
the error condition.
The value of this field may be one of the following constants:
xa-ok: Normal execution
xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction
branch may have been heuristically completed.
xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was committed.
xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was rolled back.
xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified
transaction branch was partially committed and partially rolled back.
xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified
reason.
xa-rbtimeout: The work represented by this transaction branch took too long.
</doc>
</result>
</command>
<!-- - Command: dtx.set-timeout - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="set-timeout" code="0xa" label="Set dtx timeout value">
<doc>
Sets the specified transaction branch timeout value in seconds.
</doc>
<rule name="effective">
<doc>
Once set, this timeout value is effective until this command is reinvoked with a different
value.
</doc>
</rule>
<rule name="reset">
<doc>
A value of zero resets the timeout value to the default value.
</doc>
</rule>
<implement role="server" handle="MAY" />
<field name="xid" type="xid" label="Transaction xid" required="true">
<doc>
Specifies the xid of the transaction branch for setting the timeout.
</doc>
<exception name="unknown-xid" error-code="not-found">
<doc>
If xid is unknown (the transaction branch has not been started or has already been
ended) then the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="timeout" type="uint32" label="Dtx timeout in seconds" required="true">
<doc>
The transaction timeout value in seconds.
</doc>
</field>
</command>
</class>
<!-- == Class: exchange ====================================================================== -->
<class name="exchange" code="0x7" label="work with exchanges">
<doc>
Exchanges match and distribute messages across queues. Exchanges can be configured in the
server or created at runtime.
</doc>
<doc type="grammar">
exchange = C:DECLARE
/ C:DELETE
/ C:QUERY
</doc>
<rule name="required-types">
<doc>
The server MUST implement these standard exchange types: fanout, direct.
</doc>
<doc type="scenario">
Client attempts to declare an exchange with each of these standard types.
</doc>
</rule>
<rule name="recommended-types">
<doc>
The server SHOULD implement these standard exchange types: topic, headers.
</doc>
<doc type="scenario">
Client attempts to declare an exchange with each of these standard types.
</doc>
</rule>
<rule name="required-instances">
<doc>
The server MUST, in each virtual host, pre-declare an exchange instance for each standard
exchange type that it implements, where the name of the exchange instance, if defined, is
"amq." followed by the exchange type name.
The server MUST, in each virtual host, pre-declare at least two direct exchange instances:
one named "amq.direct", the other with no public name that serves as a default exchange for
publish commands (such as message.transfer).
</doc>
<doc type="scenario">
Client creates a temporary queue and attempts to bind to each required exchange instance
("amq.fanout", "amq.direct", "amq.topic", and "amq.headers" if those types are defined).
</doc>
</rule>
<rule name="default-exchange">
<doc>
The server MUST pre-declare a direct exchange with no public name to act as the default
exchange for content publish commands (such as message.transfer) and for default queue
bindings.
</doc>
<doc type="scenario">
Client checks that the default exchange is active by publishing a message with a suitable
routing key but without specifying the exchange name, then ensuring that the message arrives
in the queue correctly.
</doc>
</rule>
<rule name="default-access">
<doc>
The default exchange MUST NOT be accessible to the client except by specifying an empty
exchange name in a content publish command (such as message.transfer). That is, the server
must not let clients explicitly bind, unbind, delete, or make any other reference to this
exchange.
</doc>
</rule>
<rule name="extensions">
<doc>
The server MAY implement other exchange types as wanted.
</doc>
</rule>
<role name="server" implement="MUST" />
<role name="client" implement="MUST" />
<domain name="name" type="str8" label="exchange name">
<doc>
The exchange name is a client-selected string that identifies the exchange for publish
commands. Exchange names may consist of any mixture of digits, letters, and underscores.
Exchange names are scoped by the virtual host.
</doc>
</domain>
<!-- - Command: exchange.declare - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="declare" code="0x1" label="verify exchange exists, create if needed">
<doc>
This command creates an exchange if it does not already exist, and if the exchange exists,
verifies that it is of the correct and expected class.
</doc>
<rule name="minimum">
<doc>
The server SHOULD support a minimum of 16 exchanges per virtual host and ideally, impose
no limit except as defined by available resources.
</doc>
<doc type="scenario">
The client creates as many exchanges as it can until the server reports an error; the
number of exchanges successfully created must be at least sixteen.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="exchange" type="name" required="true">
<exception name="reserved-names" error-code="not-allowed">
<doc>
Exchange names starting with "amq." are reserved for pre-declared and standardized
exchanges. The client MUST NOT attempt to create an exchange starting with "amq.".
</doc>
</exception>
<exception name="exchange-name-required" error-code="invalid-argument">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</exception>
</field>
<field name="type" type="str8" label="exchange type" required="true">
<doc>
Each exchange belongs to one of a set of exchange types implemented by the server. The
exchange types define the functionality of the exchange - i.e. how messages are routed
through it. It is not valid or meaningful to attempt to change the type of an existing
exchange.
</doc>
<exception name="typed" error-code="not-allowed">
<doc>
Exchanges cannot be redeclared with different types. The client MUST NOT attempt to
redeclare an existing exchange with a different type than used in the original
exchange.declare command.
</doc>
</exception>
<exception name="exchange-type-not-found" error-code="not-found">
<doc>
If the client attempts to create an exchange which the server does not recognize, an
exception MUST be sent.
</doc>
</exception>
</field>
<field name="alternate-exchange" type="name" label= "exchange name for unroutable messages">
<doc>
In the event that a message cannot be routed, this is the name of the exchange to which
the message will be sent. Messages transferred using message.transfer will be routed to
the alternate-exchange only if they are sent with the "none" accept-mode, and the
discard-unroutable delivery property is set to false, and there is no queue to route to
for the given message according to the bindings on this exchange.
</doc>
<rule name="empty-name">
<doc>
If alternate-exchange is not set (its name is an empty string), unroutable messages
that would be sent to the alternate-exchange MUST be dropped silently.
</doc>
</rule>
<exception name="pre-existing-exchange" error-code="not-allowed">
<doc>
If the alternate-exchange is not empty and if the exchange already exists with a
different alternate-exchange, then the declaration MUST result in an exception.
</doc>
</exception>
<rule name="double-failure">
<doc>
A message which is being routed to a alternate exchange, MUST NOT be re-routed to a
secondary alternate exchange if it fails to route in the primary alternate exchange.
After such a failure, the message MUST be dropped. This prevents looping.
</doc>
</rule>
</field>
<field name="passive" type="bit" label="do not create exchange">
<doc>
If set, the server will not create the exchange. The client can use this to check whether
an exchange exists without modifying the server state.
</doc>
<exception name="not-found" error-code="not-found">
<doc>
If set, and the exchange does not already exist, the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="durable" type="bit" label="request a durable exchange">
<doc>
If set when creating a new exchange, the exchange will be marked as durable. Durable
exchanges remain active when a server restarts. Non-durable exchanges (transient
exchanges) are purged if/when a server restarts.
</doc>
<rule name="support">
<doc>
The server MUST support both durable and transient exchanges.
</doc>
</rule>
<rule name="sticky">
<doc>
The server MUST ignore the durable field if the exchange already exists.
</doc>
</rule>
</field>
<field name="auto-delete" type="bit" label="auto-delete when unused">
<doc>
If set, the exchange is deleted automatically when there remain no bindings between the
exchange and any queue. Such an exchange will not be automatically deleted until at least
one binding has been made to prevent the immediate deletion of the exchange upon creation.
</doc>
<rule name="sticky">
<doc>
The server MUST ignore the auto-delete field if the exchange already exists.
</doc>
</rule>
</field>
<field name="arguments" type="map" label="arguments for declaration">
<doc>
A set of arguments for the declaration. The syntax and semantics of these arguments
depends on the server implementation. This field is ignored if passive is 1.
</doc>
<exception name="unknown-argument" error-code="not-implemented">
<doc>
If the arguments field contains arguments which are not understood by the server,
it MUST raise an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: exchange.delete - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="delete" code="0x2" label="delete an exchange">
<doc>
This command deletes an exchange. When an exchange is deleted all queue bindings on the
exchange are cancelled.
</doc>
<implement role="server" handle="MUST" />
<field name="exchange" type="name" required="true">
<exception name="exists" error-code="not-found">
<doc>
The client MUST NOT attempt to delete an exchange that does not exist.
</doc>
</exception>
<exception name="exchange-name-required" error-code="invalid-argument">
<doc>
The name of the exchange MUST NOT be a missing or empty string.
</doc>
</exception>
<exception name="used-as-alternate" error-code="not-allowed">
<doc>
An exchange MUST NOT be deleted if it is in use as an alternate-exchange by a queue or
by another exchange.
</doc>
</exception>
</field>
<field name="if-unused" type="bit" label="delete only if unused">
<doc>
If set, the server will only delete the exchange if it has no queue bindings. If the
exchange has queue bindings the server does not delete it but raises an exception
instead.
</doc>
<exception name="exchange-in-use" error-code="precondition-failed">
<doc>
If the exchange has queue bindings, and the if-unused flag is set, the server MUST NOT
delete the exchange, but MUST raise and exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: exchange.query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="query" code="0x3" label="request information about an exchange">
<doc>
This command is used to request information on a particular exchange.
</doc>
<implement role="server" handle="MUST" />
<field name="name" type="str8" label="the exchange name">
<doc>
The name of the exchange for which information is requested. If not specified explicitly
the default exchange is implied.
</doc>
</field>
<result>
<struct name="exchange-query-result" size="4" code="0x1" pack="2">
<doc>
This is sent in response to a query request and conveys information on a particular
exchange.
</doc>
<field name="type" type="str8" label="indicate the exchange type">
<doc>
The type of the exchange. Will be empty if the exchange is not found.
</doc>
</field>
<field name="durable" type="bit" label="indicate the durability">
<doc>
The durability of the exchange, i.e. if set the exchange is durable. Will not be set
if the exchange is not found.
</doc>
</field>
<field name="not-found" type="bit" label="indicate an unknown exchange">
<doc>
If set, the exchange for which information was requested is not known.
</doc>
</field>
<field name="arguments" type="map" label="other unspecified exchange properties">
<doc>
A set of properties of the exchange whose syntax and semantics depends on the server
implementation. Will be empty if the exchange is not found.
</doc>
</field>
</struct>
</result>
</command>
<!-- - Command: exchange.bind - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="bind" code="0x4" label="bind queue to an exchange">
<doc> This command binds a queue to an exchange. Until a queue is bound it will not receive
any messages. In a classic messaging model, store-and-forward queues are bound to a direct
exchange and subscription queues are bound to a topic exchange. </doc>
<rule name="duplicates">
<doc>
A server MUST ignore duplicate bindings - that is, two or more bind commands with the
same exchange, queue, and binding-key - without treating these as an error. The value of
the arguments used for the binding MUST NOT be altered by subsequent binding requests.
</doc>
<doc type="scenario">
A client binds a named queue to an exchange. The client then repeats the bind (with
identical exchange, queue, and binding-key). The second binding should use a different
value for the arguments field.
</doc>
</rule>
<rule name="durable-exchange">
<doc> Bindings between durable queues and durable exchanges are automatically durable and
the server MUST restore such bindings after a server restart. </doc>
<doc type="scenario"> A server creates a named durable queue and binds it to a durable
exchange. The server is restarted. The client then attempts to use the queue/exchange
combination. </doc>
</rule>
<rule name="binding-count">
<doc> The server SHOULD support at least 4 bindings per queue, and ideally, impose no limit
except as defined by available resources. </doc>
<doc type="scenario"> A client creates a named queue and attempts to bind it to 4 different
exchanges. </doc>
</rule>
<rule name="multiple-bindings">
<doc> Where more than one binding exists between a particular exchange instance and a
particular queue instance any given message published to that exchange should be delivered
to that queue at most once, regardless of how many distinct bindings match. </doc>
<doc type="scenario"> A client creates a named queue and binds it to the same topic exchange
at least three times using intersecting binding-keys (for example, "animals.*",
"animals.dogs.*", "animal.dogs.chihuahua"). Verify that a message matching all the
bindings (using previous example, routing key = "animal.dogs.chihuahua") is delivered once
only. </doc>
</rule>
<implement role="server" handle="MUST"/>
<field name="queue" type="queue.name" required="true">
<doc> Specifies the name of the queue to bind. </doc>
<exception name="empty-queue" error-code="invalid-argument">
<doc> A client MUST NOT be allowed to bind a non-existent and unnamed queue (i.e. empty
queue name) to an exchange. </doc>
<doc type="scenario"> A client attempts to bind with an unnamed (empty) queue name to an
exchange. </doc>
</exception>
<exception name="queue-existence" error-code="not-found">
<doc> A client MUST NOT be allowed to bind a non-existent queue (i.e. not previously
declared) to an exchange. </doc>
<doc type="scenario"> A client attempts to bind an undeclared queue name to an exchange.
</doc>
</exception>
</field>
<field name="exchange" type="name" label="name of the exchange to bind to" required="true">
<exception name="exchange-existence" error-code="not-found">
<doc> A client MUST NOT be allowed to bind a queue to a non-existent exchange. </doc>
<doc type="scenario"> A client attempts to bind a named queue to a undeclared exchange.
</doc>
</exception>
<exception name="exchange-name-required" error-code="invalid-argument">
<doc> The name of the exchange MUST NOT be a blank or empty string. </doc>
</exception>
</field>
<field name="binding-key" type="str8"
label="identifies a binding between a given exchange and queue" required="true">
<doc> The binding-key uniquely identifies a binding between a given (exchange, queue) pair.
Depending on the exchange configuration, the binding key may be matched against the
message routing key in order to make routing decisions. The match algorithm depends on the
exchange type. Some exchange types may ignore the binding key when making routing
decisions. Refer to the specific exchange type documentation. The meaning of an empty
binding key depends on the exchange implementation. </doc>
</field>
<field name="arguments" type="map" label="arguments for binding">
<doc> A set of arguments for the binding. The syntax and semantics of these arguments
depends on the exchange class. </doc>
<exception name="unknown-argument" error-code="not-implemented">
<doc> If the arguments field contains arguments which are not understood by the server, it
MUST raise an exception. </doc>
</exception>
</field>
</command>
<!-- - Command: exchange.unbind - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="unbind" code="0x5" label="unbind a queue from an exchange">
<doc>
This command unbinds a queue from an exchange.
</doc>
<implement role="server" handle="MUST" />
<field name="queue" type="queue.name" required="true">
<doc>
Specifies the name of the queue to unbind.
</doc>
<exception name="non-existent-queue" error-code="not-found">
<doc>
If the queue does not exist the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="exchange" type="name" required="true">
<doc>
The name of the exchange to unbind from.
</doc>
<exception name="non-existent-exchange" error-code="not-found">
<doc>
If the exchange does not exist the server MUST raise an exception.
</doc>
</exception>
<exception name="exchange-name-required" error-code="invalid-argument">
<doc>
The name of the exchange MUST NOT be a blank or empty string.
</doc>
</exception>
</field>
<field name="binding-key" type="str8" label="the key of the binding" required="true">
<doc>
Specifies the binding-key of the binding to unbind.
</doc>
<exception name="non-existent-binding-key" error-code="not-found">
<doc>
If there is no matching binding-key the server MUST raise an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: exchange.bound - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="bound" code="0x6" label="request information about bindings to an exchange">
<doc>
This command is used to request information on the bindings to a particular exchange.
</doc>
<implement role="server" handle="MUST" />
<field name="exchange" type="str8" label="the exchange name">
<doc>
The name of the exchange for which binding information is being requested. If not
specified explicitly the default exchange is implied.
</doc>
</field>
<field name="queue" type="str8" label="a queue name" required="true">
<doc>
If populated then determine whether the given queue is bound to the exchange.
</doc>
</field>
<field name="binding-key" type="str8" label="a binding-key">
<doc>
If populated defines the binding-key of the binding of interest, if not populated the
request will ignore the binding-key on bindings when searching for a match.
</doc>
</field>
<field name="arguments" type="map" label="a set of binding arguments">
<doc>
If populated defines the arguments of the binding of interest if not populated the request
will ignore the arguments on bindings when searching for a match
</doc>
</field>
<result>
<struct name="exchange-bound-result" size="4" code="0x2" pack="2">
<field name="exchange-not-found" type="bit" label="indicate an unknown exchange">
<doc>
If set, the exchange for which information was requested is not known.
</doc>
</field>
<field name="queue-not-found" type="bit" label="indicate an unknown queue">
<doc>
If set, the queue specified is not known.
</doc>
</field>
<field name="queue-not-matched" type="bit" label="indicate no matching queue">
<doc>
A bit which if set indicates that no binding was found from the specified exchange to
the specified queue.
</doc>
</field>
<field name="key-not-matched" type="bit" label="indicate no matching binding-key">
<doc>
A bit which if set indicates that no binding was found from the specified exchange
with the specified binding-key.
</doc>
</field>
<field name="args-not-matched" type="bit" label="indicate no matching arguments">
<doc>
A bit which if set indicates that no binding was found from the specified exchange
with the specified arguments.
</doc>
</field>
</struct>
</result>
</command>
</class>
<!-- == Class: queue ========================================================================= -->
<class name="queue" code="0x8" label="work with queues">
<doc>
Queues store and forward messages. Queues can be configured in the server or created at
runtime. Queues must be attached to at least one exchange in order to receive messages from
publishers.
</doc>
<doc type="grammar">
queue = C:DECLARE
/ C:BIND
/ C:PURGE
/ C:DELETE
/ C:QUERY
/ C:UNBIND
</doc>
<rule name="any-content">
<doc>
A server MUST allow any content class to be sent to any queue, in any mix, and queue and
deliver these content classes independently. Note that all commands that fetch content off
queues are specific to a given content class.
</doc>
<doc type="scenario">
Client creates an exchange of each standard type and several queues that it binds to each
exchange. It must then successfully send each of the standard content types to each of the
available queues.
</doc>
</rule>
<role name="server" implement="MUST" />
<role name="client" implement="MUST" />
<domain name="name" type="str8" label="queue name">
<doc>
The queue name identifies the queue within the virtual host. Queue names must have a length
of between 1 and 255 characters inclusive, must start with a digit, letter or underscores
('_') character, and must be otherwise encoded in UTF-8.
</doc>
</domain>
<!-- - Command: queue.declare - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="declare" code="0x1" label="declare queue">
<doc>
This command creates or checks a queue. When creating a new queue the client can specify
various properties that control the durability of the queue and its contents, and the level
of sharing for the queue.
</doc>
<rule name="default-binding">
<doc>
The server MUST create a default binding for a newly-created queue to the default
exchange, which is an exchange of type 'direct' and use the queue name as the binding-key.
</doc>
<doc type="scenario">
Client creates a new queue, and then without explicitly binding it to an exchange,
attempts to send a message through the default exchange binding, i.e. publish a message to
the empty exchange, with the queue name as binding-key.
</doc>
</rule>
<rule name="minimum-queues">
<doc>
The server SHOULD support a minimum of 256 queues per virtual host and ideally, impose no
limit except as defined by available resources.
</doc>
<doc type="scenario">
Client attempts to create as many queues as it can until the server reports an error. The
resulting count must at least be 256.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="queue" type="name" required="true">
<exception name="reserved-prefix" error-code="not-allowed">
<doc>
Queue names starting with "amq." are reserved for pre-declared and standardized server
queues. A client MUST NOT attempt to declare a queue with a name that starts with "amq."
and the passive option set to zero.
</doc>
<doc type="scenario">
A client attempts to create a queue with a name starting with "amq." and with the
passive option set to zero.
</doc>
</exception>
</field>
<field name="alternate-exchange" type="exchange.name"
label= "exchange name for messages with exceptions">
<doc>
The alternate-exchange field specifies how messages on this queue should be treated when
they are rejected by a subscriber, or when they are orphaned by queue deletion. When
present, rejected or orphaned messages MUST be routed to the alternate-exchange. In all
cases the messages MUST be removed from the queue.
</doc>
<exception name="pre-existing-exchange" error-code="not-allowed">
<doc>
If the alternate-exchange is not empty and if the queue already exists with a different
alternate-exchange, then the declaration MUST result in an exception.
</doc>
</exception>
<exception name="unknown-exchange" error-code="not-found">
<doc>
if the alternate-exchange does not match the name of any existing exchange on the
server, then an exception must be raised.
</doc>
</exception>
</field>
<field name="passive" type="bit" label="do not create queue">
<doc>
If set, the server will not create the queue. This field allows the client to assert the
presence of a queue without modifying the server state.
</doc>
<exception name="passive" error-code="not-found">
<doc>
The client MAY ask the server to assert that a queue exists without creating the queue
if not. If the queue does not exist, the server treats this as a failure.
</doc>
<doc type="scenario">
Client declares an existing queue with the passive option and expects the command to
succeed. Client then attempts to declare a non-existent queue with the passive option,
and the server must close the session with the correct exception.
</doc>
</exception>
</field>
<field name="durable" type="bit" label="request a durable queue">
<doc>
If set when creating a new queue, the queue will be marked as durable. Durable queues
remain active when a server restarts. Non-durable queues (transient queues) are purged
if/when a server restarts. Note that durable queues do not necessarily hold persistent
messages, although it does not make sense to send persistent messages to a transient
queue.
</doc>
<rule name="persistence">
<doc>
The queue definition MUST survive the server losing all transient memory, e.g. a
machine restart.
</doc>
<doc type="scenario">
Client creates a durable queue; server is then restarted. Client then attempts to send
message to the queue. The message should be successfully delivered.
</doc>
</rule>
<rule name="types">
<doc>
The server MUST support both durable and transient queues.
</doc>
<doc type="scenario">
A client creates two named queues, one durable and one transient.
</doc>
</rule>
<rule name="pre-existence">
<doc>
The server MUST ignore the durable field if the queue already exists.
</doc>
<doc type="scenario">
A client creates two named queues, one durable and one transient. The client then
attempts to declare the two queues using the same names again, but reversing the value
of the durable flag in each case. Verify that the queues still exist with the original
durable flag values.
</doc>
</rule>
</field>
<field name="exclusive" type="bit" label="request an exclusive queue">
<doc>
Exclusive queues can only be used from one session at a time. Once a session
declares an exclusive queue, that queue cannot be used by any other session until the
declaring session closes.
</doc>
<rule name="types">
<doc>
The server MUST support both exclusive (private) and non-exclusive (shared) queues.
</doc>
<doc type="scenario">
A client creates two named queues, one exclusive and one non-exclusive.
</doc>
</rule>
<exception name="in-use" error-code="resource-locked">
<doc>
If the server receives a declare, bind, consume or get request for a queue that has been
declared as exclusive by an existing client session, it MUST raise an exception.
</doc>
<doc type="scenario">
A client declares an exclusive named queue. A second client on a different session
attempts to declare a queue of the same name.
</doc>
</exception>
</field>
<field name="auto-delete" type="bit" label="auto-delete queue when unused">
<doc>
If this field is set and the exclusive field is also set, then the queue MUST be deleted
when the session closes.
If this field is set and the exclusive field is not set the queue is deleted when all
the consumers have finished using it. Last consumer can be cancelled either explicitly
or because its session is closed. If there was no consumer ever on the queue, it won't
be deleted.
</doc>
<rule name="pre-existence">
<doc>
The server MUST ignore the auto-delete field if the queue already exists.
</doc>
<doc type="scenario">
A client creates two named queues, one as auto-delete and one explicit-delete. The
client then attempts to declare the two queues using the same names again, but reversing
the value of the auto-delete field in each case. Verify that the queues still exist with
the original auto-delete flag values.
</doc>
</rule>
</field>
<field name="arguments" type="map" label="arguments for declaration">
<doc>
A set of arguments for the declaration. The syntax and semantics of these arguments
depends on the server implementation. This field is ignored if passive is 1.
</doc>
<exception name="unknown-argument" error-code="not-implemented">
<doc>
If the arguments field contains arguments which are not understood by the server,
it MUST raise an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: queue.delete - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="delete" code="0x2" label="delete a queue">
<doc>
This command deletes a queue. When a queue is deleted any pending messages are sent to the
alternate-exchange if defined, or discarded if it is not.
</doc>
<implement role="server" handle="MUST" />
<field name="queue" type="name" required="true">
<doc>
Specifies the name of the queue to delete.
</doc>
<exception name="empty-name" error-code="invalid-argument">
<doc>
If the queue name in this command is empty, the server MUST raise an exception.
</doc>
</exception>
<exception name="queue-exists" error-code="not-found">
<doc>
The queue must exist. If the client attempts to delete a non-existing queue the server
MUST raise an exception.
</doc>
</exception>
</field>
<field name="if-unused" type="bit" label="delete only if unused">
<doc>
If set, the server will only delete the queue if it has no consumers. If the queue has
consumers the server does does not delete it but raises an exception instead.
</doc>
<exception name="if-unused-flag" error-code="precondition-failed">
<doc>
The server MUST respect the if-unused flag when deleting a queue.
</doc>
</exception>
</field>
<field name="if-empty" type="bit" label="delete only if empty">
<doc>
If set, the server will only delete the queue if it has no messages.
</doc>
<exception name="not-empty" error-code="precondition-failed">
<doc>
If the queue is not empty the server MUST raise an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: queue.purge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="purge" code="0x3" label="purge a queue">
<doc>
This command removes all messages from a queue. It does not cancel subscribers. Purged
messages are deleted without any formal "undo" mechanism.
</doc>
<rule name="empty">
<doc>
A call to purge MUST result in an empty queue.
</doc>
</rule>
<rule name="pending-messages">
<doc>
The server MUST NOT purge messages that have already been sent to a client but not yet
accepted.
</doc>
</rule>
<rule name="purge-recovery">
<doc>
The server MAY implement a purge queue or log that allows system administrators to recover
accidentally-purged messages. The server SHOULD NOT keep purged messages in the same
storage spaces as the live messages since the volumes of purged messages may get very
large.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="queue" type="name" required="true">
<doc>
Specifies the name of the queue to purge.
</doc>
<exception name="empty-name" error-code="invalid-argument">
<doc>
If the the queue name in this command is empty, the server MUST raise an exception.
</doc>
</exception>
<exception name="queue-exists" error-code="not-found">
<doc>
The queue MUST exist. Attempting to purge a non-existing queue MUST cause an exception.
</doc>
</exception>
</field>
</command>
<!-- - Command: queue.query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="query" code="0x4" label="request information about a queue">
<doc>
This command requests information about a queue.
</doc>
<implement role="server" handle="MUST" />
<field name="queue" type="name" label="the queried queue" required="true"/>
<result>
<struct name="queue-query-result" size="4" code="0x1" pack="2">
<doc>
This is sent in response to queue.query, and conveys the requested information about a
queue. If no queue with the specified name exists then none of the fields within the
returned result struct will be populated.
</doc>
<field name="queue" type="name" required="true">
<doc>
Reports the name of the queue.
</doc>
</field>
<field name="alternate-exchange" type="exchange.name" />
<field name="durable" type="bit" />
<field name="exclusive" type="bit" />
<field name="auto-delete" type="bit" />
<field name="arguments" type="map" />
<field name="message-count" type="uint32" label="number of messages in queue"
required="true">
<doc> Reports the number of messages in the queue. </doc>
</field>
<field name="subscriber-count" type="uint32" label="number of subscribers"
required="true">
<doc>
Reports the number of subscribers for the queue.
</doc>
</field>
</struct>
</result>
</command>
</class>
<!-- == Class: file ========================================================================== -->
<class name="file" code="0x9" label="work with file content">
<doc>
The file class provides commands that support reliable file transfer. File messages have a
specific set of properties that are required for interoperability with file transfer
applications. File messages and acknowledgements are subject to session transactions. Note
that the file class does not provide message browsing commands; these are not compatible with
the staging model. Applications that need browsable file transfer should use Message content
and the Message class.
</doc>
<doc type="grammar">
file = C:QOS S:QOS-OK
/ C:CONSUME S:CONSUME-OK
/ C:CANCEL
/ C:OPEN S:OPEN-OK C:STAGE content
/ S:OPEN C:OPEN-OK S:STAGE content
/ C:PUBLISH
/ S:DELIVER
/ S:RETURN
/ C:ACK
/ C:REJECT
</doc>
<rule name="reliable-storage">
<doc>
The server MUST make a best-effort to hold file messages on a reliable storage mechanism.
</doc>
</rule>
<rule name="no-discard">
<doc>
The server MUST NOT discard a file message in case of a queue overflow. The server MUST use
the Session.Flow command to slow or stop a file message publisher when necessary.
</doc>
</rule>
<rule name="priority-levels">
<doc>
The server MUST implement at least 2 priority levels for file messages, where priorities 0-4
and 5-9 are treated as two distinct levels. The server MAY implement up to 10 priority
levels.
</doc>
</rule>
<rule name="acknowledgement-support">
<doc>
The server MUST support both automatic and explicit acknowledgements on file content.
</doc>
</rule>
<role name="server" implement="MAY" />
<role name="client" implement="MAY" />
<!-- These are the properties for a File content -->
<struct name="file-properties" size="4" code="0x1" pack="2">
<field name="content-type" type="str8" label="MIME content type" />
<field name="content-encoding" type="str8" label="MIME content encoding" />
<field name="headers" type="map" label="message header field table" />
<field name="priority" type="uint8" label="message priority, 0 to 9" />
<field name="reply-to" type="str8" label="destination to reply to" />
<field name="message-id" type="str8" label="application message identifier" />
<field name="filename" type="str8" label="message filename" />
<field name="timestamp" type="datetime" label="message timestamp" />
<!-- This field is deprecated pending review -->
<field name="cluster-id" type="str8" label="intra-cluster routing identifier" />
</struct>
<domain name="return-code" type="uint16" label="return code from server">
<doc>
The return code. The AMQP return codes are defined by this enum.
</doc>
<enum>
<choice name="content-too-large" value="311">
<doc>
The client attempted to transfer content larger than the server could accept.
</doc>
</choice>
<choice name="no-route" value="312">
<doc>
The exchange cannot route a message, most likely due to an invalid routing key. Only
when the mandatory flag is set.
</doc>
</choice>
<choice name="no-consumers" value="313">
<doc>
The exchange cannot deliver to a consumer when the immediate flag is set. As a result of
pending data on the queue or the absence of any consumers of the queue.
</doc>
</choice>
</enum>
</domain>
<!-- - Command: file.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="qos" code="0x1" label="specify quality of service">
<doc>
This command requests a specific quality of service. The QoS can be specified for the
current session or for all sessions on the connection. The particular properties and
semantics of a qos command always depend on the content class semantics. Though the qos
command could in principle apply to both peers, it is currently meaningful only for the
server.
</doc>
<implement role="server" handle="MUST" />
<response name="qos-ok" />
<field name="prefetch-size" type="uint32" label="pre-fetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Pre-fetching gives a performance improvement. This field
specifies the pre-fetch window size in octets. May be set to zero, meaning "no specific
limit". Note that other pre-fetch limits may still apply. The prefetch-size is ignored if
the no-ack option is set.
</doc>
</field>
<field name="prefetch-count" type="uint16" label="pre-fetch window in messages">
<doc>
Specifies a pre-fetch window in terms of whole messages. This is compatible with some file
API implementations. This field may be used in combination with the prefetch-size field; a
message will only be sent in advance if both pre-fetch windows (and those at the session
and connection level) allow it. The prefetch-count is ignored if the no-ack option is set.
</doc>
<rule name="prefetch-discretion">
<doc>
The server MAY send less data in advance than allowed by the client's specified
pre-fetch windows but it MUST NOT send more.
</doc>
</rule>
</field>
<field name="global" type="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</command>
<!-- - Command: file.qos-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="qos-ok" code="0x2" label="confirm the requested qos">
<doc>
This command tells the client that the requested QoS levels could be handled by the server.
The requested QoS applies to all active consumers until a new QoS is defined.
</doc>
<implement role="client" handle="MUST" />
</command>
<!-- - Command: file.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="consume" code="0x3" label="start a queue consumer">
<doc>
This command asks the server to start a "consumer", which is a transient request for
messages from a specific queue. Consumers last as long as the session they were created on,
or until the client cancels them.
</doc>
<rule name="min-consumers">
<doc>
The server SHOULD support at least 16 consumers per queue, unless the queue was declared
as private, and ideally, impose no limit except as defined by available resources.
</doc>
</rule>
<implement role="server" handle="MUST" />
<response name="consume-ok" />
<field name="queue" type="queue.name">
<doc>
Specifies the name of the queue to consume from.
</doc>
<exception name="queue-exists-if-empty" error-code="not-allowed">
<doc>
If the queue name in this command is empty, the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="consumer-tag" type="str8">
<doc>
Specifies the identifier for the consumer. The consumer tag is local to a connection, so
two clients can use the same consumer tags.
</doc>
<exception name="not-existing-consumer" error-code="not-allowed">
<doc>
The tag MUST NOT refer to an existing consumer. If the client attempts to create two
consumers with the same non-empty tag the server MUST raise an exception.
</doc>
</exception>
<exception name="not-empty-consumer-tag" error-code="not-allowed">
<doc>
The client MUST NOT specify a tag that is empty or blank.
</doc>
<doc type="scenario">
Attempt to create a consumers with an empty tag.
</doc>
</exception>
</field>
<field name="no-local" type="bit">
<doc>If the no-local field is set the server will not send messages to the connection that
published them.</doc>
</field>
<field name="no-ack" type="bit" label="no acknowledgement needed">
<doc>
If this field is set the server does not expect acknowledgements for messages. That is,
when a message is delivered to the client the server automatically and silently
acknowledges it on behalf of the client. This functionality increases performance but at
the cost of reliability. Messages can get lost if a client dies before it can deliver them
to the application.
</doc>
</field>
<field name="exclusive" type="bit" label="request exclusive access">
<doc>
Request exclusive consumer access, meaning only this consumer can access the queue.
</doc>
<exception name="in-use" error-code="resource-locked">
<doc>
If the server cannot grant exclusive access to the queue when asked, - because there are
other consumers active - it MUST raise an exception.
</doc>
</exception>
</field>
<field name="nowait" type="bit" label="do not send a reply command">
<doc>
If set, the server will not respond to the command. The client should not wait for a reply
command. If the server could not complete the command it will raise an exception.
</doc>
</field>
<field name="arguments" type="map" label="arguments for consuming">
<doc>
A set of arguments for the consume. The syntax and semantics of these arguments depends on
the providers implementation.
</doc>
</field>
</command>
<command name="consume-ok" code="0x4" label="confirm a new consumer">
<doc>
This command provides the client with a consumer tag which it MUST use in commands that work
with the consumer.
</doc>
<implement role="client" handle="MUST" />
<field name="consumer-tag" type="str8">
<doc>
Holds the consumer tag specified by the client or provided by the server.
</doc>
</field>
</command>
<!-- - Command: file.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="cancel" code="0x5" label="end a queue consumer">
<doc>
This command cancels a consumer. This does not affect already delivered messages, but it
does mean the server will not send any more messages for that consumer.
</doc>
<implement role="server" handle="MUST" />
<field name="consumer-tag" type="str8">
<doc>
the identifier of the consumer to be cancelled.
</doc>
</field>
</command>
<!-- - Command: file.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="open" code="0x6" label="request to start staging">
<doc>
This command requests permission to start staging a message. Staging means sending the
message into a temporary area at the recipient end and then delivering the message by
referring to this temporary area. Staging is how the protocol handles partial file transfers
- if a message is partially staged and the connection breaks, the next time the sender
starts to stage it, it can restart from where it left off.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<response name="open-ok" />
<field name="identifier" type="str8" label="staging identifier">
<doc>
This is the staging identifier. This is an arbitrary string chosen by the sender. For
staging to work correctly the sender must use the same staging identifier when staging the
same message a second time after recovery from a failure. A good choice for the staging
identifier would be the SHA1 hash of the message properties data (including the original
filename, revised time, etc.).
</doc>
</field>
<field name="content-size" type="uint64" label="message content size">
<doc>
The size of the content in octets. The recipient may use this information to allocate or
check available space in advance, to avoid "disk full" errors during staging of very large
messages.
</doc>
<rule name="content-size">
<doc>
The sender MUST accurately fill the content-size field. Zero-length content is
permitted.
</doc>
</rule>
</field>
</command>
<!-- - Command: file.open-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="open-ok" code="0x7" label="confirm staging ready">
<doc>
This command confirms that the recipient is ready to accept staged data. If the message was
already partially-staged at a previous time the recipient will report the number of octets
already staged.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<response name="stage" />
<field name="staged-size" type="uint64" label="already staged amount">
<doc>
The amount of previously-staged content in octets. For a new message this will be zero.
</doc>
<rule name="behavior">
<doc>
The sender MUST start sending data from this octet offset in the message, counting from
zero.
</doc>
</rule>
<rule name="staging">
<doc>
The recipient MAY decide how long to hold partially-staged content and MAY implement
staging by always discarding partially-staged content. However if it uses the file
content type it MUST support the staging commands.
</doc>
</rule>
</field>
</command>
<!-- - Command: file.stage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="stage" code="0x8" label="stage message content">
<doc>
This command stages the message, sending the message content to the recipient from the octet
offset specified in the Open-Ok command.
</doc>
<implement role="server" handle="MUST" />
<implement role="client" handle="MUST" />
<segments>
<header required="true">
<entry type="file-properties"/>
</header>
<body/>
</segments>
</command>
<!-- - Command: file.publish - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="publish" code="0x9" label="publish a message">
<doc>
This command publishes a staged file message to a specific exchange. The file message will
be routed to queues as defined by the exchange configuration and distributed to any active
consumers when the transaction, if any, is committed.
</doc>
<implement role="server" handle="MUST" />
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange to publish to. The exchange name can be empty, meaning
the default exchange. If the exchange name is specified, and that exchange does not exist,
the server will raise an exception.
</doc>
<rule name="default">
<doc>
The server MUST accept a blank exchange name to mean the default exchange.
</doc>
</rule>
<exception name="refusal" error-code="not-implemented">
<doc>
The exchange MAY refuse file content in which case it MUST send an exception.
</doc>
</exception>
</field>
<field name="routing-key" type="str8" label="Message routing key">
<doc>
Specifies the routing key for the message. The routing key is used for routing messages
depending on the exchange configuration.
</doc>
</field>
<field name="mandatory" type="bit" label="indicate mandatory routing">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue. If
this flag is set, the server will return an unroutable message with a Return command. If
this flag is zero, the server silently drops the message.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the mandatory flag.
</doc>
</rule>
</field>
<field name="immediate" type="bit" label="request immediate delivery">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue
consumer immediately. If this flag is set, the server will return an undeliverable message
with a Return command. If this flag is zero, the server will queue the message, but with
no guarantee that it will ever be consumed.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the immediate flag.
</doc>
</rule>
</field>
<field name="identifier" type="str8" label="staging identifier">
<doc>
This is the staging identifier of the message to publish. The message must have been
staged. Note that a client can send the Publish command asynchronously without waiting for
staging to finish.
</doc>
</field>
</command>
<!-- - Command: file.return - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="return" code="0xa" label="return a failed message">
<doc>
This command returns an undeliverable message that was published with the "immediate" flag
set, or an unroutable message published with the "mandatory" flag set. The reply code and
text provide information about the reason that the message was undeliverable.
</doc>
<implement role="client" handle="MUST" />
<field name="reply-code" type="return-code" />
<field name="reply-text" type="str8" label="The localized reply text.">
<doc>
This text can be logged as an aid to resolving issues.
</doc>
</field>
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" type="str8" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
<segments>
<header required="true">
<entry type="file-properties"/>
</header>
<body/>
</segments>
</command>
<!-- - Command: file.deliver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="deliver" code="0xb" label="notify the client of a consumer message">
<doc>
This command delivers a staged file message to the client, via a consumer. In the
asynchronous message delivery model, the client starts a consumer using the consume command,
then the server responds with Deliver commands as and when messages arrive for that
consumer.
</doc>
<rule name="redelivery-tracking">
<doc>
The server SHOULD track the number of times a message has been delivered to clients and
when a message is redelivered a certain number of times - e.g. 5 times - without being
acknowledged, the server SHOULD consider the message to be non-processable (possibly
causing client applications to abort), and move the message to a dead letter queue.
</doc>
</rule>
<implement role="client" handle="MUST" />
<field name="consumer-tag" type="str8" />
<field name="delivery-tag" type="uint64" >
<doc>
The server-assigned and session-specific delivery tag
</doc>
<rule name="non-zero">
<doc>
The server MUST NOT use a zero value for delivery tags. Zero is reserved for client use,
meaning "all messages so far received".
</doc>
</rule>
</field>
<field name="redelivered" type="bit" label="Indicate possible duplicate delivery">
<doc>
This boolean flag indicates that the message may have been previously delivered to this
or another client.
</doc>
</field>
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" type="str8" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
<field name="identifier" type="str8" label="staging identifier">
<doc>
This is the staging identifier of the message to deliver. The message must have been
staged. Note that a server can send the Deliver command asynchronously without waiting for
staging to finish.
</doc>
</field>
</command>
<!-- - Command: file.ack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="ack" code="0xc" label="acknowledge one or more messages">
<doc>
This command acknowledges one or more messages delivered via the Deliver command. The client
can ask to confirm a single message or a set of messages up to and including a specific
message.
</doc>
<implement role="server" handle="MUST" />
<field name="delivery-tag" type="uint64" >
<doc>
The identifier of the message being acknowledged
</doc>
<rule name="session-local">
<doc>
The delivery tag is valid only within the session from which the message was received.
i.e. A client MUST NOT receive a message on one session and then acknowledge it on
another.
</doc>
</rule>
</field>
<field name="multiple" type="bit" label="acknowledge multiple messages">
<doc>
If set to 1, the delivery tag is treated as "up to and including", so that the client can
acknowledge multiple messages with a single command. If set to zero, the delivery tag
refers to a single message. If the multiple field is 1, and the delivery tag is zero,
tells the server to acknowledge all outstanding messages.
</doc>
<rule name="validation">
<doc>
The server MUST validate that a non-zero delivery-tag refers to an delivered message,
and raise an exception if this is not the case.
</doc>
</rule>
</field>
</command>
<!-- - Command: file.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="reject" code="0xd" label="reject an incoming message">
<doc>
This command allows a client to reject a message. It can be used to return untreatable
messages to their original queue. Note that file content is staged before delivery, so the
client will not use this command to interrupt delivery of a large message.
</doc>
<rule name="server-interpretation">
<doc>
The server SHOULD interpret this command as meaning that the client is unable to process
the message at this time.
</doc>
</rule>
<rule name="not-selection">
<doc>
A client MUST NOT use this command as a means of selecting messages to process. A rejected
message MAY be discarded or dead-lettered, not necessarily passed to another client.
</doc>
</rule>
<implement role="server" handle="MUST" />
<field name="delivery-tag" type="uint64">
<doc>
the identifier of the message to be rejected
</doc>
<rule name="session-local">
<doc>
The delivery tag is valid only within the session from which the message was received.
i.e. A client MUST NOT receive a message on one session and then reject it on another.
</doc>
</rule>
</field>
<field name="requeue" type="bit" label="requeue the message">
<doc>
If this field is zero, the message will be discarded. If this bit is 1, the server will
attempt to requeue the message.
</doc>
<rule name="requeue-strategy">
<doc>
The server MUST NOT deliver the message to the same client within the context of the
current session. The recommended strategy is to attempt to deliver the message to an
alternative consumer, and if that is not possible, to move the message to a dead-letter
queue. The server MAY use more sophisticated tracking to hold the message on the queue
and redeliver it to the same client at a later stage.
</doc>
</rule>
</field>
</command>
</class>
<!-- == Class: stream ======================================================================== -->
<class name="stream" code="0xa" label="work with streaming content">
<doc>
The stream class provides commands that support multimedia streaming. The stream class uses
the following semantics: one message is one packet of data; delivery is unacknowledged and
unreliable; the consumer can specify quality of service parameters that the server can try to
adhere to; lower-priority messages may be discarded in favor of high priority messages.
</doc>
<doc type="grammar">
stream = C:QOS S:QOS-OK
/ C:CONSUME S:CONSUME-OK
/ C:CANCEL
/ C:PUBLISH content
/ S:RETURN
/ S:DELIVER content
</doc>
<rule name="overflow-discard">
<doc>
The server SHOULD discard stream messages on a priority basis if the queue size exceeds some
configured limit.
</doc>
</rule>
<rule name="priority-levels">
<doc>
The server MUST implement at least 2 priority levels for stream messages, where priorities
0-4 and 5-9 are treated as two distinct levels. The server MAY implement up to 10 priority
levels.
</doc>
</rule>
<rule name="acknowledgement-support">
<doc>
The server MUST implement automatic acknowledgements on stream content. That is, as soon as
a message is delivered to a client via a Deliver command, the server must remove it from the
queue.
</doc>
</rule>
<role name="server" implement="MAY" />
<role name="client" implement="MAY" />
<!-- These are the properties for a Stream content -->
<struct name="stream-properties" size="4" code="0x1" pack="2">
<field name="content-type" type="str8" label="MIME content type" />
<field name="content-encoding" type="str8" label="MIME content encoding" />
<field name="headers" type="map" label="message header field table" />
<field name="priority" type="uint8" label="message priority, 0 to 9" />
<field name="timestamp" type="datetime" label="message timestamp" />
</struct>
<domain name="return-code" type="uint16" label="return code from server">
<doc>
The return code. The AMQP return codes are defined by this enum.
</doc>
<enum>
<choice name="content-too-large" value="311">
<doc>
The client attempted to transfer content larger than the server could accept.
</doc>
</choice>
<choice name="no-route" value="312">
<doc>
The exchange cannot route a message, most likely due to an invalid routing key. Only
when the mandatory flag is set.
</doc>
</choice>
<choice name="no-consumers" value="313">
<doc>
The exchange cannot deliver to a consumer when the immediate flag is set. As a result of
pending data on the queue or the absence of any consumers of the queue.
</doc>
</choice>
</enum>
</domain>
<!-- - Command: stream.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="qos" code="0x1" label="specify quality of service">
<doc>
This command requests a specific quality of service. The QoS can be specified for the
current session or for all sessions on the connection. The particular properties and
semantics of a qos command always depend on the content class semantics. Though the qos
command could in principle apply to both peers, it is currently meaningful only for the
server.
</doc>
<implement role="server" handle="MUST" />
<response name="qos-ok" />
<field name="prefetch-size" type="uint32" label="pre-fetch window in octets">
<doc>
The client can request that messages be sent in advance so that when the client finishes
processing a message, the following message is already held locally, rather than needing
to be sent within the session. Pre-fetching gives a performance improvement. This field
specifies the pre-fetch window size in octets. May be set to zero, meaning "no specific
limit". Note that other pre-fetch limits may still apply.
</doc>
</field>
<field name="prefetch-count" type="uint16" label="pre-fetch window in messages">
<doc>
Specifies a pre-fetch window in terms of whole messages. This field may be used in
combination with the prefetch-size field; a message will only be sent in advance if both
pre-fetch windows (and those at the session and connection level) allow it.
</doc>
</field>
<field name="consume-rate" type="uint32" label="transfer rate in octets/second">
<doc>
Specifies a desired transfer rate in octets per second. This is usually determined by the
application that uses the streaming data. A value of zero means "no limit", i.e. as
rapidly as possible.
</doc>
<rule name="ignore-prefetch">
<doc>
The server MAY ignore the pre-fetch values and consume rates, depending on the type of
stream and the ability of the server to queue and/or reply it.
</doc>
</rule>
<rule name="drop-by-priority">
<doc>
The server MAY drop low-priority messages in favor of high-priority messages.
</doc>
</rule>
</field>
<field name="global" type="bit" label="apply to entire connection">
<doc>
By default the QoS settings apply to the current session only. If this field is set, they
are applied to the entire connection.
</doc>
</field>
</command>
<!-- - Command: stream.qos-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="qos-ok" code="0x2" label="confirm the requested qos">
<doc>
This command tells the client that the requested QoS levels could be handled by the server.
The requested QoS applies to all active consumers until a new QoS is defined.
</doc>
<implement role="client" handle="MUST" />
</command>
<!-- - Command: stream.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="consume" code="0x3" label="start a queue consumer">
<doc>
This command asks the server to start a "consumer", which is a transient request for
messages from a specific queue. Consumers last as long as the session they were created on,
or until the client cancels them.
</doc>
<rule name="min-consumers">
<doc>
The server SHOULD support at least 16 consumers per queue, unless the queue was declared
as private, and ideally, impose no limit except as defined by available resources.
</doc>
</rule>
<rule name="priority-based-delivery">
<doc>
Streaming applications SHOULD use different sessions to select different streaming
resolutions. AMQP makes no provision for filtering and/or transforming streams except on
the basis of priority-based selective delivery of individual messages.
</doc>
</rule>
<implement role="server" handle="MUST" />
<response name="consume-ok" />
<field name="queue" type="queue.name">
<doc>
Specifies the name of the queue to consume from.
</doc>
<exception name="queue-exists-if-empty" error-code="not-allowed">
<doc>
If the queue name in this command is empty, the server MUST raise an exception.
</doc>
</exception>
</field>
<field name="consumer-tag" type="str8">
<doc>
Specifies the identifier for the consumer. The consumer tag is local to a connection, so
two clients can use the same consumer tags.
</doc>
<exception name="not-existing-consumer" error-code="not-allowed">
<doc>
The tag MUST NOT refer to an existing consumer. If the client attempts to create two
consumers with the same non-empty tag the server MUST raise an exception.
</doc>
</exception>
<exception name="not-empty-consumer-tag" error-code="not-allowed">
<doc>
The client MUST NOT specify a tag that is empty or blank.
</doc>
<doc type="scenario">
Attempt to create a consumers with an empty tag.
</doc>
</exception>
</field>
<field name="no-local" type="bit">
<doc>If the no-local field is set the server will not send messages to the connection that
published them.</doc>
</field>
<field name="exclusive" type="bit" label="request exclusive access">
<doc>
Request exclusive consumer access, meaning only this consumer can access the queue.
</doc>
<exception name="in-use" error-code="resource-locked">
<doc>
If the server cannot grant exclusive access to the queue when asked, - because there are
other consumers active - it MUST raise an exception with return code 405
(resource locked).
</doc>
</exception>
</field>
<field name="nowait" type="bit" label="do not send a reply command">
<doc>
If set, the server will not respond to the command. The client should not wait for a reply
command. If the server could not complete the command it will raise an exception.
</doc>
</field>
<field name="arguments" type="map" label="arguments for consuming">
<doc>
A set of arguments for the consume. The syntax and semantics of these arguments depends on
the providers implementation.
</doc>
</field>
</command>
<!-- - Command: stream.consume-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="consume-ok" code="0x4" label="confirm a new consumer">
<doc>
This command provides the client with a consumer tag which it may use in commands that work
with the consumer.
</doc>
<implement role="client" handle="MUST" />
<field name="consumer-tag" type="str8">
<doc>
Holds the consumer tag specified by the client or provided by the server.
</doc>
</field>
</command>
<!-- - Command: stream.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="cancel" code="0x5" label="end a queue consumer">
<doc>
This command cancels a consumer. Since message delivery is asynchronous the client may
continue to receive messages for a short while after cancelling a consumer. It may process
or discard these as appropriate.
</doc>
<implement role="server" handle="MUST" />
<field name="consumer-tag" type="str8" />
</command>
<!-- - Command: stream.publish - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="publish" code="0x6" label="publish a message">
<doc>
This command publishes a message to a specific exchange. The message will be routed to
queues as defined by the exchange configuration and distributed to any active consumers as
appropriate.
</doc>
<implement role="server" handle="MUST" />
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange to publish to. The exchange name can be empty, meaning
the default exchange. If the exchange name is specified, and that exchange does not exist,
the server will raise an exception.
</doc>
<rule name="default">
<doc>
The server MUST accept a blank exchange name to mean the default exchange.
</doc>
</rule>
<exception name="refusal" error-code="not-implemented">
<doc>
The exchange MAY refuse stream content in which case it MUST respond with an exception.
</doc>
</exception>
</field>
<field name="routing-key" type="str8" label="Message routing key">
<doc>
Specifies the routing key for the message. The routing key is used for routing messages
depending on the exchange configuration.
</doc>
</field>
<field name="mandatory" type="bit" label="indicate mandatory routing">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue. If
this flag is set, the server will return an unroutable message with a Return command. If
this flag is zero, the server silently drops the message.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the mandatory flag.
</doc>
</rule>
</field>
<field name="immediate" type="bit" label="request immediate delivery">
<doc>
This flag tells the server how to react if the message cannot be routed to a queue
consumer immediately. If this flag is set, the server will return an undeliverable message
with a Return command. If this flag is zero, the server will queue the message, but with
no guarantee that it will ever be consumed.
</doc>
<rule name="implementation">
<doc>
The server SHOULD implement the immediate flag.
</doc>
</rule>
</field>
<segments>
<header required="true">
<entry type="stream-properties"/>
</header>
<body/>
</segments>
</command>
<!-- - Command: stream.return - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="return" code="0x7" label="return a failed message">
<doc>
This command returns an undeliverable message that was published with the "immediate" flag
set, or an unroutable message published with the "mandatory" flag set. The reply code and
text provide information about the reason that the message was undeliverable.
</doc>
<implement role="client" handle="MUST" />
<field name="reply-code" type="return-code" />
<field name="reply-text" type="str8" label="The localized reply text.">
<doc>
The localized reply text. This text can be logged as an aid to resolving issues.
</doc>
</field>
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="routing-key" type="str8" label="Message routing key">
<doc>
Specifies the routing key name specified when the message was published.
</doc>
</field>
<segments>
<header required="true">
<entry type="stream-properties"/>
</header>
<body/>
</segments>
</command>
<!-- - Command: stream.deliver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<command name="deliver" code="0x8" label="notify the client of a consumer message">
<doc>
This command delivers a message to the client, via a consumer. In the asynchronous message
delivery model, the client starts a consumer using the Consume command, then the server
responds with Deliver commands as and when messages arrive for that consumer.
</doc>
<implement role="client" handle="MUST" />
<field name="consumer-tag" type="str8" />
<field name="delivery-tag" type="uint64">
<doc>
The server-assigned and session-specific delivery tag
</doc>
<rule name="session-local">
<doc>
The delivery tag is valid only within the session from which the message was received.
i.e. A client MUST NOT receive a message on one session and then acknowledge it on
another.
</doc>
</rule>
</field>
<field name="exchange" type="exchange.name">
<doc>
Specifies the name of the exchange that the message was originally published to.
</doc>
</field>
<field name="queue" type="queue.name" required="true">
<doc>
Specifies the name of the queue that the message came from. Note that a single session can
start many consumers on different queues.
</doc>
</field>
<segments>
<header required="true">
<entry type="stream-properties"/>
</header>
<body/>
</segments>
</command>
</class>
</amqp>