/[de-setf-amqp]/specification/amqp.0-10.xml
ViewVC logotype

Contents of /specification/amqp.0-10.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3 - (show annotations)
Tue Feb 23 09:05:39 2010 UTC (4 years, 1 month ago) by janderson
File MIME type: text/xml
File size: 256414 byte(s)
Merge commit 'remotes/github/master' into remotes/git-svn
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright Notice
5 ================
6 (c) Copyright Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,
7 Goldman Sachs, IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A,
8 Novell, Rabbit Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc.
9 2006, 2007. All rights reserved.
10
11 License
12 =======
13
14 Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,Goldman Sachs,
15 IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A, Novell, Rabbit
16 Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc. (collectively,
17 the "Authors") each hereby grants to you a worldwide, perpetual, royalty-free, nontransferable,
18 nonexclusive license to (i) copy, display, distribute and implement the Advanced Messaging Queue
19 Protocol ("AMQP") Specification and (ii) the Licensed Claims that are held by the Authors, all for
20 the purpose of implementing the Advanced Messaging Queue Protocol Specification. Your license and
21 any rights under this Agreement will terminate immediately without notice from any Author if you
22 bring any claim, suit, demand, or action related to the Advanced Messaging Queue Protocol
23 Specification against any Author. Upon termination, you shall destroy all copies of the Advanced
24 Messaging Queue Protocol Specification in your possession or control.
25
26 As used hereunder, "Licensed Claims" means those claims of a patent or patent application,
27 throughout the world, excluding design patents and design registrations, owned or controlled, or
28 that can be sublicensed without fee and in compliance with the requirements of this Agreement, by
29 an Author or its affiliates now or at any future time and which would necessarily be infringed by
30 implementation of the Advanced Messaging Queue Protocol Specification. A claim is necessarily
31 infringed hereunder only when it is not possible to avoid infringing it because there is no
32 plausible non-infringing alternative for implementing the required portions of the Advanced
33 Messaging Queue Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not
34 include any claims other than as set forth above even if contained in the same patent as Licensed
35 Claims; or that read solely on any implementations of any portion of the Advanced Messaging Queue
36 Protocol Specification that are not required by the Advanced Messaging Queue Protocol
37 Specification, or that, if licensed, would require a payment of royalties by the licensor to
38 unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling
39 technologies that may be necessary to make or use any Licensed Product but are not themselves
40 expressly set forth in the Advanced Messaging Queue Protocol Specification (e.g., semiconductor
41 manufacturing technology, compiler technology, object oriented technology, networking technology,
42 operating system technology, and the like); or (ii) the implementation of other published
43 standards developed elsewhere and merely referred to in the body of the Advanced Messaging Queue
44 Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or
45 function of which is not required for compliance with the Advanced Messaging Queue Protocol
46 Specification. For purposes of this definition, the Advanced Messaging Queue Protocol
47 Specification shall be deemed to include both architectural and interconnection requirements
48 essential for interoperability and may also include supporting source code artifacts where such
49 architectural, interconnection requirements and source code artifacts are expressly identified as
50 being required or documentation to achieve compliance with the Advanced Messaging Queue Protocol
51 Specification.
52
53 As used hereunder, "Licensed Products" means only those specific portions of products (hardware,
54 software or combinations thereof) that implement and are compliant with all relevant portions of
55 the Advanced Messaging Queue Protocol Specification.
56
57 The following disclaimers, which you hereby also acknowledge as to any use you may make of the
58 Advanced Messaging Queue Protocol Specification:
59
60 THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO
61 REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF
62 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS
63 OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
64 IMPLEMENTATION OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD
65 PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
66
67 THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
68 DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED
69 MESSAGING QUEUE PROTOCOL SPECIFICATION.
70
71 The name and trademarks of the Authors may NOT be used in any manner, including advertising or
72 publicity pertaining to the Advanced Messaging Queue Protocol Specification or its contents
73 without specific, written prior permission. Title to copyright in the Advanced Messaging Queue
74 Protocol Specification will at all times remain with the Authors.
75
76 No other rights are granted by implication, estoppel or otherwise.
77
78 Upon termination of your license or rights under this Agreement, you shall destroy all copies of
79 the Advanced Messaging Queue Protocol Specification in your possession or control.
80
81 Trademarks
82 ==========
83 "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are
84 trademarks of JPMorgan Chase & Co.
85
86 IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
87
88 IONA, IONA Technologies, and the IONA logos are trademarks of IONA Technologies PLC and/or its
89 subsidiaries.
90
91 LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered trademarks of Red Hat,
92 Inc. in the US and other countries.
93
94 Java, all Java-based trademarks and OpenOffice.org are trademarks of Sun Microsystems, Inc. in the
95 United States, other countries, or both.
96
97 Other company, product, or service names may be trademarks or service marks of others.
98
99 Links to full AMQP specification:
100 =================================
101 http://www.envoytech.org/spec/amq/
102 http://www.iona.com/opensource/amqp/
103 http://www.redhat.com/solutions/specifications/amqp/
104 http://www.twiststandards.org/tiki-index.php?page=AMQ
105 http://www.imatix.com/amqp
106 -->
107
108 <!--
109 XML Notes
110 =========
111
112 We use entities to indicate repetition; attributes to indicate properties.
113
114 We use the "name" attribute as an identifier, usually within the context of the surrounding
115 entities.
116
117 We use hyphens (minus char '-') to seperate words in names.
118
119 We do not enforce any particular validation mechanism but we support all mechanisms. The protocol
120 definition conforms to a formal grammar that is published seperately in several technologies.
121
122 -->
123
124 <!DOCTYPE amqp SYSTEM "amqp.dtd">
125
126 <amqp xmlns="http://www.amqp.org/schema/amqp.xsd"
127 major="0" minor="10" port="5672">
128
129 <!--
130 ====================== == type definitions == ======================
131 -->
132
133 <!--
134 0x00 - 0x0f: Fixed width, 1 octet
135 -->
136
137 <type name="bin8" code="0x00" fixed-width="1" label="octet of unspecified encoding">
138 <doc>
139 The bin8 type consists of exactly one octet of opaque binary data.
140 </doc>
141
142 <doc type="picture" title="Wire Format">
143 1 OCTET
144 +----------+
145 | bin8 |
146 +----------+
147 </doc>
148
149 <doc type="bnf">
150 bin8 = OCTET
151 </doc>
152 </type>
153
154 <type name="int8" code="0x01" fixed-width="1" label="8-bit signed integral value (-128 - 127)">
155 <doc>
156 The int8 type is a signed integral value encoded using an 8-bit two's complement
157 representation.
158 </doc>
159
160 <doc type="picture" title="Wire Format">
161 1 OCTET
162 +----------+
163 | int8 |
164 +----------+
165 </doc>
166
167 <doc type="bnf">
168 int8 = OCTET
169 </doc>
170 </type>
171
172 <type name="uint8" code="0x02" fixed-width="1" label="8-bit unsigned integral value (0 - 255)">
173 <doc>
174 The uint8 type is an 8-bit unsigned integral value.
175 </doc>
176
177 <doc type="picture" title="Wire Format">
178 1 OCTET
179 +---------+
180 | uint8 |
181 +---------+
182 </doc>
183
184 <doc type="bnf">
185 uint8 = OCTET
186 </doc>
187 </type>
188
189 <type name="char" code="0x04" fixed-width="1" label="an iso-8859-15 character">
190 <doc>
191 The char type encodes a single character from the iso-8859-15 character set.
192 </doc>
193
194 <doc type="picture" title="Wire Format">
195 1 OCTET
196 +----------+
197 | char |
198 +----------+
199 </doc>
200
201 <doc type="bnf">
202 char = OCTET
203 </doc>
204 </type>
205
206 <type name="boolean" code="0x08" fixed-width="1"
207 label="boolean value (zero represents false, nonzero represents true)">
208 <doc>
209 The boolean type is a single octet that encodes a true or false value. If the octet is zero,
210 then the boolean is false. Any other value represents true.
211 </doc>
212
213 <doc type="picture" title="Wire Format">
214 1 OCTET
215 +---------+
216 | boolean |
217 +---------+
218 </doc>
219
220 <doc type="bnf">
221 boolean = OCTET
222 </doc>
223 </type>
224
225 <!--
226 0x10 - 0x1f: Fixed width, 2 octets
227 -->
228
229 <type name="bin16" code="0x10" fixed-width="2" label="two octets of unspecified binary encoding">
230 <doc>
231 The bin16 type consists of two consecutive octets of opaque binary data.
232 </doc>
233
234 <doc type="picture" title="Wire Format">
235 1 OCTET 1 OCTET
236 +-----------+-----------+
237 | octet-one | octet-two |
238 +-----------+-----------+
239 </doc>
240
241 <doc type="bnf">
242 bin16 = 2 OCTET
243 </doc>
244 </type>
245
246 <type name="int16" code="0x11" fixed-width="2" label="16-bit signed integral value">
247 <doc>
248 The int16 type is a signed integral value encoded using a 16-bit two's complement
249 representation in network byte order.
250 </doc>
251
252 <doc type="picture" title="Wire Format">
253 1 OCTET 1 OCTET
254 +-----------+----------+
255 | high-byte | low-byte |
256 +-----------+----------+
257 </doc>
258
259 <doc type="bnf">
260 int16 = high-byte low-byte
261 high-byte = OCTET
262 low-byte = OCTET
263 </doc>
264 </type>
265
266 <type name="uint16" code="0x12" fixed-width="2" label="16-bit unsigned integer">
267 <doc>
268 The uint16 type is a 16-bit unsigned integral value encoded in network byte order.
269 </doc>
270
271 <doc type="picture" title="Wire Format">
272 1 OCTET 1 OCTET
273 +-----------+----------+
274 | high-byte | low-byte |
275 +-----------+----------+
276 </doc>
277
278 <doc type="bnf">
279 uint16 = high-byte low-byte
280 high-byte = OCTET
281 low-byte = OCTET
282 </doc>
283 </type>
284
285 <!--
286 0x20 - 0x2f: Fixed width, 4 octets
287 -->
288
289 <type name="bin32" code="0x20" fixed-width="4" label="four octets of unspecified binary encoding">
290 <doc>
291 The bin32 type consists of 4 consecutive octets of opaque binary data.
292 </doc>
293
294 <doc type="picture" title="Wire Format">
295 1 OCTET 1 OCTET 1 OCTET 1 OCTET
296 +-----------+-----------+-------------+------------+
297 | octet-one | octet-two | octet-three | octet-four |
298 +-----------+-----------+-------------+------------+
299 </doc>
300
301 <doc type="bnf">
302 bin32 = 4 OCTET
303 </doc>
304 </type>
305
306 <type name="int32" code="0x21" fixed-width="4" label="32-bit signed integral value">
307 <doc>
308 The int32 type is a signed integral value encoded using a 32-bit two's complement
309 representation in network byte order.
310 </doc>
311
312 <doc type="picture" title="Wire Format">
313 1 OCTET 1 OCTET 1 OCTET 1 OCTET
314 +-----------+------------+----------+----------+
315 | byte-four | byte-three | byte-two | byte-one |
316 +-----------+------------+----------+----------+
317 MSB LSB
318 </doc>
319
320 <doc type="bnf">
321 int32 = byte-four byte-three byte-two byte-one
322 byte-four = OCTET ; most significant byte (MSB)
323 byte-three = OCTET
324 byte-two = OCTET
325 byte-one = OCTET ; least significant byte (LSB)
326 </doc>
327 </type>
328
329 <type name="uint32" code="0x22" fixed-width="4" label="32-bit unsigned integral value">
330 <doc>
331 The uint32 type is a 32-bit unsigned integral value encoded in network byte order.
332 </doc>
333
334 <doc type="picture" title="Wire Format">
335 1 OCTET 1 OCTET 1 OCTET 1 OCTET
336 +-----------+------------+----------+----------+
337 | byte-four | byte-three | byte-two | byte-one |
338 +-----------+------------+----------+----------+
339 MSB LSB
340 </doc>
341
342 <doc type="bnf">
343 uint32 = byte-four byte-three byte-two byte-one
344 byte-four = OCTET ; most significant byte (MSB)
345 byte-three = OCTET
346 byte-two = OCTET
347 byte-one = OCTET ; least significant byte (LSB)
348 </doc>
349 </type>
350
351 <type name="float" code="0x23" fixed-width="4"
352 label="single precision IEEE 754 32-bit floating point">
353 <doc>
354 The float type encodes a single precision 32-bit floating point number. The format and
355 operations are defined by the IEEE 754 standard for 32-bit floating point numbers.
356 </doc>
357
358 <doc type="picture" title="Wire Format">
359 4 OCTETs
360 +-----------------------+
361 | float |
362 +-----------------------+
363 IEEE 754 32-bit float
364 </doc>
365
366 <doc type="bnf">
367 float = 4 OCTET ; IEEE 754 32-bit floating point number
368 </doc>
369 </type>
370
371 <type name="char-utf32" code="0x27" fixed-width="4"
372 label="single unicode character in UTF-32 encoding">
373 <doc>
374 The char-utf32 type consists of a single unicode character in the UTF-32 encoding.
375 </doc>
376
377 <doc type="picture" title="Wire Format">
378 4 OCTETs
379 +------------------+
380 | char-utf32 |
381 +------------------+
382 UTF-32 character
383 </doc>
384
385 <doc type="bnf">
386 char-utf32 = 4 OCTET ; single UTF-32 character
387 </doc>
388 </type>
389
390 <type name="sequence-no" fixed-width="4" label="serial number defined in RFC-1982">
391 <doc>
392 The sequence-no type encodes, in network byte order, a serial number as defined in RFC-1982.
393 The arithmetic, operators, and ranges for numbers of this type are defined by RFC-1982.
394 </doc>
395
396 <doc type="picture" title="Wire Format">
397 4 OCTETs
398 +------------------------+
399 | sequence-no |
400 +------------------------+
401 RFC-1982 serial number
402 </doc>
403
404 <doc type="bnf">
405 sequence-no = 4 OCTET ; RFC-1982 serial number
406 </doc>
407 </type>
408
409 <!--
410 0x30 - 0x3f: Fixed width types - 8 octets
411 -->
412
413 <type name="bin64" code="0x30" fixed-width="8"
414 label="eight octets of unspecified binary encoding">
415 <doc>
416 The bin64 type consists of eight consecutive octets of opaque binary data.
417 </doc>
418
419 <doc type="picture" title="Wire Format">
420 1 OCTET 1 OCTET 1 OCTET 1 OCTET
421 +-----------+-----------+-----+-------------+-------------+
422 | octet-one | octet-two | ... | octet-seven | octet-eight |
423 +-----------+-----------+-----+-------------+-------------+
424 </doc>
425
426 <doc type="bnf">
427 bin64 = 8 OCTET
428 </doc>
429 </type>
430
431 <type name="int64" code="0x31" fixed-width="8" label="64-bit signed integral value">
432 <doc>
433 The int64 type is a signed integral value encoded using a 64-bit two's complement
434 representation in network byte order.
435 </doc>
436
437 <doc type="picture" title="Wire Format">
438 1 OCTET 1 OCTET 1 OCTET 1 OCTET
439 +------------+------------+-----+----------+----------+
440 | byte-eight | byte-seven | ... | byte-two | byte-one |
441 +------------+------------+-----+----------+----------+
442 MSB LSB
443 </doc>
444
445 <doc type="bnf">
446 int64 = byte-eight byte-seven byte-six byte-five
447 byte-four byte-three byte-two byte-one
448 byte-eight = 1 OCTET ; most significant byte (MSB)
449 byte-seven = 1 OCTET
450 byte-six = 1 OCTET
451 byte-five = 1 OCTET
452 byte-four = 1 OCTET
453 byte-three = 1 OCTET
454 byte-two = 1 OCTET
455 byte-one = 1 OCTET ; least significant byte (LSB)
456 </doc>
457 </type>
458
459 <type name="uint64" code="0x32" fixed-width="8" label="64-bit unsigned integral value">
460 <doc>
461 The uint64 type is a 64-bit unsigned integral value encoded in network byte order.
462 </doc>
463
464 <doc type="picture" title="Wire Format">
465 1 OCTET 1 OCTET 1 OCTET 1 OCTET
466 +------------+------------+-----+----------+----------+
467 | byte-eight | byte-seven | ... | byte-two | byte-one |
468 +------------+------------+-----+----------+----------+
469 MSB LSB
470 </doc>
471
472 <doc type="bnf">
473 uint64 = byte-eight byte-seven byte-six byte-five
474 byte-four byte-three byte-two byte-one
475 byte-eight = 1 OCTET ; most significant byte (MSB)
476 byte-seven = 1 OCTET
477 byte-six = 1 OCTET
478 byte-five = 1 OCTET
479 byte-four = 1 OCTET
480 byte-three = 1 OCTET
481 byte-two = 1 OCTET
482 byte-one = 1 OCTET ; least significant byte (LSB)
483 </doc>
484 </type>
485
486 <type name="double" code="0x33" fixed-width="8" label="double precision IEEE 754 floating point">
487 <doc>
488 The double type encodes a double precision 64-bit floating point number. The format and
489 operations are defined by the IEEE 754 standard for 64-bit double precision floating point
490 numbers.
491 </doc>
492
493 <doc type="picture" title="Wire Format">
494 8 OCTETs
495 +-----------------------+
496 | double |
497 +-----------------------+
498 IEEE 754 64-bit float
499 </doc>
500
501 <doc type="bnf">
502 double = 8 OCTET ; double precision IEEE 754 floating point number
503 </doc>
504 </type>
505
506 <type name="datetime" code="0x38" fixed-width="8" label="datetime in 64 bit POSIX time_t format">
507 <doc>
508 The datetime type encodes a date and time using the 64 bit POSIX time_t format.
509 </doc>
510
511 <doc type="picture" title="Wire Format">
512 8 OCTETs
513 +---------------------+
514 | datetime |
515 +---------------------+
516 posix time_t format
517 </doc>
518
519 <doc type="bnf">
520 datetime = 8 OCTET ; 64 bit posix time_t format
521 </doc>
522 </type>
523
524 <!--
525 0x40 - 0x4f: Fixed width types - 16 octets
526 -->
527
528 <type name="bin128" code="0x40" fixed-width="16"
529 label="sixteen octets of unspecified binary encoding">
530 <doc>
531 The bin128 type consists of 16 consecutive octets of opaque binary data.
532 </doc>
533
534 <doc type="picture" title="Wire Format">
535 1 OCTET 1 OCTET 1 OCTET 1 OCTET
536 +-----------+-----------+-----+---------------+---------------+
537 | octet-one | octet-two | ... | octet-fifteen | octet-sixteen |
538 +-----------+-----------+-----+---------------+---------------+
539 </doc>
540
541 <doc type="bnf">
542 bin128 = 16 OCTET
543 </doc>
544 </type>
545
546 <type name="uuid" code="0x48" fixed-width="16" label="UUID (RFC-4122 section 4.1.2) - 16 octets">
547 <doc>
548 The uuid type encodes a universally unique id as defined by RFC-4122. The format and
549 operations for this type can be found in section 4.1.2 of RFC-4122.
550 </doc>
551
552 <doc type="picture" title="Wire Format">
553 16 OCTETs
554 +---------------+
555 | uuid |
556 +---------------+
557 RFC-4122 UUID
558 </doc>
559
560 <doc type="bnf">
561 uuid = 16 OCTET ; RFC-4122 section 4.1.2
562 </doc>
563 </type>
564
565 <!--
566 0x50 - 0x5f: Fixed width types - 32 octets
567 -->
568
569 <type name="bin256" code="0x50" fixed-width="32"
570 label="thirty two octets of unspecified binary encoding">
571 <doc>
572 The bin256 type consists of thirty two consecutive octets of opaque binary data.
573 </doc>
574
575 <doc type="picture" title="Wire Format">
576 1 OCTET 1 OCTET 1 OCTET 1 OCTET
577 +-----------+-----------+-----+------------------+------------------+
578 | octet-one | octet-two | ... | octet-thirty-one | octet-thirty-two |
579 +-----------+-----------+-----+------------------+------------------+
580 </doc>
581
582 <doc type="bnf">
583 bin256 = 32 OCTET
584 </doc>
585 </type>
586
587 <!--
588 0x60 - 0x6f: Fixed width types - 64 octets
589 -->
590
591 <type name="bin512" code="0x60" fixed-width="64"
592 label="sixty four octets of unspecified binary encoding">
593 <doc>
594 The bin512 type consists of sixty four consecutive octets of opaque binary data.
595 </doc>
596
597 <doc type="picture" title="Wire Format">
598 1 OCTET 1 OCTET 1 OCTET 1 OCTET
599 +-----------+-----------+-----+-------------------+------------------+
600 | octet-one | octet-two | ... | octet-sixty-three | octet-sixty-four |
601 +-----------+-----------+-----+-------------------+------------------+
602 </doc>
603
604 <doc type="bnf">
605 bin512 = 64 OCTET
606 </doc>
607 </type>
608
609 <!--
610 0x70 - 0x7f: Fixed width types - 128 octets
611 -->
612
613 <type name="bin1024" code="0x70" fixed-width="128"
614 label="one hundred and twenty eight octets of unspecified binary encoding">
615 <doc>
616 The bin1024 type consists of one hundred and twenty eight octets of opaque binary data.
617 </doc>
618
619 <doc type="picture" title="Wire Format">
620 1 OCTET 1 OCTET 1 OCTET 1 OCTET
621 +-----------+-----------+-----+------------------------+------------------------+
622 | octet-one | octet-two | ... | octet-one-twenty-seven | octet-one-twenty-eight |
623 +-----------+-----------+-----+------------------------+------------------------+
624 </doc>
625
626 <doc type="bnf">
627 bin1024 = 128 OCTET
628 </doc>
629 </type>
630
631 <!--
632 0x80 - 0x8f: Variable length - one byte length field (up to 255 octets)
633 -->
634
635 <type name="vbin8" code="0x80" variable-width="1" label="up to 255 octets of opaque binary data">
636 <doc>
637 The vbin8 type encodes up to 255 octets of opaque binary data. The number of octets is first
638 encoded as an 8-bit unsigned integral value. This is followed by the actual data.
639 </doc>
640
641 <doc type="picture" title="Wire Format">
642 1 OCTET size OCTETs
643 +---------+-------------+
644 | size | octets |
645 +---------+-------------+
646 uint8
647 </doc>
648
649 <doc type="bnf">
650 vbin8 = size octets
651 size = uint8
652 octets = 0*255 OCTET ; size OCTETs
653 </doc>
654 </type>
655
656 <type name="str8-latin" code="0x84" variable-width="1" label="up to 255 iso-8859-15 characters">
657 <doc>
658 The str8-latin type encodes up to 255 octets of iso-8859-15 characters. The number of octets
659 is first encoded as an 8-bit unsigned integral value. This is followed by the actual
660 characters.
661 </doc>
662
663 <doc type="picture" title="Wire Format">
664 1 OCTET size OCTETs
665 +---------+------------------------+
666 | size | characters |
667 +---------+------------------------+
668 uint16 iso-8859-15 characters
669 </doc>
670
671 <doc type="bnf">
672 str8-latin = size characters
673 size = uint8
674 characters = 0*255 OCTET ; size OCTETs
675 </doc>
676 </type>
677
678 <type name="str8" code="0x85" variable-width="1" label="up to 255 octets worth of UTF-8 unicode">
679 <doc>
680 The str8 type encodes up to 255 octets worth of UTF-8 unicode. The number of octets of unicode
681 is first encoded as an 8-bit unsigned integral value. This is followed by the actual UTF-8
682 unicode. Note that the encoded size refers to the number of octets of unicode, not necessarily
683 the number of characters since the UTF-8 unicode may include multi-byte character sequences.
684 </doc>
685
686 <doc type="picture" title="Wire Format">
687 1 OCTET size OCTETs
688 +---------+--------------+
689 | size | utf8-unicode |
690 +---------+--------------+
691 uint8
692 </doc>
693
694 <doc type="bnf">
695 str8 = size utf8-unicode
696 size = uint8
697 utf8-unicode = 0*255 OCTET ; size OCTETs
698 </doc>
699 </type>
700
701 <type name="str8-utf16" code="0x86" variable-width="1"
702 label="up to 255 octets worth of UTF-16 unicode">
703 <doc>
704 The str8-utf16 type encodes up to 255 octets worth of UTF-16 unicode. The number of octets of
705 unicode is first encoded as an 8-bit unsigned integral value. This is followed by the actual
706 UTF-16 unicode. Note that the encoded size refers to the number of octets of unicode, not the
707 number of characters since the UTF-16 unicode will include at least two octets per unicode
708 character.
709 </doc>
710
711 <doc type="picture" title="Wire Format">
712 1 OCTET size OCTETs
713 +---------+---------------+
714 | size | utf16-unicode |
715 +---------+---------------+
716 uint8
717 </doc>
718
719 <doc type="bnf">
720 str8-utf16 = size utf16-unicode
721 size = uint8
722 utf16-unicode = 0*255 OCTET ; size OCTETs
723 </doc>
724 </type>
725
726 <!--
727 0x90 - 0x9f: Variable length types - two byte length field (up to 65535 octets)
728 -->
729
730 <type name="vbin16" code="0x90" variable-width="2"
731 label="up to 65535 octets of opaque binary data">
732 <doc>
733 The vbin16 type encodes up to 65535 octets of opaque binary data. The number of octets is
734 first encoded as a 16-bit unsigned integral value in network byte order. This is followed by
735 the actual data.
736 </doc>
737
738 <doc type="picture" title="Wire Format">
739 2 OCTETs size OCTETs
740 +----------+-------------+
741 | size | octets |
742 +----------+-------------+
743 uint16
744 </doc>
745
746 <doc type="bnf">
747 vbin16 = size octets
748 size = uint16
749 octets = 0*65535 OCTET ; size OCTETs
750 </doc>
751 </type>
752
753 <type name="str16-latin" code="0x94" variable-width="2"
754 label="up to 65535 iso-8859-15 characters">
755 <doc>
756 The str16-latin type encodes up to 65535 octets of is-8859-15 characters. The number of octets
757 is first encoded as a 16-bit unsigned integral value in network byte order. This is followed
758 by the actual characters.
759 </doc>
760
761 <doc type="picture" title="Wire Format">
762 2 OCTETs size OCTETs
763 +----------+------------------------+
764 | size | characters |
765 +----------+------------------------+
766 uint16 iso-8859-15 characters
767 </doc>
768
769 <doc type="bnf">
770 str16-latin = size characters
771 size = uint16
772 characters = 0*65535 OCTET ; size OCTETs
773 </doc>
774 </type>
775
776 <type name="str16" code="0x95" variable-width="2"
777 label="up to 65535 octets worth of UTF-8 unicode">
778 <doc>
779 The str16 type encodes up to 65535 octets worth of UTF-8 unicode. The number of octets is
780 first encoded as a 16-bit unsigned integral value in network byte order. This is followed by
781 the actual UTF-8 unicode. Note that the encoded size refers to the number of octets of
782 unicode, not necessarily the number of unicode characters since the UTF-8 unicode may include
783 multi-byte character sequences.
784 </doc>
785
786 <doc type="picture" title="Wire Format">
787 2 OCTETs size OCTETs
788 +----------+--------------+
789 | size | utf8-unicode |
790 +----------+--------------+
791 uint16
792 </doc>
793
794 <doc type="bnf">
795 str16 = size utf8-unicode
796 size = uint16
797 utf8-unicode = 0*65535 OCTET ; size OCTETs
798 </doc>
799 </type>
800
801 <type name="str16-utf16" code="0x96" variable-width="2"
802 label="up to 65535 octets worth of UTF-16 unicode">
803 <doc>
804 The str16-utf16 type encodes up to 65535 octets worth of UTF-16 unicode. The number of octets
805 is first encoded as a 16-bit unsigned integral value in network byte order. This is followed
806 by the actual UTF-16 unicode. Note that the encoded size refers to the number of octets of
807 unicode, not the number of unicode characters since the UTF-16 unicode will include at least
808 two octets per unicode character.
809 </doc>
810
811 <doc type="picture" title="Wire Format">
812 2 OCTETs size OCTETs
813 +----------+---------------+
814 | size | utf16-unicode |
815 +----------+---------------+
816 uint16
817 </doc>
818
819 <doc type="bnf">
820 str16-utf16 = size utf16-unicode
821 size = uint16
822 utf16-unicode = 0*65535 OCTET ; size OCTETs
823 </doc>
824 </type>
825
826 <type name="byte-ranges" variable-width="2" label="byte ranges within a 64-bit payload">
827 <doc>
828 The byte-ranges type encodes up to 65535 octets worth of non-overlapping, non-touching,
829 ascending byte ranges within a 64-bit sequence of bytes. Each range is represented as an
830 inclusive lower and upper bound that identifies all the byte offsets included within a given
831 range.
832 </doc>
833
834 <doc>
835 The number of octets of data is first encoded as a 16-bit unsigned integral value in network
836 byte order. This is then followed by the encoded representation of the ranges included in the
837 set. These MUST be encoded in ascending order, and any two ranges included in a given set MUST
838 NOT include overlapping or touching byte offsets.
839 </doc>
840
841 <doc>
842 Each range is encoded as a pair of 64-bit unsigned integral values in network byte order
843 respectively representing the lower and upper bounds for that range. Note that because each
844 range is exactly 16 octets, the size in octets of the encoded ranges will always be 16 times
845 the number of ranges in the set.
846 </doc>
847
848 <doc type="picture" title="Wire Format">
849 +----= size OCTETs =----+
850 | |
851 2 OCTETs | 16 OCTETs |
852 +----------+-----+-----------+-----+
853 | size | .../| range |\... |
854 +----------+---/ +-----------+ \---+
855 uint16 / / \ \
856 / / \ \
857 / 8 OCTETs 8 OCTETs \
858 +-----------+-----------+
859 | lower | upper |
860 +-----------+-----------+
861 uint64 uint64
862 </doc>
863
864 <doc type="bnf">
865 byte-ranges = size *range
866 size = uint16
867 range = lower upper
868 lower = uint64
869 upper = uint64
870 </doc>
871 </type>
872
873 <type name="sequence-set" variable-width="2" label="ranged set representation">
874 <doc>
875 The sequence-set type is a set of pairs of RFC-1982 numbers representing a discontinuous range
876 within an RFC-1982 sequence. Each pair represents a closed interval within the list.
877 </doc>
878
879 <doc>
880 Sequence-sets can be represented as lists of pairs of positive 32-bit numbers, each pair
881 representing a closed interval that does not overlap or touch with any other interval in the
882 list. For example, a set containing words 0, 1, 2, 5, 6, and 15 can be represented:
883 </doc>
884
885 <doc type="picture">
886 [(0, 2), (5, 6), (15, 15)]
887 </doc>
888
889 <doc>
890 1) The list-of-pairs representation is sorted ascending (as defined by RFC 1982
891 (http://www.ietf.org/rfc/rfc1982.txt) ) by the first elements of each pair.
892 </doc>
893
894 <doc>
895 2) The list-of-pairs is flattened into a list-of-words.
896 </doc>
897
898 <doc>
899 3) Each word in the list is packed into ascending locations in memory with network byte
900 ordering.
901 </doc>
902
903 <doc>
904 4) The size in bytes, represented as a 16-bit network-byte-order unsigned value, is prepended.
905 </doc>
906
907 <doc>
908 For instance, the example from above would be encoded:
909 </doc>
910
911 <doc type="picture">
912 [(0, 2), (5, 6), (15, 15)] -- already sorted.
913 [0, 2, 5, 6, 15, 15] -- flattened.
914 000000000000000200000005000000060000000F0000000F -- bytes in hex
915 0018000000000000000200000005000000060000000F0000000F -- bytes in hex,
916 length (24) prepended
917 </doc>
918
919 <doc type="picture" title="Wire Format">
920 +----= size OCTETs =----+
921 | |
922 2 OCTETs | 8 OCTETs |
923 +----------+-----+-----------+-----+
924 | size | .../| range |\... |
925 +----------+---/ +-----------+ \---+
926 uint16 / / \ \
927 / / \ \
928 / / \ \
929 / / \ \
930 / 4 OCTETs 4 OCTETs \
931 +-------------+-------------+
932 | lower | upper |
933 +-------------+-------------+
934 sequence-no sequence-no
935 </doc>
936
937 <doc type="bnf">
938 sequence-set = size *range
939 size = uint16 ; length of variable portion in bytes
940
941 range = lower upper ; inclusive
942 lower = sequence-no
943 upper = sequence-no
944 </doc>
945 </type>
946
947 <!--
948 0xa0 - 0xaf: Variable length types - four byte length field (up to 4294967295 octets)
949 -->
950
951 <type name="vbin32" code="0xa0" variable-width="4"
952 label="up to 4294967295 octets of opaque binary data">
953 <doc>
954 The vbin32 type encodes up to 4294967295 octets of opaque binary data. The number of octets is
955 first encoded as a 32-bit unsigned integral value in network byte order. This is followed by
956 the actual data.
957 </doc>
958
959 <doc type="picture" title="Wire Format">
960 4 OCTETs size OCTETs
961 +----------+-------------+
962 | size | octets |
963 +----------+-------------+
964 uint32
965 </doc>
966
967 <doc type="bnf">
968 vbin32 = size octets
969 size = uint32
970 octets = 0*4294967295 OCTET ; size OCTETs
971 </doc>
972 </type>
973
974 <type name="map" code="0xa8" variable-width="4" label="a mapping of keys to typed values">
975 <doc>
976 A map is a set of distinct keys where each key has an associated (type,value) pair. The triple
977 of the key, type, and value, form an entry within a map. Each entry within a given map MUST
978 have a distinct key. A map is encoded as a size in octets, a count of the number of entries,
979 followed by the encoded entries themselves.
980 </doc>
981
982 <doc>
983 An encoded map may contain up to (4294967295 - 4) octets worth of encoded entries. The size is
984 encoded as a 32-bit unsigned integral value in network byte order equal to the number of
985 octets worth of encoded entries plus 4. (The extra 4 octets is added for the entry count.) The
986 size is then followed by the number of entries encoded as a 32-bit unsigned integral value in
987 network byte order. Finally the entries are encoded sequentially.
988 </doc>
989
990 <doc>
991 An entry is encoded as the key, followed by the type, and then the value. The key is always a
992 string encoded as a str8. The type is a single octet that may contain any valid AMQP type
993 code. The value is encoded according to the rules defined by the type code for that entry.
994 </doc>
995
996 <doc type="picture" title="Wire Format">
997 +------------= size OCTETs =-----------+
998 | |
999 4 OCTETs | 4 OCTETs |
1000 +----------+----------+-----+---------------+-----+
1001 | size | count | .../| entry |\... |
1002 +----------+----------+---/ +---------------+ \---+
1003 uint32 uint32 / / \ \
1004 / / \ \
1005 / / \ \
1006 / / \ \
1007 / / \ \
1008 / k OCTETs 1 OCTET n OCTETs \
1009 +-----------+---------+-----------+
1010 | key | type | value |
1011 +-----------+---------+-----------+
1012 str8 *type*
1013 </doc>
1014
1015 <doc type="bnf">
1016 map = size count *entry
1017
1018 size = uint32 ; size of count and entries in octets
1019 count = uint32 ; number of entries in the map
1020
1021 entry = key type value
1022 key = str8
1023 type = OCTET ; type code of the value
1024 value = *OCTET ; the encoded value
1025 </doc>
1026 </type>
1027
1028 <type name="list" code="0xa9" variable-width="4" label="a series of consecutive type-value pairs">
1029 <doc>
1030 A list is an ordered sequence of (type, value) pairs. The (type, value) pair forms an item
1031 within the list. The list may contain items of many distinct types. A list is encoded as a
1032 size in octets, followed by a count of the number of items, followed by the items themselves
1033 encoded in their defined order.
1034 </doc>
1035
1036 <doc>
1037 An encoded list may contain up to (4294967295 - 4) octets worth of encoded items. The size is
1038 encoded as a 32-bit unsigned integral value in network byte order equal to the number of
1039 octets worth of encoded items plus 4. (The extra 4 octets is added for the item count.) The
1040 size is then followed by the number of items encoded as a 32-bit unsigned integral value in
1041 network byte order. Finally the items are encoded sequentially in their defined order.
1042 </doc>
1043
1044 <doc>
1045 An item is encoded as the type followed by the value. The type is a single octet that may
1046 contain any valid AMQP type code. The value is encoded according to the rules defined by the
1047 type code for that item.
1048 </doc>
1049
1050 <doc type="picture" title="Wire Format">
1051 +---------= size OCTETs =---------+
1052 | |
1053 4 OCTETs | 4 OCTETs |
1054 +----------+----------+-----+----------+-----+
1055 | size | count | .../| item |\... |
1056 +----------+----------+---/ +----------+ \---+
1057 uint32 uint32 / / \ \
1058 / / \ \
1059 / 1 OCTET n OCTETs \
1060 +----------+-----------+
1061 | type | value |
1062 +----------+-----------+
1063 *type*
1064 </doc>
1065
1066 <doc type="bnf">
1067 list = size count *item
1068
1069 size = uint32 ; size of count and items in octets
1070 count = uint32 ; number of items in the list
1071
1072 item = type value
1073 type = OCTET ; type code of the value
1074 value = *OCTET ; the encoded value
1075 </doc>
1076 </type>
1077
1078 <type name="array" code="0xaa" variable-width="4"
1079 label="a defined length collection of values of a single type">
1080 <doc>
1081 An array is an ordered sequence of values of the same type. The array is encoded in as a size
1082 in octets, followed by a type code, then a count of the number values in the array, and
1083 finally the values encoded in their defined order.
1084 </doc>
1085
1086 <doc>
1087 An encoded array may contain up to (4294967295 - 5) octets worth of encoded values. The size
1088 is encoded as a 32-bit unsigned integral value in network byte order equal to the number of
1089 octets worth of encoded values plus 5. (The extra 5 octets consist of 4 octets for the count
1090 of the number of values, and one octet to hold the type code for the items in the array.) The
1091 size is then followed by a single octet that may contain any valid AMQP type code. The type
1092 code is then followed by the number of values encoded as a 32-bit unsigned integral value in
1093 network byte order. Finally the values are encoded sequentially in their defined order
1094 according to the rules defined by the type code for the array.
1095 </doc>
1096
1097 <doc type="picture" title="Wire Format">
1098 4 OCTETs 1 OCTET 4 OCTETs (size - 5) OCTETs
1099 +----------+---------+----------+-------------------------+
1100 | size | type | count | values |
1101 +----------+---------+----------+-------------------------+
1102 uint32 uint32 *count* encoded *types*
1103 </doc>
1104
1105 <doc type="bnf">
1106 array = size type count values
1107
1108 size = uint32 ; size of type, count, and values in octets
1109 type = OCTET ; the type of the encoded values
1110 count = uint32 ; number of items in the array
1111
1112 values = 0*4294967290 OCTET ; (size - 5) OCTETs
1113 </doc>
1114 </type>
1115
1116 <type name="struct32" code="0xab" variable-width="4" label="a coded struct with a 32-bit size">
1117 <doc>
1118 The struct32 type describes any coded struct with a 32-bit (4 octet) size. The type is
1119 restricted to be only coded structs with a 32-bit size, consequently the first six octets of
1120 any encoded value for this type MUST always contain the size, class-code, and struct-code in
1121 that order.
1122 </doc>
1123
1124 <doc>
1125 The size is encoded as a 32-bit unsigned integral value in network byte order that is equal to
1126 the size of the encoded field-data, packing-flags, class-code, and struct-code. The class-code
1127 is a single octet that may be set to any valid class code. The struct-code is a single octet
1128 that may be set to any valid struct code within the given class-code.
1129 </doc>
1130
1131 <doc>
1132 The first six octets are then followed by the packing flags and encoded field data. The
1133 presence and quantity of packing-flags, as well as the specific fields are determined by the
1134 struct definition identified with the encoded class-code and struct-code.
1135 </doc>
1136
1137 <doc type="picture" title="Wire Format">
1138 4 OCTETs 1 OCTET 1 OCTET pack-width OCTETs n OCTETs
1139 +----------+------------+-------------+-------------------+------------+
1140 | size | class-code | struct-code | packing-flags | field-data |
1141 +----------+------------+-------------+-------------------+------------+
1142 uint32
1143
1144 n = (size - 2 - pack-width)
1145 </doc>
1146
1147 <doc type="bnf">
1148 struct32 = size class-code struct-code packing-flags field-data
1149
1150 size = uint32
1151
1152 class-code = OCTET ; zero for top-level structs
1153 struct-code = OCTET ; together with class-code identifies the struct
1154 ; definition which determines the pack-width and
1155 ; fields
1156
1157 packing-flags = 0*4 OCTET ; pack-width OCTETs
1158
1159 field-data = *OCTET ; (size - 2 - pack-width) OCTETs
1160 </doc>
1161 </type>
1162
1163 <!--
1164 0xb0 - 0xbf: Reserved
1165 -->
1166
1167 <!--
1168 0xc0 - 0xcf:Fixed width types - 5 octets
1169 -->
1170
1171 <type name="bin40" code="0xc0" fixed-width="5" label="five octets of unspecified binary encoding">
1172 <doc>
1173 The bin40 type consists of five consecutive octets of opaque binary data.
1174 </doc>
1175
1176 <doc type="picture" title="Wire Format">
1177 1 OCTET 1 OCTET 1 OCTET 1 OCTET 1 OCTET
1178 +-----------+-----------+-------------+------------+------------+
1179 | octet-one | octet-two | octet-three | octet-four | octet-five |
1180 +-----------+-----------+-------------+------------+------------+
1181 </doc>
1182
1183 <doc type="bnf">
1184 bin40 = 5 OCTET
1185 </doc>
1186 </type>
1187
1188 <type name="dec32" code="0xc8" fixed-width="5"
1189 label="32-bit decimal value (e.g. for use in financial values)">
1190 <doc>
1191 The dec32 type is decimal value with a variable number of digits following the decimal point.
1192 It is encoded as an 8-bit unsigned integral value representing the number of decimal places.
1193 This is followed by the signed integral value encoded using a 32-bit two's complement
1194 representation in network byte order.
1195 </doc>
1196
1197 <doc>
1198 The former value is referred to as the exponent of the divisor. The latter value is the
1199 mantissa. The decimal value is given by: mantissa / 10^exponent.
1200 </doc>
1201
1202 <doc type="picture" title="Wire Format">
1203 1 OCTET 4 OCTETs
1204 +----------+----------+
1205 | exponent | mantissa |
1206 +----------+----------+
1207 uint8 int32
1208 </doc>
1209
1210 <doc type="bnf">
1211 dec32 = exponent mantissa
1212 exponent = uint8
1213 mantissa = int32
1214 </doc>
1215 </type>
1216
1217 <!--
1218 0xd0 - 0xdf: Fixed width types - 9 octets
1219 -->
1220
1221 <type name="bin72" code="0xd0" fixed-width="9"
1222 label="nine octets of unspecified binary encoding">
1223 <doc>
1224 The bin72 type consists of nine consecutive octets of opaque binary data.
1225 </doc>
1226
1227 <doc type="picture" title="Wire Format">
1228 1 OCTET 1 OCTET 1 OCTET 1 OCTET
1229 +-----------+-----------+-----+-------------+------------+
1230 | octet-one | octet-two | ... | octet-eight | octet-nine |
1231 +-----------+-----------+-----+-------------+------------+
1232 </doc>
1233
1234 <doc type="bnf">
1235 bin64 = 9 OCTET
1236 </doc>
1237 </type>
1238
1239 <type name="dec64" code="0xd8" fixed-width="9"
1240 label="64-bit decimal value (e.g. for use in financial values)">
1241 <doc>
1242 The dec64 type is decimal value with a variable number of digits following the decimal point.
1243 It is encoded as an 8-bit unsigned integral value representing the number of decimal places.
1244 This is followed by the signed integral value encoded using a 64-bit two's complement
1245 representation in network byte order.
1246 </doc>
1247
1248 <doc>
1249 The former value is referred to as the exponent of the divisor. The latter value is the
1250 mantissa. The decimal value is given by: mantissa / 10^exponent.
1251 </doc>
1252
1253 <doc type="picture" title="Wire Format">
1254 1 OCTET 8 OCTETs
1255 +----------+----------+
1256 | exponent | mantissa |
1257 +----------+----------+
1258 uint8 int64
1259 </doc>
1260
1261 <doc type="bnf">
1262 dec64 = exponent mantissa
1263 exponent = uint8
1264 mantissa = int64
1265 </doc>
1266 </type>
1267
1268 <!--
1269 0xe0 - 0xef: Reserved
1270 -->
1271
1272 <!--
1273 0xf0 - 0xff: Zero-length types
1274 -->
1275
1276 <type name="void" code="0xf0" fixed-width="0" label="the void type">
1277 <doc>
1278 The void type is used within tagged data structures such as maps and lists to indicate an
1279 empty value. The void type has no value and is encoded as an empty sequence of octets.
1280 </doc>
1281 </type>
1282
1283 <type name="bit" code="0xf1" fixed-width="0" label="presence indicator">
1284 <doc>
1285 The bit type is used to indicate that a packing flag within a packed struct is being used to
1286 represent a boolean value based on the presence of an empty value. The bit type has no value
1287 and is encoded as an empty sequence of octets.
1288 </doc>
1289 </type>
1290
1291 <!--
1292 ======================================================
1293 == CONSTANTS
1294 ======================================================
1295 -->
1296
1297 <!-- Protocol constants -->
1298
1299 <constant name="MIN-MAX-FRAME-SIZE" value="4096" label="The minimum size (in bytes) which can be
1300 agreed upon as the maximum frame size.">
1301 <doc>
1302 During the initial connection negotiation, the two peers must agree upon a maximum frame size.
1303 This constant defines the minimum value to which the maximum frame size can be set. By
1304 defining this value, the peers can guarantee that they can send frames of up to this size
1305 until they have agreed a definitive maximum frame size for that connection.
1306 </doc>
1307 </constant>
1308
1309 <!--
1310 ======================================================
1311 == DOMAIN TYPES
1312 ======================================================
1313 -->
1314
1315 <!-- Segment types -->
1316
1317 <domain name="segment-type" type="uint8" label="valid values for the frame type indicator.">
1318 <doc>
1319 Segments are defined in <xref ref="specification.transport.assemblies_segments_and_frames"/>.
1320 The segment domain defines the valid values that may be used for the segment indicator within
1321 the frame header.
1322 </doc>
1323
1324 <enum>
1325 <choice name="control" value="0">
1326 <doc>
1327 The frame type indicator for Control segments (see <xref
1328 ref="specification.formal_notation.controls"/>).
1329 </doc>
1330 </choice>
1331 <choice name="command" value="1">
1332 <doc>
1333 The frame type indicator for Command segments (see <xref
1334 ref="specification.formal_notation.commands"/>).
1335 </doc>
1336 </choice>
1337 <choice name="header" value="2" >
1338 <doc>
1339 The frame type indicator for Header segments (see <xref
1340 ref="specification.formal_notation.segments.header"/>).
1341 </doc>
1342 </choice>
1343 <choice name="body" value="3" >
1344 <doc>
1345 The frame type indicator for Body segments (see <xref
1346 ref="specification.formal_notation.segments.body"/>).
1347 </doc>
1348 </choice>
1349 </enum>
1350 </domain>
1351
1352 <!-- Tracks -->
1353
1354 <domain name="track" type="uint8" label="Valid values for transport level tracks">
1355 <doc> Tracks are defined in <xref ref="specification.transport.channels_and_tracks"/>. The
1356 track domain defines the valid values that may used for the track indicator within the frame
1357 header</doc>
1358 <enum>
1359 <choice name="control" value="0">
1360 <doc>
1361 The track used for all controls. All controls defined in this specification MUST be sent
1362 on track 0.
1363 </doc>
1364 </choice>
1365 <choice name="command" value="1">
1366 <doc>
1367 The track used for all commands. All commands defined in this specification MUST be sent
1368 on track 1.
1369 </doc>
1370 </choice>
1371 </enum>
1372 </domain>
1373
1374
1375 <domain name="str16-array" type="array" label="An array of values of type str16.">
1376 <doc>
1377 An array of values of type str16.
1378 </doc>
1379 </domain>
1380
1381
1382
1383 <!-- == Class: connection ==================================================================== -->
1384
1385 <class name="connection" code="0x1" label="work with connections">
1386 <doc>
1387 The connection class provides controls for a client to establish a network connection to a
1388 server, and for both peers to operate the connection thereafter.
1389 </doc>
1390
1391 <doc type="grammar">
1392 connection = open-connection
1393 *use-connection
1394 close-connection
1395 open-connection = C:protocol-header
1396 S:START C:START-OK
1397 *challenge
1398 S:TUNE C:TUNE-OK
1399 C:OPEN S:OPEN-OK | S:REDIRECT
1400 challenge = S:SECURE C:SECURE-OK
1401 use-connection = *channel
1402 close-connection = C:CLOSE S:CLOSE-OK
1403 / S:CLOSE C:CLOSE-OK
1404 </doc>
1405
1406 <role name="server" implement="MUST" />
1407 <role name="client" implement="MUST" />
1408
1409 <domain name="close-code" type="uint16" label="code used in the connection.close control to
1410 indicate reason for closure">
1411 <enum>
1412 <choice name="normal" value="200">
1413 <doc>
1414 The connection closed normally.
1415 </doc>
1416 </choice>
1417
1418 <choice name="connection-forced" value="320">
1419 <doc>
1420 An operator intervened to close the connection for some reason. The client may retry at
1421 some later date.
1422 </doc>
1423 </choice>
1424
1425 <choice name="invalid-path" value="402">
1426 <doc>
1427 The client tried to work with an unknown virtual host.
1428 </doc>
1429 </choice>
1430
1431 <choice name="framing-error" value="501">
1432 <doc>
1433 A valid frame header cannot be formed from the incoming byte stream.
1434 </doc>
1435 </choice>
1436 </enum>
1437 </domain>
1438
1439 <domain name="amqp-host-url" type="str16" label="URL for identifying an AMQP Server">
1440 <doc>
1441 The amqp-url domain defines a format for identifying an AMQP Server. It is used to provide
1442 alternate hosts in the case where a client has to reconnect because of failure, or because
1443 the server requests the client to do so upon initial connection.
1444 </doc>
1445 <doc type="bnf"><![CDATA[
1446 amqp_url = "amqp:" prot_addr_list
1447 prot_addr_list = [prot_addr ","]* prot_addr
1448 prot_addr = tcp_prot_addr | tls_prot_addr
1449
1450 tcp_prot_addr = tcp_id tcp_addr
1451 tcp_id = "tcp:" | ""
1452 tcp_addr = [host [":" port] ]
1453 host = <as per http://www.ietf.org/rfc/rfc3986.txt>
1454 port = number]]>
1455 </doc>
1456 </domain>
1457
1458 <domain name="amqp-host-array" type="array" label="An array of values of type amqp-host-url">
1459 <doc>
1460 Used to provide a list of alternate hosts.
1461 </doc>
1462 </domain>
1463
1464 <!-- - Control: connection.start - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1465
1466 <control name="start" code="0x1" label="start connection negotiation">
1467 <doc>
1468 This control starts the connection negotiation process by telling the client the supported
1469 security mechanisms and locales from which the client can choose.
1470 </doc>
1471
1472 <rule name="protocol-name">
1473 <doc>
1474 If the server cannot support the protocol specified in the protocol header, it MUST close
1475 the socket connection without sending any response control.
1476 </doc>
1477 <doc type="scenario">
1478 The client sends a protocol header containing an invalid protocol name. The server must
1479 respond by closing the connection.
1480 </doc>
1481 </rule>
1482
1483 <rule name="client-support">
1484 <doc>
1485 If the client cannot handle the protocol version suggested by the server it MUST close the
1486 socket connection.
1487 </doc>
1488 <doc type="scenario">
1489 The server sends a protocol version that is lower than any valid implementation, e.g. 0.1.
1490 The client must respond by closing the connection.
1491 </doc>
1492 </rule>
1493
1494 <implement role="client" handle="MUST" />
1495
1496 <response name="start-ok" />
1497
1498 <field name="server-properties" type="map" label="server properties">
1499 <rule name="required-fields">
1500 <doc>
1501 The properties SHOULD contain at least these fields: "host", specifying the server host
1502 name or address, "product", giving the name of the server product, "version", giving the
1503 name of the server version, "platform", giving the name of the operating system,
1504 "copyright", if appropriate, and "information", giving other general information.
1505 </doc>
1506 <doc type="scenario">
1507 Client connects to server and inspects the server properties. It checks for the presence
1508 of the required fields.
1509 </doc>
1510 </rule>
1511 </field>
1512
1513 <field name="mechanisms" type="str16-array" label="available security mechanisms"
1514 required="true">
1515 <doc>
1516 A list of the security mechanisms that the server supports.
1517 </doc>
1518 </field>
1519
1520 <field name="locales" type="str16-array" label="available message locales" required="true">
1521 <doc>
1522 A list of the message locales that the server supports. The locale defines the language in
1523 which the server will send reply texts.
1524 </doc>
1525
1526 <rule name="required-support">
1527 <doc>
1528 The server MUST support at least the en_US locale.
1529 </doc>
1530 <doc type="scenario">
1531 Client connects to server and inspects the locales field. It checks for the presence of
1532 the required locale(s).
1533 </doc>
1534 </rule>
1535 </field>
1536 </control>
1537
1538 <!-- - Control: connection.start-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1539
1540 <control name="start-ok" code="0x2" label="select security mechanism and locale">
1541 <doc>
1542 This control selects a SASL security mechanism.
1543 </doc>
1544
1545 <implement role="server" handle="MUST" />
1546
1547 <field name="client-properties" type="map" label="client properties">
1548 <rule name="required-fields">
1549 <!-- This rule is not testable from the client side -->
1550 <doc>
1551 The properties SHOULD contain at least these fields: "product", giving the name of the
1552 client product, "version", giving the name of the client version, "platform", giving the
1553 name of the operating system, "copyright", if appropriate, and "information", giving
1554 other general information.
1555 </doc>
1556 </rule>
1557 </field>
1558
1559 <field name="mechanism" type="str8" label="selected security mechanism" required="true">
1560 <doc>
1561 A single security mechanisms selected by the client, which must be one of those specified
1562 by the server.
1563 </doc>
1564
1565 <rule name="security">
1566 <doc>
1567 The client SHOULD authenticate using the highest-level security profile it can handle
1568 from the list provided by the server.
1569 </doc>
1570 </rule>
1571
1572 <rule name="validity">
1573 <doc>
1574 If the mechanism field does not contain one of the security mechanisms proposed by the
1575 server in the Start control, the server MUST close the connection without sending any
1576 further data.
1577 </doc>
1578 <doc type="scenario">
1579 Client connects to server and sends an invalid security mechanism. The server must
1580 respond by closing the connection (a socket close, with no connection close
1581 negotiation).
1582 </doc>
1583 </rule>
1584 </field>
1585
1586 <field name="response" type="vbin32" label="security response data" required="true">
1587 <doc>
1588 A block of opaque data passed to the security mechanism. The contents of this data are
1589 defined by the SASL security mechanism.
1590 </doc>
1591 </field>
1592
1593 <field name="locale" type="str8" label="selected message locale" required="true">
1594 <doc>
1595 A single message locale selected by the client, which must be one of those specified by
1596 the server.
1597 </doc>
1598 </field>
1599 </control>
1600
1601 <!-- - Control: connection.secure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1602
1603 <control name="secure" code="0x3" label="security mechanism challenge">
1604 <doc>
1605 The SASL protocol works by exchanging challenges and responses until both peers have
1606 received sufficient information to authenticate each other. This control challenges the
1607 client to provide more information.
1608 </doc>
1609
1610 <implement role="client" handle="MUST" />
1611
1612 <response name="secure-ok" />
1613
1614 <field name="challenge" type="vbin32" label="security challenge data" required="true">
1615 <doc>
1616 Challenge information, a block of opaque binary data passed to the security mechanism.
1617 </doc>
1618 </field>
1619 </control>
1620
1621 <!-- - Control: connection.secure-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1622
1623 <control name="secure-ok" code="0x4" label="security mechanism response">
1624 <doc>
1625 This control attempts to authenticate, passing a block of SASL data for the security
1626 mechanism at the server side.
1627 </doc>
1628
1629 <implement role="server" handle="MUST" />
1630
1631 <field name="response" type="vbin32" label="security response data" required="true">
1632 <doc>
1633 A block of opaque data passed to the security mechanism. The contents of this data are
1634 defined by the SASL security mechanism.
1635 </doc>
1636 </field>
1637 </control>
1638
1639 <!-- - Control: connection.tune - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1640
1641 <control name="tune" code="0x5" label="propose connection tuning parameters">
1642 <doc>
1643 This control proposes a set of connection configuration values to the client. The client can
1644 accept and/or adjust these.
1645 </doc>
1646
1647 <implement role="client" handle="MUST" />
1648
1649 <response name="tune-ok" />
1650
1651 <field name="channel-max" type="uint16" label="proposed maximum channels">
1652 <doc>
1653 The maximum total number of channels that the server allows per connection. If this is not
1654 set it means that the server does not impose a fixed limit, but the number of allowed
1655 channels may be limited by available server resources.
1656 </doc>
1657 </field>
1658
1659 <field name="max-frame-size" type="uint16" label="proposed maximum frame size">
1660 <doc>
1661 The largest frame size that the server proposes for the connection. The client can
1662 negotiate a lower value. If this is not set means that the server does not impose any
1663 specific limit but may reject very large frames if it cannot allocate resources for them.
1664 </doc>
1665
1666 <rule name="minimum">
1667 <doc>
1668 Until the max-frame-size has been negotiated, both peers MUST accept frames of up to
1669 MIN-MAX-FRAME-SIZE octets large, and the minimum negotiated value for max-frame-size is
1670 also MIN-MAX-FRAME-SIZE.
1671 </doc>
1672 <doc type="scenario">
1673 Client connects to server and sends a large properties field, creating a frame of
1674 MIN-MAX-FRAME-SIZE octets. The server must accept this frame.
1675 </doc>
1676 </rule>
1677 </field>
1678
1679 <field name="heartbeat-min" type="uint16" label="the minimum supported heartbeat delay">
1680 <doc>
1681 The minimum delay, in seconds, of the connection heartbeat supported by the server. If
1682 this is not set it means the server does not support sending heartbeats.
1683 </doc>
1684 </field>
1685
1686 <field name="heartbeat-max" type="uint16" label="the maximum supported heartbeat delay">
1687 <doc>
1688 The maximum delay, in seconds, of the connection heartbeat supported by the server. If
1689 this is not set it means the server has no maximum.
1690 </doc>
1691
1692 <rule name="permitted-range">
1693 <doc>
1694 The heartbeat-max value must be greater than or equal to the value supplied in the
1695 heartbeat-min field.
1696 </doc>
1697 </rule>
1698
1699 <rule name="no-heartbeat-min">
1700 <doc>
1701 If no heartbeat-min is supplied, then the heartbeat-max field MUST remain empty.
1702 </doc>
1703 </rule>
1704 </field>
1705 </control>
1706
1707 <!-- - Control: connection.tune-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1708
1709 <control name="tune-ok" code="0x6" label="negotiate connection tuning parameters">
1710 <doc>
1711 This control sends the client's connection tuning parameters to the server. Certain fields
1712 are negotiated, others provide capability information.
1713 </doc>
1714
1715 <implement role="server" handle="MUST" />
1716
1717 <field name="channel-max" type="uint16" label="negotiated maximum channels" required="true">
1718 <doc>
1719 The maximum total number of channels that the client will use per connection.
1720 </doc>
1721
1722 <rule name="upper-limit">
1723 <doc>
1724 If the client specifies a channel max that is higher than the value provided by the
1725 server, the server MUST close the connection without attempting a negotiated close. The
1726 server may report the error in some fashion to assist implementers.
1727 </doc>
1728
1729 </rule>
1730
1731 <rule name="available-channels">
1732 <doc>
1733 If the client agrees to a channel-max of N channels, then the channels available for
1734 communication between client and server are precisely the channels numbered 0 to (N-1).
1735 </doc>
1736 </rule>
1737 </field>
1738
1739 <field name="max-frame-size" type="uint16" label="negotiated maximum frame size">
1740 <doc>
1741 The largest frame size that the client and server will use for the connection. If it is
1742 not set means that the client does not impose any specific limit but may reject very large
1743 frames if it cannot allocate resources for them. Note that the max-frame-size limit
1744 applies principally to content frames, where large contents can be broken into frames of
1745 arbitrary size.
1746 </doc>
1747
1748 <rule name="minimum">
1749 <doc>
1750 Until the max-frame-size has been negotiated, both peers MUST accept frames of up to
1751 MIN-MAX-FRAME-SIZE octets large, and the minimum negotiated value for max-frame-size is
1752 also MIN-MAX-FRAME-SIZE.
1753 </doc>
1754 </rule>
1755
1756 <rule name="upper-limit">
1757 <doc>
1758 If the client specifies a max-frame-size that is higher than the value provided by the
1759 server, the server MUST close the connection without attempting a negotiated close. The
1760 server may report the error in some fashion to assist implementers.
1761 </doc>
1762 </rule>
1763
1764 <rule name="max-frame-size">
1765 <doc>
1766 A peer MUST NOT send frames larger than the agreed-upon size. A peer that receives an
1767 oversized frame MUST close the connection with the framing-error close-code.
1768 </doc>
1769 </rule>
1770 </field>
1771
1772 <field name="heartbeat" type="uint16" label="negotiated heartbeat delay">
1773 <doc>
1774 The delay, in seconds, of the connection heartbeat chosen by the client. If it is not set
1775 it means the client does not want a heartbeat.
1776 </doc>
1777
1778 <rule name="permitted-range">
1779 <doc>
1780 The chosen heartbeat MUST be in the range supplied by the heartbeat-min and
1781 heartbeat-max fields of connection.tune.
1782 </doc>
1783 </rule>
1784
1785 <rule name="no-heartbeat-min">
1786 <doc>
1787 The heartbeat field MUST NOT be set if the heartbeat-min field of connection.tune was
1788 not set by the server.
1789 </doc>
1790 </rule>
1791 </field>
1792 </control>
1793
1794 <!-- - Control: connection.open - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1795
1796 <control name="open" code="0x7" label="open connection to virtual host">
1797 <doc>
1798 This control opens a connection to a virtual host, which is a collection of resources, and
1799 acts to separate multiple application domains within a server. The server may apply
1800 arbitrary limits per virtual host, such as the number of each type of entity that may be
1801 used, per connection and/or in total.
1802 </doc>
1803
1804 <implement role="server" handle="MUST" />
1805
1806 <response name="open-ok" />
1807 <response name="redirect" />
1808
1809 <field name="virtual-host" type="str8" label="virtual host name" required="true">
1810 <doc>
1811 The name of the virtual host to work with.
1812 </doc>
1813
1814 <rule name="separation">
1815 <doc>
1816 If the server supports multiple virtual hosts, it MUST enforce a full separation of
1817 exchanges, queues, and all associated entities per virtual host. An application,
1818 connected to a specific virtual host, MUST NOT be able to access resources of another
1819 virtual host.
1820 </doc>
1821 </rule>
1822
1823 <rule name="security">
1824 <doc>
1825 The server SHOULD verify that the client has permission to access the specified virtual
1826 host.
1827 </doc>
1828 </rule>
1829 </field>
1830
1831 <field name="capabilities" type="str16-array" label="required capabilities">
1832 <doc>
1833 The client can specify zero or more capability names. The server can use this to determine
1834 how to process the client's connection request.
1835 </doc>
1836 </field>
1837
1838 <field name="insist" type="bit" label="insist on connecting to server">
1839 <doc>
1840 In a configuration with multiple collaborating servers, the server may respond to a
1841 connection.open control with a Connection.Redirect. The insist option tells the server
1842 that the client is insisting on a connection to the specified server.
1843 </doc>
1844 <rule name="behavior">
1845 <doc>
1846 When the client uses the insist option, the server MUST NOT respond with a
1847 Connection.Redirect control. If it cannot accept the client's connection request it
1848 should respond by closing the connection with a suitable reply code.
1849 </doc>
1850 </rule>
1851 </field>
1852 </control>
1853
1854 <!-- - Control: connection.open-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1855
1856 <control name="open-ok" code="0x8" label="signal that connection is ready">
1857 <doc>
1858 This control signals to the client that the connection is ready for use.
1859 </doc>
1860
1861 <implement role="client" handle="MUST" />
1862
1863 <field name="known-hosts" type="amqp-host-array" label="alternate hosts which may be used in
1864 the case of failure">
1865 <doc>
1866 Specifies an array of equivalent or alternative hosts that the server knows about, which
1867 will normally include the current server itself. Each entry in the array will be in the
1868 form of an IP address or DNS name, optionally followed by a colon and a port number.
1869 Clients can cache this information and use it when reconnecting to a server after a
1870 failure. This field may be empty.
1871 </doc>
1872 </field>
1873 </control>
1874
1875 <!-- - Control: connection.redirect - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1876
1877 <control name="redirect" code="0x9" label="redirects client to other server">
1878 <doc>
1879 This control redirects the client to another server, based on the requested virtual host
1880 and/or capabilities.
1881 </doc>
1882
1883 <rule name="usage">
1884 <doc>
1885 When getting the connection.redirect control, the client SHOULD reconnect to the host
1886 specified, and if that host is not present, to any of the hosts specified in the
1887 known-hosts list.
1888 </doc>
1889 </rule>
1890
1891 <implement role="client" handle="MUST" />
1892
1893 <field name="host" type="amqp-host-url" label="server to connect to" required="true">
1894 <doc>
1895 Specifies the server to connect to.
1896 </doc>
1897 </field>
1898
1899 <field name="known-hosts" type="amqp-host-array" label="alternate hosts to try in case of
1900 failure">
1901 <doc>
1902 An array of equivalent or alternative hosts that the server knows about.
1903 </doc>
1904 </field>
1905 </control>
1906
1907 <!-- - Control: connection.heartbeat - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1908
1909 <control name="heartbeat" code="0xa" label="indicates connection is still alive">
1910 <doc>
1911 The heartbeat control may be used to generate artificial network traffic when a connection
1912 is idle. If a connection is idle for more than twice the negotiated heartbeat delay, the
1913 peers MAY be considered disconnected.
1914 </doc>
1915 </control>
1916
1917 <!-- - Control: connection.close - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1918
1919 <control name="close" code="0xb" label="request a connection close">
1920 <doc>
1921 This control indicates that the sender wants to close the connection. The reason for close
1922 is indicated with the reply-code and reply-text. The channel this control is sent on MAY be
1923 used to indicate which channel caused the connection to close.
1924 </doc>
1925
1926 <implement role="client" handle="MUST" />
1927 <implement role="server" handle="MUST" />
1928
1929 <response name="close-ok" />
1930
1931 <field name="reply-code" type="close-code" label="the numeric reply code"
1932 required="true">
1933 <doc>
1934 Indicates the reason for connection closure.
1935 </doc>
1936 </field>
1937 <field name="reply-text" type="str8" label="the localized reply text">
1938 <doc>
1939 This text can be logged as an aid to resolving issues.
1940 </doc>
1941 </field>
1942 </control>
1943
1944 <!-- - Control: connection.close-ok - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1945
1946 <control name="close-ok" code="0xc" label="confirm a connection close">
1947 <doc>
1948 This control confirms a connection.close control and tells the recipient that it is safe to
1949 release resources for the connection and close the socket.
1950 </doc>
1951
1952 <rule name="reporting">
1953 <doc>
1954 A peer that detects a socket closure without having received a Close-Ok handshake control
1955 SHOULD log the error.
1956 </doc>
1957 </rule>
1958
1959 <implement role="client" handle="MUST" />
1960 <implement role="server" handle="MUST" />
1961 </control>
1962
1963 </class>
1964
1965 <!-- == Class: session ======================================================================= -->
1966
1967 <class name="session" code="0x2" label="session controls">
1968 <doc>
1969 A session is a named interaction between two peers. Session names are chosen by the upper
1970 layers and may be used indefinitely. The model layer may associate long-lived or durable state
1971 with a given session name. The session layer provides transport of commands associated with
1972 this interaction.
1973 </doc>
1974
1975 <doc>
1976 The controls defined within this class are specified in terms of the "sender" of commands and
1977 the "receiver" of commands. Since both client and server send and receive commands, the
1978 overall session dialog is symmetric, however the semantics of the session controls are defined
1979 in terms of a single sender/receiver pair, and it is assumed that the client and server will
1980 each contain both a sender and receiver implementation.
1981 </doc>
1982
1983 <rule name="attachment">
1984 <doc>
1985 The transport MUST be attached in order to use any control other than "attach", "attached",
1986 "detach", or "detached". A peer receiving any other control on a detached transport MUST
1987 discard it and send a session.detached with the "not-attached" reason code.
1988 </doc>
1989 </rule>
1990
1991 <role name="server" implement="MUST" />
1992 <role name="client" implement="MUST" />
1993
1994 <role name="sender" implement="MUST">
1995 <doc>
1996 The sender of commands.
1997 </doc>
1998 </role>
1999 <role name="receiver" implement="MUST">
2000 <doc>
2001 The receiver of commands.
2002 </doc>
2003 </role>
2004
2005 <domain name="name" type="vbin16" label="opaque session name">
2006 <doc>
2007 The session name uniquely identifies an interaction between two peers. It is scoped to a
2008 given authentication principal.
2009 </doc>
2010 </domain>
2011
2012 <domain name="detach-code" type="uint8" label="reason for detach">
2013 <enum>
2014 <choice name="normal" value="0">
2015 <doc>
2016 The session was detached by request.
2017 </doc>
2018 </choice>
2019 <choice name="session-busy" value="1">
2020 <doc>
2021 The session is currently attached to another transport.
2022 </doc>
2023 </choice>
2024 <choice name="transport-busy" value="2">
2025 <doc>
2026 The transport is currently attached to another session.
2027 </doc>
2028 </choice>
2029 <choice name="not-attached" value="3">
2030 <doc>
2031 The transport is not currently attached to any session.
2032 </doc>
2033 </choice>
2034 <choice name="unknown-ids" value="4">
2035 <doc>
2036 Command data was received prior to any use of the command-point control.
2037 </doc>
2038 </choice>
2039 </enum>
2040 </domain>
2041
2042 <domain name="commands" type="sequence-set" label="identifies a set of commands">
2043 </domain>
2044
2045 <struct name="header" size="1" pack="1">
2046 <doc>
2047 The session header appears on commands after the class and command id, but prior to command
2048 arguments.
2049 </doc>
2050
2051 <field name="sync" type="bit" label="request notification of completion">
2052 <doc>
2053 Request notification of completion for this command.
2054 </doc>
2055 </field>
2056 </struct>
2057
2058 <struct name="command-fragment" size="0" pack="0" label="byte-ranges within a set of commands">
2059
2060 <field name="command-id" type="sequence-no" required="true">
2061
2062 </field>
2063 <field name="byte-ranges" type="byte-ranges" required="true">
2064
2065 </field>
2066 </struct>
2067
2068 <domain name="command-fragments" type="array" label="an array of values of type
2069 command-fragment"/>
2070
2071 <control name="attach" code="0x1" label="attach to the named session">
2072 <doc>
2073 Requests that the current transport be attached to the named session. Success or failure
2074 will be indicated with an attached or detached response. This control is idempotent.
2075 </doc>
2076
2077 <rule name="one-transport-per-session">
2078 <doc>
2079 A session MUST NOT be attached to more than one transport at a time.
2080 </doc>
2081 </rule>
2082
2083 <rule name="one-session-per-transport">
2084 <doc>
2085 A transport MUST NOT be attached to more than one session at a time.
2086 </doc>
2087 </rule>
2088
2089 <rule name="idempotence">
2090 <doc>
2091 Attaching a session to its current transport MUST succeed and result in an attached
2092 response.
2093 </doc>
2094 </rule>
2095
2096 <rule name="scoping">
2097 <doc>
2098 Attachment to the same session name from distinct authentication principals MUST succeed.
2099 </doc>
2100 </rule>
2101
2102 <implement role="server" handle="MUST" />
2103 <implement role="client" handle="MAY" />
2104
2105 <response name="attached"/>
2106 <response name="detached"/>
2107
2108 <field name="name" type="name" label="the session name" required="true">
2109 <doc>
2110 Identifies the session to be attached to the current transport.
2111 </doc>
2112 </field>
2113
2114 <field name="force" type="bit" label="force attachment to a busy session">
2115 <doc>
2116 If set then a busy session will be forcibly detached from its other transport and
2117 reattached to the current transport.
2118 </doc>
2119 </field>
2120 </control>
2121
2122 <control name="attached" code="0x2" label="confirm attachment to the named session">
2123 <doc>
2124 Confirms successful attachment of the transport to the named session.
2125 </doc>
2126
2127 <implement role="server" handle="MUST" />
2128 <implement role="client" handle="MUST" />
2129
2130 <field name="name" type="name" label="the session name" required="true">
2131 <doc>
2132 Identifies the session now attached to the current transport.
2133 </doc>
2134 </field>
2135 </control>
2136
2137 <control name="detach" code="0x3" label="detach from the named session">
2138 <doc>
2139 Detaches the current transport from the named session.
2140 </doc>
2141
2142 <implement role="server" handle="MUST" />
2143 <implement role="client" handle="MUST" />
2144
2145 <response name="detached"/>
2146
2147 <field name="name" type="name" label="the session name" required="true">
2148 <doc>
2149 Identifies the session to detach.
2150 </doc>
2151 </field>
2152 </control>
2153
2154 <control name="detached" code="0x4" label="confirm detachment from the named session">
2155 <doc>
2156 Confirms detachment of the current transport from the named session.
2157 </doc>
2158
2159 <implement role="server" handle="MUST" />
2160 <implement role="client" handle="MUST" />
2161
2162 <field name="name" type="name" label="the session name" required="true">
2163 <doc>
2164 Identifies the detached session.
2165 </doc>
2166 </field>
2167 <field name="code" type="detach-code" label="the reason for detach" required="true">
2168 <doc>
2169 Identifies the reason for detaching from the named session.
2170 </doc>
2171 </field>
2172 </control>
2173
2174 <!--
2175 Execution state is the set of confirmed, and completed incoming commands, as well as the set
2176 of outgoing in-doubt commands held for replay.
2177 -->
2178
2179 <control name="request-timeout" code="0x5" label="requests the execution timeout be changed">
2180 <doc>
2181 This control may be sent by either the sender or receiver of commands. It requests that the
2182 execution timeout be changed. This is the minimum amount of time that a peer must preserve
2183 execution state for a detached session.
2184 </doc>
2185
2186 <rule name="maximum-granted-timeout">
2187 <doc>
2188 The handler of this request MUST set his timeout to the maximum allowed value less than or
2189 equal to the requested timeout, and MUST convey the chosen timeout in the response.
2190 </doc>
2191 </rule>
2192
2193 <implement role="sender" handle="MUST" />
2194 <implement role="receiver" handle="MUST" />
2195
2196 <response name="timeout"/>
2197
2198 <field name="timeout" type="uint32" label="the requested timeout">
2199 <doc>
2200 The requested timeout for execution state in seconds. If not set, this control requests
2201 that execution state is preserved indefinitely.
2202 </doc>
2203 </field>
2204 </control>
2205
2206 <control name="timeout" code="0x6" label="the granted timeout">
2207 <doc>
2208 This control may be sent by the either the sender or receiver of commands. It is a
2209 one-to-one reply to the request-timeout control that indicates the granted timeout for
2210 execution state.
2211 </doc>
2212
2213 <implement role="sender" handle="MUST" />
2214 <implement role="receiver" handle="MUST" />
2215
2216 <field name="timeout" type="uint32" label="the execution timeout">
2217 <doc>
2218 The timeout for execution state. If not set, then execution state is preserved
2219 indefinitely.
2220 </doc>
2221 </field>
2222 </control>
2223
2224 <control name="command-point" code="0x7"
2225 label="the command id and byte offset of subsequent data">
2226 <doc>
2227 This control is sent by the sender of commands and handled by the receiver of commands. This
2228 establishes the sequence numbers associated with all subsequent command data sent from the
2229 sender to the receiver. The subsequent command data will be numbered starting with the
2230 values supplied in this control and proceeding sequentially. This must be used at least once
2231 prior to sending any command data on newly attached transports.
2232 </doc>
2233
2234 <rule name="newly-attached-transports">
2235 <doc>
2236 If command data is sent on a newly attached transport the session MUST be detached with an
2237 "unknown-id" reason-code.
2238 </doc>
2239 </rule>
2240
2241 <rule name="zero-offset">
2242 <doc>
2243 If the offset is zero, the next data frame MUST have the first-frame and first-segment
2244 flags set. Violation of this is a framing error.
2245 </doc>
2246 </rule>
2247
2248 <rule name="nonzero-offset">
2249 <doc>
2250 If the offset is nonzero, the next data frame MUST NOT have both the first-frame and
2251 first-segment flag set. Violation of this is a framing error.
2252 </doc>
2253 </rule>
2254
2255 <implement role="receiver" handle="MUST" />
2256
2257 <field name="command-id" type="sequence-no" label="the command-id of the next command"
2258 required="true"/>
2259 <field name="command-offset" type="uint64" label="the byte offset within the command"
2260 required="true"/>
2261 </control>
2262
2263 <control name="expected" code="0x8" label="informs the peer of expected commands">
2264 <doc>
2265 This control is sent by the receiver of commands and handled by the sender of commands. It
2266 informs the sender of what commands and command fragments are expected at the receiver.
2267 This control is only sent in response to a flush control with the expected flag set. The
2268 expected control is never sent spontaneously.
2269 </doc>
2270
2271 <rule name="include-next-command">
2272 <doc>
2273 The set of expected commands MUST include the next command after the highest seen command.
2274 </doc>
2275 </rule>
2276
2277 <rule name="commands-empty-means-new-session">
2278 <doc>
2279 The set of expected commands MUST have zero elements if and only if the sender holds no
2280 execution state for the session (i.e. it is a new session).
2281 </doc>
2282 </rule>
2283
2284 <rule name="no-overlaps">
2285 <doc>
2286 If a command-id appears in the commands field, it MUST NOT appear in the fragments field.
2287 </doc>
2288 </rule>
2289
2290 <rule name="minimal-fragments">
2291 <doc>
2292 When choice is permitted, a command MUST appear in the commands field rather than the
2293 fragments field.
2294 </doc>
2295 </rule>
2296
2297 <implement role="sender" handle="MUST" />
2298
2299 <field name="commands" type="commands" label="expected commands" required="true"/>
2300 <field name="fragments" type="command-fragments" label="expected fragments" />
2301 </control>
2302
2303 <control name="confirmed" code="0x9" label="notifies of confirmed commands">
2304 <doc>
2305 This control is sent by the receiver of commands and handled by the sender of commands. This
2306 sends the set of commands that will definitely be completed by this peer to the sender. This
2307 excludes commands known by the receiver to be considered confirmed or complete at the
2308 sender.
2309 </doc>
2310 <doc>
2311 This control must be sent if the partner requests the set of confirmed commands using the
2312 session.flush control with the confirmed flag set.
2313 </doc>
2314 <doc>
2315 This control may be sent spontaneously. One reason for separating confirmation from
2316 completion is for large persistent messages, where the receipt (and storage to a durable
2317 store) of part of the message will result in less data needing to be replayed in the case of
2318 transport failure during transmission.
2319 </doc>
2320 <doc>
2321 A simple implementation of an AMQP client or server may be implemented to take no action on
2322 receipt of session.confirmed controls, and take action only when receiving
2323 session.completed controls.
2324 </doc>
2325 <doc>
2326 A simple implementation of an AMQP client or server may be implemented such that it never
2327 spontaneously sends session.confirmed and that when requested for the set of confirmed
2328 commands (via the session.flush control) it responds with the same set of commands as it
2329 would to when the set of completed commands was requested (trivially all completed commands
2330 are confirmed).
2331 </doc>
2332
2333 <rule name="durability">
2334 <doc>
2335 If a command has durable implications, it MUST NOT be confirmed until the fact of the
2336 command has been recorded on durable media.
2337 </doc>
2338 </rule>
2339
2340 <rule name="no-overlaps">
2341 <doc>
2342 If a command-id appears in the commands field, it MUST NOT appear in the fragments field.
2343 </doc>
2344 </rule>
2345
2346 <rule name="minimal-fragments">
2347 <doc>
2348 When choice is permitted, a command MUST appear in the commands field rather than the
2349 fragments field.
2350 </doc>
2351 </rule>
2352
2353 <implement role="sender" handle="MUST" />
2354
2355 <field name="commands" type="commands" label="entirely confirmed commands">
2356 <rule name="exclude-known-complete">
2357 <doc>
2358 Command-ids included in prior known-complete replies MUST be excluded from the set of
2359 all confirmed commands.
2360 </doc>
2361 </rule>
2362 </field>
2363 <field name="fragments" type="command-fragments" label="partially confirmed commands"/>
2364 </control>
2365
2366 <control name="completed" code="0xa" label="notifies of command completion">
2367 <doc>
2368 This control is sent by the receiver of commands, and handled by the sender of commands. It
2369 informs the sender of all commands completed by the receiver. This excludes commands known
2370 by the receiver to be considered complete at the sender.
2371 </doc>
2372
2373 <rule name="known-completed-reply">
2374 <doc>
2375 The sender MUST eventually reply with a known-completed set that covers the completed ids.
2376 </doc>
2377 </rule>
2378
2379 <rule name="delayed-reply">
2380 <doc>
2381 The known-complete reply MAY be delayed at the senders discretion if the timely-reply
2382 field is not set.
2383 </doc>
2384 </rule>
2385
2386 <rule name="merged-reply">
2387 <doc>
2388 Multiple replies may be merged by sending a single known-completed that includes the union
2389 of the merged command-id sets.
2390 </doc>
2391 </rule>
2392
2393 <implement role="sender" handle="MUST" />
2394
2395 <field name="commands" type="commands" label="completed commands">
2396 <doc>
2397 The ids of all completed commands. This excludes commands known by the receiver to be
2398 considered complete at the sender.
2399 </doc>
2400
2401 <rule name="completed-implies-confirmed">
2402 <doc>
2403 The sender MUST consider any completed commands to also be confirmed.
2404 </doc>
2405 </rule>
2406
2407 <rule name="exclude-known-complete">
2408 <doc>
2409 Command-ids included in prior known-complete replies MUST be excluded from the set of
2410 all completed commands.
2411 </doc>
2412 </rule>
2413 </field>
2414 <field name="timely-reply" type="bit">
2415 <doc>
2416 If set, the sender is no longer free to delay the known-completed reply.
2417 </doc>
2418 </field>
2419 </control>
2420
2421 <control name="known-completed" code="0xb" label="Inform peer of which commands are known to be
2422 completed">
2423 <doc>
2424 This control is sent by the sender of commands, and handled by the receiver of commands. It
2425 is sent in reply to one or more completed controls from the receiver. It informs the
2426 receiver that commands are known to be completed by the sender.
2427 </doc>
2428
2429 <rule name="stateless">
2430 <doc>
2431 The sender need not keep state to generate this reply. It is sufficient to reply to any
2432 completed control with an exact echo of the completed ids.
2433 </doc>
2434 </rule>
2435
2436 <implement role="receiver" handle="MUST" />
2437
2438 <field name="commands" type="commands" label="commands known to be complete">
2439 <doc>
2440 The set of completed commands for one or more session.completed controls.
2441 </doc>
2442
2443 <rule name="known-completed-implies-known-confirmed">
2444 <doc>
2445 The receiver MUST treat any of the specified commands to be considered by the sender as
2446 confirmed as well as completed.
2447 </doc>
2448 </rule>
2449 </field>
2450 </control>
2451
2452 <control name="flush" code="0xc" label="requests a session.completed">
2453 <doc>
2454 This control is sent by the sender of commands and handled by the receiver of commands. It
2455 requests that the receiver produce the indicated command sets. The receiver should issue the
2456 indicated sets at the earliest possible opportunity.
2457 </doc>
2458
2459 <implement role="receiver" handle="MUST" />
2460
2461 <field name="expected" type="bit" label="request notification of expected commands"/>
2462 <field name="confirmed" type="bit" label="request notification of confirmed commands"/>
2463 <field name="completed" type="bit" label="request notification of completed commands"/>
2464 </control>
2465
2466 <control name="gap" code="0xd" label="indicates missing segments in the stream">
2467 <doc>
2468 This control is sent by the sender of commands and handled by the receiver of commands. It
2469 sends command ranges for which there will be no further data forthcoming. The receiver
2470 should proceed with the next available commands that arrive after the gap.
2471 </doc>
2472
2473 <rule name="gap-confirmation-and-completion">
2474 <doc>
2475 The command-ids covered by a session.gap MUST be added to the completed and confirmed sets
2476 by the receiver.
2477 </doc>
2478 </rule>
2479
2480 <rule name="aborted-commands">
2481 <doc>
2482 If a session.gap covers a partially received command, the receiving peer MUST treat the
2483 command as aborted.
2484 </doc>
2485 </rule>
2486
2487 <rule name="completed-or-confirmed-commands">
2488 <doc>
2489 If a session.gap covers a completed or confirmed command, the receiving peer MUST continue
2490 to treat the command as completed or confirmed.
2491 </doc>
2492 </rule>
2493
2494 <implement role="receiver" handle="MUST" />
2495
2496 <field name="commands" type="commands">
2497 <doc>
2498 The set of command-ids that are contained in this gap.
2499 </doc>
2500 </field>
2501 </control>
2502
2503 </class>
2504
2505 <!-- == Class: execution ===================================================================== -->
2506
2507 <class name="execution" code="0x3" label="execution commands">
2508 <doc>
2509 The execution class provides commands that carry execution information about other model level
2510 commands.
2511 </doc>
2512
2513 <role name="server" implement="MUST"/>
2514 <role name="client" implement="MUST"/>
2515
2516 <domain name="error-code" type="uint16">
2517 <enum>
2518 <choice name="unauthorized-access" value="403">
2519 <doc>
2520 The client attempted to work with a server entity to which it has no access due to
2521 security settings.
2522 </doc>
2523 </choice>
2524
2525 <choice name="not-found" value="404">
2526 <doc>
2527 The client attempted to work with a server entity that does not exist.
2528 </doc>
2529 </choice>
2530
2531 <choice name="resource-locked" value="405">
2532 <doc>
2533 The client attempted to work with a server entity to which it has no access because
2534 another client is working with it.
2535 </doc>
2536 </choice>
2537
2538 <choice name="precondition-failed" value="406">
2539 <doc>
2540 The client requested a command that was not allowed because some precondition failed.
2541 </doc>
2542 </choice>
2543
2544 <choice name="resource-deleted" value="408">
2545 <doc>
2546 A server entity the client is working with has been deleted.
2547 </doc>
2548 </choice>
2549
2550 <choice name="illegal-state" value="409">
2551 <doc>
2552 The peer sent a command that is not permitted in the current state of the session.
2553 </doc>
2554 </choice>
2555
2556 <choice name="command-invalid" value="503">
2557 <doc>
2558 The command segments could not be decoded.
2559 </doc>
2560 </choice>
2561
2562 <choice name="resource-limit-exceeded" value="506">
2563 <doc>
2564 The client exceeded its resource allocation.
2565 </doc>
2566 </choice>
2567
2568 <choice name="not-allowed" value="530">
2569 <doc>
2570 The peer tried to use a command a manner that is inconsistent with the rules described
2571 in the specification.
2572 </doc>
2573 </choice>
2574
2575 <choice name="illegal-argument" value="531">
2576 <doc>
2577 The command argument is malformed, i.e. it does not fall within the specified domain.
2578 The illegal-argument exception can be raised on execution of any command which has
2579 domain valued fields.
2580 </doc>
2581 </choice>
2582
2583 <choice name="not-implemented" value="540">
2584 <doc>
2585 The peer tried to use functionality that is not implemented in its partner.
2586 </doc>
2587 </choice>
2588
2589 <choice name="internal-error" value="541">
2590 <doc>
2591 The peer could not complete the command because of an internal error. The peer may
2592 require intervention by an operator in order to resume normal operations.
2593 </doc>
2594 </choice>
2595
2596 <choice name="invalid-argument" value="542">
2597 <doc>
2598 An invalid argument was passed to a command, and the operation could not
2599 proceed. An invalid argument is not illegal (see illegal-argument), i.e. it matches
2600 the domain definition; however the particular value is invalid in this context.
2601 </doc>
2602 </choice>
2603 </enum>
2604 </domain>
2605
2606 <!-- - Command: execution.sync - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2607
2608 <command name="sync" code="0x1" label="request notification of completion for issued commands">
2609 <doc>
2610 This command is complete when all prior commands are completed.
2611 </doc>
2612
2613 <implement role="server" handle="MUST"/>
2614 <implement role="client" handle="MUST"/>
2615 </command>
2616
2617 <!-- - Command: execution.result - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2618
2619 <command name="result" code="0x2" label="carries execution results">
2620 <doc>
2621 This command carries data resulting from the execution of a command.
2622 </doc>
2623
2624 <implement role="server" handle="MUST"/>
2625 <implement role="client" handle="MUST"/>
2626
2627 <field name="command-id" type="sequence-no" required="true"/>
2628 <field name="value" type="struct32"/>
2629 </command>
2630
2631 <!-- - Command: execution.exception - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
2632
2633 <command name="exception" code="0x3" label="notifies a peer of an execution error">
2634 <doc>
2635 This command informs a peer of an execution exception. The command-id, when given,
2636 correlates the error to a specific command.
2637 </doc>
2638
2639 <implement role="client" handle="MUST"/>
2640 <implement role="server" handle="MUST"/>
2641
2642 <field name="error-code" type="error-code" required="true" label="error code indicating the
2643 type of error"/>
2644 <field name="command-id" type="sequence-no" label="exceptional command">
2645 <doc>
2646 The command-id of the command which caused the exception. If the exception was not caused
2647 by a specific command, this value is not set.
2648 </doc>
2649 </field>
2650 <field name="class-code" type="uint8" label="the class code of the command whose execution
2651 gave rise to the error (if appropriate)"/>
2652 <field name="command-code" type="uint8" label="the class code of the command whose execution
2653 gave rise to the error (if appropriate)"/>
2654 <field name="field-index" type="uint8" label="index of the exceptional field">
2655 <doc>
2656 The zero based index of the exceptional field within the arguments to the exceptional
2657 command. If the exception was not caused by a specific field, this value is not set.
2658 </doc>
2659 </field>
2660 <field name="description" type="str16" label="descriptive text on the exception">
2661 <doc>
2662 The description provided is implementation defined, but MUST be in the language
2663 appropriate for the selected locale. The intention is that this description is suitable
2664 for logging or alerting output.
2665 </doc>
2666 </field>
2667 <field name="error-info" type="map" label="map to carry additional information about the
2668 error"/>
2669
2670 </command>
2671
2672 </class>
2673
2674 <!-- == Class: message ======================================================================= -->
2675
2676 <class name="message" code="0x4" label="message transfer">
2677 <doc>
2678 The message class provides commands that support an industry-standard messaging model.
2679 </doc>
2680
2681 <doc type="picture" title="Transfer States">
2682 START:
2683
2684 The message has yet to be sent to the recipient.
2685
2686 NOT-ACQUIRED:
2687
2688 The message has been sent to the recipient, but is not
2689 acquired by the recipient.
2690
2691 ACQUIRED:
2692
2693 The message has been sent to and acquired by the recipient.
2694
2695 END:
2696
2697 The transfer is complete.
2698 </doc>
2699
2700 <doc type="picture" title="State Transitions"><![CDATA[
2701 *:TRANSFER (accept-mode=none) *:TRANSFER (acquire-mode=pre-acquired)
2702 +---------------------------------START------------------------------------------+
2703 | | |
2704 | | *:TRANSFER (acquire-mode=not-acquired) |
2705 | | |
2706 | R:RELEASE \|/ |
2707 | +-------------NOT-ACQUIRED<--+ |
2708 | | | | | R:ACQUIRE (if unavailable) |
2709 | | | +-----+ |
2710 | | | |
2711 | | | R:ACQUIRE (if available) |
2712 | | | |
2713 | | \|/ |
2714 | | ACQUIRED<-------------------------------------------+
2715 | | |
2716 | | | R:ACCEPT / R:REJECT / R:RELEASE
2717 | | |
2718 | | \|/
2719 | +------------->END]]>
2720 | /|\
2721 | |
2722 +-------------------------------+
2723 </doc>
2724
2725 <doc type="grammar">
2726 message = *:TRANSFER [ R:ACQUIRE ] [ R:ACCEPT / R:REJECT / R:RELEASE ]
2727 / *:RESUME
2728 / *:SET-FLOW-MODE
2729 / *:FLOW
2730 / *:STOP
2731 / C:SUBSCRIBE
2732 / C:CANCEL
2733 / C:FLUSH
2734 </doc>
2735
2736 <rule name="persistent-message">
2737 <doc>
2738 The server SHOULD respect the delivery-mode property of messages and SHOULD make a
2739 best-effort to hold persistent messages on a reliable storage mechanism.
2740 </doc>
2741 <doc type="scenario">
2742 Send a persistent message to queue, stop server, restart server and then verify whether
2743 message is still present. Assumes that queues are durable. Persistence without durable
2744 queues makes no sense.
2745 </doc>
2746 </rule>
2747
2748 <rule name="no-persistent-message-discard">
2749 <doc>
2750 The server MUST NOT discard a persistent message in case of a queue overflow.
2751 </doc>
2752 <doc type="scenario">
2753 Create a queue overflow situation with persistent messages and verify that messages do not
2754 get lost (presumably the server will write them to disk).
2755 </doc>
2756 </rule>
2757
2758 <rule name="throttling">
2759 <doc>
2760 The server MAY use the message.flow command to slow or stop a message publisher when
2761 necessary.
2762 </doc>
2763 </rule>
2764
2765 <rule name="non-persistent-message-overflow">
2766 <doc>
2767 The server MAY overflow non-persistent messages to persistent storage.
2768 </doc>
2769 </rule>
2770
2771 <rule name="non-persistent-message-discard">
2772 <doc>
2773 The server MAY discard or dead-letter non-persistent messages on a priority basis if the
2774 queue size exceeds some configured limit.
2775 </doc>
2776 </rule>
2777
2778 <rule name="min-priority-levels">
2779 <doc>
2780 The server MUST implement at least 2 priority levels for messages, where priorities 0 and
2781 9 are treated as two distinct levels.
2782 </doc>
2783 </rule>
2784
2785 <rule name="priority-level-implementation">
2786 <doc>
2787 The server SHOULD implement distinct priority levels in the following manner:
2788 </doc>
2789 <doc>
2790 If the server implements n distinct priorities then priorities 0 to 5 - ceiling(n/2) should
2791 be treated equivalently and should be the lowest effective priority. The priorities 4 +
2792 floor(n/2) should be treated equivalently and should be the highest effective priority. The
2793 priorities (5 - ceiling(n/2)) to (4 + floor(n/2)) inclusive must be treated as distinct
2794 priorities.
2795 </doc>
2796 <doc>
2797 Thus, for example, if 2 distinct priorities are implemented, then levels 0 to 4 are
2798 equivalent, and levels 5 to 9 are equivalent and levels 4 and 5 are distinct. If 3 distinct
2799 priorities are implements the 0 to 3 are equivalent, 5 to 9 are equivalent and 3, 4 and 5
2800 are distinct.
2801 </doc>
2802 <doc>
2803 This scheme ensures that if two priorities are distinct for a server which implements m
2804 separate priority levels they are also distinct for a server which implements n different
2805 priority levels where n > m.
2806 </doc>
2807 </rule>
2808
2809 <rule name="priority-delivery">
2810 <doc>
2811 The server MUST deliver messages of the same priority in order irrespective of their
2812 individual persistence.
2813 </doc>
2814 <doc type="scenario">
2815 Send a set of messages with the same priority but different persistence settings to a queue.
2816 Subscribe and verify that messages arrive in same order as originally published.
2817 </doc>
2818 </rule>
2819
2820 <role name="server" implement="MUST" />
2821 <role name="client" implement="MUST" />
2822
2823 <domain name="destination" type="str8" label="destination for a message">
2824 <doc>
2825 Specifies the destination to which the message is to be transferred.
2826 </doc>
2827 </domain>
2828
2829 <domain name="accept-mode" type="uint8" label="indicates a confirmation mode">
2830 <doc>
2831 Controls how the sender of messages is notified of successful transfer.
2832 </doc>
2833
2834 <enum>
2835 <choice name="explicit" value="0">
2836 <doc>
2837 Successful transfer is signaled by message.accept. An acquired message (whether
2838 acquisition was implicit as in pre-acquired mode or explicit as in not-acquired mode) is
2839 not considered transferred until a message.accept that includes the transfer command is
2840 received.
2841 </doc>
2842 </choice>
2843
2844 <choice name="none" value="1">
2845 <doc>
2846 Successful transfer is assumed when accept-mode is "pre-acquired". Messages transferred
2847 with an accept-mode of "not-acquired" cannot be acquired when accept-mode is "none".
2848 </doc>
2849 </choice>
2850 </enum>
2851 </domain>
2852
2853 <domain name="acquire-mode" type="uint8" label="indicates the transfer mode">
2854 <doc>
2855 Indicates whether a transferred message can be considered as automatically acquired or
2856 whether an explicit request is necessary in order to acquire it.
2857 </doc>
2858
2859 <enum>
2860 <choice name="pre-acquired" value="0">
2861 <doc>
2862 the message is acquired when the transfer starts
2863 </doc>
2864 </choice>
2865
2866 <choice name="not-acquired" value="1">
2867 <doc>
2868 the message is not acquired when it arrives, and must be explicitly acquired by the
2869 recipient
2870 </doc>
2871 </choice>
2872 </enum>
2873 </domain>
2874
2875 <domain name="reject-code" type="uint16" label="reject code for transfer">
2876 <doc>
2877 Code specifying the reason for a message reject.
2878 </doc>
2879 <enum>
2880 <choice name="unspecified" value="0">
2881 <doc>
2882 Rejected for an unspecified reason.
2883 </doc>
2884 </choice>
2885 <choice name="unroutable" value="1">
2886 <doc>
2887 Delivery was attempted but there were no queues which the message could be routed to.
2888 </doc>
2889 </choice>
2890 <choice name="immediate" value="2">
2891 <doc>
2892 The rejected message had the immediate flag set to true, but at the time of the transfer
2893 at least one of the queues to which it was to be routed did not have any subscriber able
2894 to take the message.
2895 </doc>
2896 </choice>
2897 </enum>
2898 </domain>
2899
2900 <domain name="resume-id" type="str16">
2901 <doc>
2902 A resume-id serves to identify partially transferred message content. The id is chosen by
2903 the sender, and must be unique to a given user. A resume-id is not expected to be unique
2904 across users.
2905 </doc>
2906 </domain>
2907
2908 <domain name="delivery-mode" type="uint8"
2909 label="indicates whether a message should be treated as transient or durable">
2910 <doc>
2911
2912 Used to set the reliability requirements for a message which is transferred to the server.
2913 </doc>
2914 <enum>
2915 <choice name="non-persistent" value="1">
2916 <doc>
2917 A non-persistent message may be lost in event of a failure, but the nature of the
2918 communication is such that an occasional message loss is tolerable. This is the lowest
2919 overhead mode. Non-persistent messages are delivered at most once only.
2920 </doc>
2921 </choice>
2922
2923 <choice name="persistent" value="2">
2924 <doc>
2925 A persistent message is one which must be stored on a persistent medium (usually hard
2926 drive) at every stage of delivery so that it will not be lost in event of failure (other
2927 than of the medium itself). This is normally accomplished with some additional overhead.
2928 A persistent message may be delivered more than once if there is uncertainty about the
2929 state of its delivery after a failure and recovery.
2930 </doc>
2931 </choice>
2932 </enum>
2933 </domain>
2934
2935 <domain name="delivery-priority" type="uint8"
2936 label="indicates the desired priority to assign to a message transfer">
2937 <doc>
2938 Used to assign a priority to a message transfer. Priorities range from 0 (lowest) to 9
2939 (highest).
2940 </doc>
2941 <enum>
2942 <choice name="lowest" value="0">
2943 <doc>
2944 Lowest possible priority message.
2945 </doc>
2946 </choice>
2947
2948 <choice name="lower" value="1">
2949 <doc>
2950 Very low priority message
2951 </doc>
2952 </choice>
2953
2954 <choice name="low" value="2">
2955 <doc>
2956 Low priority message.
2957 </doc>
2958 </choice>
2959
2960 <choice name="below-average" value="3">
2961 <doc>
2962 Below average priority message.
2963 </doc>
2964 </choice>
2965
2966 <choice name="medium" value="4">
2967 <doc>
2968 Medium priority message.
2969 </doc>
2970 </choice>
2971
2972
2973 <choice name="above-average" value="5">
2974 <doc>
2975 Above average priority message
2976 </doc>
2977 </choice>
2978
2979
2980 <choice name="high" value="6">
2981 <doc>
2982 High priority message
2983 </doc>
2984 </choice>
2985
2986 <choice name="higher" value="7">
2987 <doc>
2988 Higher priority message
2989 </doc>
2990 </choice>
2991
2992 <choice name="very-high" value="8">
2993 <doc>
2994 Very high priority message.
2995 </doc>
2996 </choice>
2997
2998 <choice name="highest" value="9">
2999 <doc>
3000 Highest possible priority message.
3001 </doc>
3002 </choice>
3003 </enum>
3004 </domain>
3005
3006 <struct name="delivery-properties" size="4" code="0x1" pack="2">
3007 <field name="discard-unroutable" type="bit" label="controls discard of unroutable messages">
3008 <doc>
3009 If set on a message that is not routable the broker can discard it. If not set, an
3010 unroutable message should be handled by reject when accept-mode is explicit; or by routing
3011 to the alternate-exchange if defined when accept-mode is none.
3012 </doc>
3013 </field>
3014
3015 <field name="immediate" type="bit" label="Consider message unroutable if it cannot be
3016 processed immediately">
3017 <doc>
3018 If the immediate flag is set to true on a message transferred to a Server, then the
3019 message should be considered unroutable (and not delivered to any queues) if, for any
3020 queue that it is to be routed to according to the standard routing behavior, there is not
3021 a subscription on that queue able to receive the message. The treatment of unroutable
3022 messages is dependent on the value of the discard-unroutable flag.
3023 </doc>
3024 <doc>
3025 The immediate flag is ignored on transferred to a Client.
3026 </doc>
3027 </field>
3028
3029 <field name="redelivered" type="bit" label="redelivery flag">
3030 <doc>
3031 This boolean flag indicates that the message may have been previously delivered to this
3032 or another client.
3033 </doc>
3034 <doc>
3035 If the redelivered flag is set on transfer to a Server, then any delivery of the message
3036 from that Server to a Client must also have the redelivered flag set to true.
3037 </doc>
3038 <rule name="implementation">
3039 <doc>
3040 The server MUST try to signal redelivered messages when it can. When redelivering a
3041 message that was not successfully accepted, the server SHOULD deliver it to the original
3042 client if possible.
3043 </doc>
3044 <doc type="scenario">
3045 Create a shared queue and publish a message to the queue. Subscribe using explicit
3046 accept-mode, but do not accept the message. Close the session, reconnect, and subscribe
3047 to the queue again. The message MUST arrive with the redelivered flag set.
3048 </doc>
3049 </rule>
3050 <rule name="hinting">
3051 <doc>
3052 The client should not rely on the redelivered field to detect duplicate messages where
3053 publishers may themselves produce duplicates. A fully robust client should be able to
3054 track duplicate received messages on non-transacted, and locally-transacted sessions.
3055 </doc>
3056 </rule>
3057 </field>
3058
3059 <field name="priority" type="delivery-priority" label="message priority, 0 to 9"
3060 required="true">
3061 <doc> Message priority, which can be between 0 and 9. Messages with higher priorities may be
3062 delivered before those with lower priorities. </doc>
3063 </field>
3064
3065 <field name="delivery-mode" type="delivery-mode" label="message persistence requirement"
3066 required="true">
3067 <doc> The delivery mode may be non-persistent or persistent. </doc>
3068 </field>
3069
3070 <field name="ttl" type="uint64" label="time to live in ms">
3071 <doc> Duration in milliseconds for which the message should be considered "live". If this is
3072 set then a message expiration time will be computed based on the current time plus this
3073 value. Messages that live longer than their expiration time will be discarded (or dead
3074 lettered).</doc>
3075 <rule name="ttl-decrement">
3076 <doc>
3077 If a message is transferred between brokers before delivery to a final subscriber the
3078 ttl should be decremented before peer to peer transfer and both timestamp and expiration
3079 should be cleared.
3080 </doc>
3081 </rule>
3082 </field>
3083
3084 <field name="timestamp" type="datetime" label="message timestamp">
3085 <doc>
3086 The timestamp is set by the broker on arrival of the message.
3087 </doc>
3088 </field>
3089
3090 <field name="expiration" type="datetime" label="message expiration time">
3091 <doc>
3092 The expiration header assigned by the broker. After receiving the message the broker sets
3093 expiration to the sum of the ttl specified in the publish command and the current time.
3094 (ttl=expiration - timestamp)
3095 </doc>
3096 </field>
3097
3098 <field name="exchange" type="exchange.name" label="originating exchange">
3099 <doc>
3100 Identifies the exchange specified in the destination field of the message.transfer used to
3101 publish the message. This MUST be set by the broker upon receipt of a message.
3102 </doc>
3103 </field>
3104
3105 <field name="routing-key" type="str8" label="message routing key">
3106 <doc>
3107 The value of the key determines to which queue the exchange will send the message. The way
3108 in which keys are used to make this routing decision depends on the type of exchange to
3109 which the message is sent. For example, a direct exchange will route a message to a queue
3110 if that queue is bound to the exchange with a binding-key identical to the routing-key of
3111 the message.
3112 </doc>
3113 </field>
3114
3115 <field name="resume-id" type="resume-id" label="global id for message transfer">
3116 <doc>
3117 When a resume-id is provided the recipient MAY use it to retain message data should the
3118 session expire while the message transfer is still incomplete.
3119 </doc>
3120 </field>
3121
3122 <field name="resume-ttl" type="uint64" label="ttl in ms for interrupted message data">
3123 <doc>
3124 When a resume-ttl is provided the recipient MAY use it has a guideline for how long to
3125 retain the partially complete data when a resume-id is specified. If no resume-id is
3126 specified then this value should be ignored.
3127 </doc>
3128 </field>
3129 </struct>
3130
3131 <struct name="fragment-properties" size="4" code="0x2" pack="2">
3132 <doc>
3133 These properties permit the transfer of message fragments. These may be used in conjunction
3134 with byte level flow control to limit the rate at which large messages are received. Only
3135 the first fragment carries the delivery-properties and message-properties.
3136
3137 Syntactically each fragment appears as a complete message to the lower layers of the
3138 protocol, however the model layer is required to treat all the fragments as a single
3139 message. For example all fragments must be delivered to the same client. In pre-acquired
3140 mode, no message fragments can be delivered by the broker until the entire message has been
3141 received.
3142 </doc>
3143
3144 <field name="first" type="bit" default="1">
3145 <doc>True if this fragment contains the start of the message, false otherwise.</doc>
3146 </field>
3147
3148 <field name="last" type="bit" default="1">
3149 <doc>True if this fragment contains the end of the message, false otherwise.</doc>
3150 </field>
3151
3152 <field name="fragment-size" type="uint64">
3153 <doc>This field may optionally contain the size of the fragment.</doc>
3154 </field>
3155 </struct>
3156
3157 <struct name="reply-to" size="2" pack="2">
3158 <doc>The reply-to domain provides a simple address structure for replying to to a message to a
3159 destination within the same virtual-host.</doc>
3160 <field name="exchange" type="exchange.name" label="the name of the exchange to reply to"/>
3161 <field name="routing-key" type="str8" label="the routing-key to use when replying"/>
3162 </struct>
3163
3164 <struct name="message-properties" size="4" code="0x3" pack="2">
3165 <field name="content-length" type="uint64" label="length of the body segment in bytes">
3166 <doc>
3167 The length of the body segment in bytes.
3168 </doc>
3169 </field>
3170
3171 <field name="message-id" type="uuid" label="application message identifier">
3172 <doc>
3173 Message-id is an optional property of UUID type which uniquely identifies a message within
3174 the message system. The message producer is usually responsible for setting the
3175 message-id. The server MAY discard a message as a duplicate if the value of the message-id
3176 matches that of a previously received message. Duplicate messages MUST still be accepted
3177 if transferred with an accept-mode of "explicit".
3178 </doc>
3179
3180 <rule name="unique">
3181 <doc>
3182 A message-id MUST be unique within a given server instance. A message-id SHOULD be
3183 globally unique (i.e. across different systems).
3184 </doc>
3185 </rule>
3186
3187 <rule name="immutable">
3188 <doc>
3189 A message ID is immutable. Once set, a message-id MUST NOT be changed or reassigned,
3190 even if the message is replicated, resent or sent to multiple queues.
3191 </doc>
3192 </rule>
3193 </field>
3194
3195 <field name="correlation-id" type="vbin16" label="application correlation identifier">
3196 <doc>
3197 This is a client-specific id that may be used to mark or identify messages between
3198 clients. The server ignores this field.
3199 </doc>
3200 </field>
3201
3202 <field name="reply-to" type="reply-to" label="destination to reply to">
3203 <doc>
3204 The destination of any message that is sent in reply to this message.
3205 </doc>
3206 </field>
3207
3208 <field name="content-type" type="str8" label="MIME content type">
3209 <doc>
3210 The RFC-2046 MIME type for the message content (such as "text/plain"). This is set by the
3211 originating client.
3212 </doc>
3213 </field>
3214
3215 <field name="content-encoding" type="str8" label="MIME content encoding">
3216 <doc>
3217 The encoding for character-based message content. This is set by the originating client.
3218 Examples include UTF-8 and ISO-8859-15.
3219 </doc>
3220 </field>
3221
3222 <field name="user-id" type="vbin16" label="creating user id">
3223 <doc>
3224 The identity of the user responsible for producing the message. The client sets this
3225 value, and it is authenticated by the broker.
3226 </doc>
3227
3228 <rule name="authentication">
3229 <doc>
3230 The server MUST produce an unauthorized-access exception if the user-id field is set to
3231 a principle for which the client is not authenticated.
3232 </doc>
3233 </rule>
3234 </field>
3235
3236 <field name="app-id" type="vbin16" label="creating application id">
3237 <doc>
3238 The identity of the client application responsible for producing the message.
3239 </doc>
3240 </field>
3241
3242 <field name="application-headers" type="map" label="application specific headers table">
3243 <doc>
3244 This is a collection of user-defined headers or properties which may be set by the
3245 producing client and retrieved by the consuming client.
3246 </doc>
3247 </field>
3248 </struct>
3249
3250 <domain name="flow-mode" type="uint8" label="the flow-mode for allocating flow credit">
3251 <enum>
3252 <choice name="credit" value="0">
3253 <doc>
3254 Credit based flow control.
3255 </doc>
3256 </choice>
3257
3258 <choice name="window" value="1">
3259 <doc>
3260 Window based flow control.
3261 </doc>
3262 </choice>
3263 </enum>
3264 </domain>
3265
3266 <domain name="credit-unit" type="uint8" label="specifies the unit of credit balance">
3267 <enum>
3268 <choice name="message" value="0">
3269 <doc>Indicates a value specified in messages.</doc>
3270 </choice>
3271 <choice name="byte" value="1">
3272 <doc>Indicates a value specified in bytes.</doc>
3273 </choice>
3274 </enum>
3275 </domain>
3276
3277 <!-- - Command: message.transfer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3278
3279 <command name="transfer" code="0x1" label="transfer a message">
3280 <doc>
3281 This command transfers a message between two peers. When a client uses this command to
3282 publish a message to a broker, the destination identifies a specific exchange. The message
3283 will then be routed to queues as defined by the exchange configuration.
3284
3285 The client may request a broker to transfer messages to it, from a particular queue, by
3286 issuing a subscribe command. The subscribe command specifies the destination that the broker
3287 should use for any resulting transfers.
3288 </doc>
3289
3290 <rule name="transactional-publish">
3291 <doc>
3292 If a transfer to an exchange occurs within a transaction, then it is not available from
3293 the queue until the transaction commits. It is not specified whether routing takes place
3294 when the transfer is received or when the transaction commits.
3295 </doc>
3296 </rule>
3297
3298 <implement role="server" handle="MUST" />
3299 <implement role="client" handle="MUST" />
3300
3301
3302 <field name="destination" type="destination" label="message destination">
3303 <doc>
3304 Specifies the destination to which the message is to be transferred.
3305 </doc>
3306
3307 <rule name="blank-destination">
3308 <doc>
3309 The server MUST accept a blank destination to mean the default exchange.
3310 </doc>
3311 </rule>
3312
3313 <exception name="nonexistent-exchange" error-code="not-found">
3314 <doc>
3315 If the destination refers to an exchange that does not exist, the peer MUST raise a
3316 session exception.
3317 </doc>
3318 </exception>
3319 </field>
3320
3321 <field name="accept-mode" type="accept-mode" required="true">
3322 <doc>
3323 Indicates whether message.accept, session.complete, or nothing at all is required to
3324 indicate successful transfer of the message.
3325 </doc>
3326 </field>
3327
3328 <field name="acquire-mode" type="acquire-mode" required="true">
3329 <doc>
3330 Indicates whether or not the transferred message has been acquired.
3331 </doc>
3332 </field>
3333
3334 <segments>
3335 <header>
3336 <entry type="delivery-properties"/>
3337 <entry type="fragment-properties"/>
3338 <entry type="message-properties"/>
3339 </header>
3340 <body/>
3341 </segments>
3342 </command>
3343
3344 <!-- - Command: message.accept - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3345
3346 <command name="accept" code="0x2" label="reject a message">
3347 <doc>
3348 Accepts the message. Once a transfer is accepted, the command-id may no longer be referenced
3349 from other commands.
3350 </doc>
3351
3352 <rule name="acquisition">
3353 <doc>
3354 The recipient MUST have acquired a message in order to accept it.
3355 </doc>
3356 </rule>
3357
3358 <implement role="server" handle="MUST" />
3359 <implement role="client" handle="MUST" />
3360
3361 <field name="transfers" type="session.commands" required="true">
3362 <doc>
3363 Identifies the messages previously transferred that should be accepted.
3364 </doc>
3365 </field>
3366 </command>
3367
3368 <!-- - Command: message.reject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3369
3370 <command name="reject" code="0x3" label="reject a message">
3371 <doc>
3372 Indicates that the message transfers are unprocessable in some way. A server may reject a
3373 message if it is unroutable. A client may reject a message if it is invalid. A message may
3374 be rejected for other reasons as well. Once a transfer is rejected, the command-id may no
3375 longer be referenced from other commands.
3376 </doc>
3377
3378 <rule name="alternate-exchange">
3379 <doc>
3380 When a client rejects a message, the server MUST deliver that message to the
3381 alternate-exchange on the queue from which it was delivered. If no alternate-exchange is
3382 defined for that queue the broker MAY discard the message.
3383 </doc>
3384 </rule>
3385
3386 <rule name="acquisition">
3387 <doc>
3388 The recipient MUST have acquired a message in order to reject it. If the message is not
3389 acquired any reject MUST be ignored.
3390 </doc>
3391 </rule>
3392
3393 <implement role="server" handle="MUST" />
3394 <implement role="client" handle="MUST" />
3395
3396 <field name="transfers" type="session.commands" required="true">
3397 <doc>
3398 Identifies the messages previously transferred that should be rejected.
3399 </doc>
3400 </field>
3401 <field name="code" type="reject-code" required="true">
3402 <doc>
3403 Code describing the reason for rejection.
3404 </doc>
3405 </field>
3406 <field name="text" type="str8" label="informational text for message reject">
3407 <doc>
3408 Text describing the reason for rejection.
3409 </doc>
3410 </field>
3411 </command>
3412
3413 <!-- - Command: message.release - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3414
3415 <command name="release" code="0x4" label="release a message">
3416 <doc>
3417 Release previously transferred messages. When acquired messages are released, they become
3418 available for acquisition by any subscriber. Once a transfer is released, the command-id may
3419 no longer be referenced from other commands.
3420 </doc>
3421
3422 <rule name="ordering">
3423 <doc>
3424 Acquired messages that have been released MAY subsequently be delivered out of order.
3425 Implementations SHOULD ensure that released messages keep their position with respect to
3426 undelivered messages of the same priority.
3427 </doc>
3428 </rule>
3429
3430 <implement role="server" handle="MUST" />
3431 <implement role="client" handle="MAY" />
3432
3433 <field name="transfers" type="session.commands" required="true">
3434 <doc>
3435 Indicates the messages to be released.
3436 </doc>
3437 </field>
3438 <field name="set-redelivered" type="bit" label="mark the released messages as redelivered">
3439 <doc>
3440 By setting set-redelivered to true, any acquired messages released to a queue with this
3441 command will be marked as redelivered on their next transfer from that queue. If this flag
3442 is not set, then an acquired message will retain its original redelivered status on the
3443 queue. Messages that are not acquired are unaffected by the value of this flag.
3444 </doc>
3445 </field>
3446 </command>
3447
3448 <!-- - Command: message.acquire - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3449
3450 <command name="acquire" code="0x5" label="acquire messages for consumption">
3451 <doc>
3452 Acquires previously transferred messages for consumption. The acquired ids (if any) are
3453 sent via message.acquired.
3454 </doc>
3455
3456 <rule name="one-to-one">
3457 <doc>
3458 Each acquire MUST produce exactly one message.acquired even if it is empty.
3459 </doc>
3460 </rule>
3461
3462 <implement role="server" handle="MUST" />
3463
3464 <field name="transfers" type="session.commands" required="true">
3465 <doc>
3466 Indicates the messages to be acquired.
3467 </doc>
3468 </field>
3469
3470 <result>
3471 <struct name="acquired" size="4" code="0x4" pack="2" label="indicates acquired messages">
3472 <doc>
3473 Identifies a set of previously transferred messages that have now been acquired.
3474 </doc>
3475
3476 <field name="transfers" type="session.commands" required="true">
3477 <doc>
3478 Indicates the acquired messages.
3479 </doc>
3480 </field>
3481 </struct>
3482 </result>
3483 </command>
3484
3485 <!-- - Command: message.resume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3486
3487 <command name="resume" code="0x6" label="resume an interrupted message transfer">
3488 <doc>
3489 This command resumes an interrupted transfer. The recipient should return the amount of
3490 partially transferred data associated with the given resume-id, or zero if there is no data
3491 at all. If a non-zero result is returned, the recipient should expect to receive message
3492 fragment(s) containing the remainder of the interrupted message.
3493 </doc>
3494
3495 <implement role="server" handle="MUST" />
3496 <implement role="client" handle="MUST" />
3497
3498 <field name="destination" type="destination">
3499 <doc>
3500 The destination to which the remaining message fragments are transferred.
3501 </doc>
3502
3503 <exception name="destination-not-found" error-code="not-found">
3504 <doc>If the destination does not exist, the recipient MUST close the session.</doc>
3505 </exception>
3506 </field>
3507
3508 <field name="resume-id" type="resume-id" required="true">
3509 <doc>
3510 The name of the transfer being resumed.
3511 </doc>
3512
3513 <rule name="unknown-resume-id">
3514 <doc>If the resume-id is not known, the recipient MUST return an offset of zero.</doc>
3515 </rule>
3516 </field>
3517
3518 <result>
3519 <struct name="message-resume-result" size="4" code="0x5" pack="2">
3520 <field name="offset" type="uint64">
3521 <doc>
3522 Indicates the amount of data already transferred.
3523 </doc>
3524 </field>
3525 </struct>
3526 </result>
3527 </command>
3528
3529 <!-- - Command: message.subscribe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3530
3531 <command name="subscribe" code="0x7" label="start a queue subscription">
3532 <doc> This command asks the server to start a "subscription", which is a request for messages
3533 from a specific queue. Subscriptions last as long as the session they were created on, or
3534 until the client cancels them. </doc>
3535
3536 <rule name="simultaneous-subscriptions">
3537 <doc> The server SHOULD support at least 16 subscriptions per queue, and ideally, impose no
3538 limit except as defined by available resources. </doc>
3539 <doc type="scenario"> Create a queue and create subscriptions on that queue until the server
3540 closes the connection. Verify that the number of subscriptions created was at least
3541 sixteen and report the total number. </doc>
3542 </rule>
3543
3544 <rule name="default-flow-mode">
3545 <doc> The default flow mode for new subscriptions is window-mode. </doc>
3546 </rule>
3547
3548 <exception name="queue-deletion" error-code="resource-deleted">
3549 <doc>
3550 If the queue for this subscription is deleted, any subscribing sessions MUST be closed.
3551 This exception may occur at any time after the subscription has been completed.
3552 </doc>
3553 </exception>
3554
3555 <exception name="queue-not-found" error-code="not-found">
3556 <doc> If the queue for this subscription does not exist, then the subscribing session MUST
3557 be closed. </doc>
3558 </exception>
3559
3560 <rule name="initial-credit">
3561 <doc>
3562 Immediately after a subscription is created, the initial byte and message credit for that
3563 destination is zero.
3564 </doc>
3565 </rule>
3566
3567 <implement role="server" handle="MUST"/>
3568
3569 <field name="queue" type="queue.name" required="true">
3570 <doc> Specifies the name of the subscribed queue. </doc>
3571 </field>
3572
3573 <field name="destination" type="destination" label="incoming message destination">
3574 <doc> The client specified name for the subscription. This is used as the destination for
3575 all messages transferred from this subscription. The destination is scoped to the session.
3576 </doc>
3577
3578 <exception name="unique-subscriber-destination" error-code="not-allowed">
3579 <doc> The client MUST NOT specify a destination that refers to an existing subscription on
3580 the same session. </doc>
3581 <doc type="scenario"> Attempt to create two subscriptions on the same session with the
3582 same non-empty destination. </doc>
3583 </exception>
3584 </field>
3585
3586 <field name="accept-mode" type="accept-mode" required="true">
3587 <doc> The accept-mode to use for messages transferred from this subscription. </doc>
3588 </field>
3589
3590 <field name="acquire-mode" type="acquire-mode" required="true">
3591 <doc> The acquire-mode to use for messages transferred from this subscription. </doc>
3592 </field>
3593
3594 <field name="exclusive" type="bit" label="request exclusive access">
3595 <doc> Request an exclusive subscription. This prevents other subscribers from subscribing to
3596 the queue. </doc>
3597
3598 <exception name="in-use" error-code="resource-locked">
3599 <doc> The server MUST NOT grant an exclusive subscription to a queue that already has
3600 subscribers. </doc>
3601 <doc type="scenario"> Open two connections to a server, and in one connection create a
3602 shared (non-exclusive) queue and then subscribe to the queue. In the second connection
3603 attempt to subscribe to the same queue using the exclusive option. </doc>
3604 </exception>
3605 </field>
3606
3607 <field name="resume-id" type="resume-id">
3608 <doc> Requests that the broker use the supplied resume-id when transferring messages for
3609 this subscription. </doc>
3610 </field>
3611
3612 <field name="resume-ttl" type="uint64">
3613 <doc> Requested duration in milliseconds for the broker use as resume-ttl when transferring
3614 messages for this subscription. </doc>
3615 </field>
3616
3617 <field name="arguments" type="map" label="arguments for vendor extensions">
3618 <doc> The syntax and semantics of these arguments depends on the providers implementation.
3619 </doc>
3620 </field>
3621 </command>
3622
3623 <!-- - Command: message.cancel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3624
3625 <command name="cancel" code="0x8" label="end a queue subscription">
3626 <doc>
3627 This command cancels a subscription. This does not affect already delivered messages, but it
3628 does mean the server will not send any more messages for that subscription. The client may
3629 receive an arbitrary number of messages in between sending the cancel command and receiving
3630 notification that the cancel command is complete.
3631 </doc>
3632
3633 <rule name="post-cancel-transfer-resolution">
3634 <doc>
3635 Canceling a subscription MUST NOT affect pending transfers. A transfer made prior to
3636 canceling transfers to the destination MUST be able to be accepted, released, acquired, or
3637 rejected after the subscription is canceled.
3638 </doc>
3639 </rule>
3640
3641 <implement role="server" handle="MUST" />
3642
3643 <field name="destination" type="destination" required="true">
3644 <exception name="subscription-not-found" error-code="not-found">
3645 <doc>
3646 If the subscription specified by the destination is not found, the server MUST close the
3647 session.
3648 </doc>
3649 </exception>
3650 </field>
3651 </command>
3652
3653 <!-- - Command: message.set-flow-mode - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3654
3655 <command name="set-flow-mode" code="0x9" label="set the flow control mode">
3656 <doc>
3657 Sets the mode of flow control used for a given destination to either window or credit based
3658 flow control.
3659
3660 With credit based flow control, the sender of messages continually maintains its current
3661 credit balance with the recipient. The credit balance consists of two values, a message
3662 count, and a byte count. Whenever message data is sent, both counts must be decremented.
3663 If either value reaches zero, the flow of message data must stop. Additional credit is
3664 received via the message.flow command.
3665
3666 The sender MUST NOT send partial assemblies. This means that if there is not enough byte
3667 credit available to send a complete message, the sender must either wait or use message
3668 fragmentation (see the fragment-properties header struct) to send the first part of the
3669 message data in a complete assembly.
3670
3671 Window based flow control is identical to credit based flow control, however message
3672 transfer completion implicitly grants a single unit of message credit, and the size of the
3673 message in byte credits for each completed message transfer. Completion of the transfer
3674 command with session.completed is the only way credit is implicitly updated; message.accept,
3675 message.release, message.reject, tx.commit and tx.rollback have no effect on the outstanding
3676 credit balances.
3677 </doc>
3678
3679 <rule name="byte-accounting">
3680 <doc>
3681 The byte count is decremented by the payload size of each transmitted frame with segment
3682 type header or body appearing within a message.transfer command. Note that the payload
3683 size is the frame size less the frame header size.
3684 </doc>
3685 </rule>
3686
3687 <rule name="mode-switching">
3688 <doc>
3689 Mode switching may only occur if both the byte and message credit balance are zero. There
3690 are three ways for a recipient of messages to be sure that the sender's credit balances
3691 are zero:
3692
3693 1) The recipient may send a message.stop command to the sender. When the recipient
3694 receives notification of completion for the message.stop command, it knows that the
3695 sender's credit is zero.
3696
3697 2) The recipient may perform the same steps described in (1) with the message.flush
3698 command substituted for the message.stop command.
3699
3700 3) Immediately after a subscription is created with message.subscribe, the credit for
3701 that destination is zero.
3702 </doc>
3703 </rule>
3704
3705 <rule name="default-flow-mode">
3706 <doc>
3707 Prior to receiving an explicit set-flow-mode command, a peer MUST consider the flow-mode
3708 to be window.
3709 </doc>
3710 </rule>
3711
3712 <implement role="server" handle="MUST" />
3713 <implement role="client" handle="MUST" />
3714
3715 <field name="destination" type="destination"/>
3716 <field name="flow-mode" type="flow-mode" required="true">
3717 <doc>
3718 The new flow control mode.
3719 </doc>
3720 </field>
3721 </command>
3722
3723 <!-- - Command: message.flow - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3724
3725 <command name="flow" code="0xa" label="control message flow">
3726 <doc>
3727 This command controls the flow of message data to a given destination. It is used by the
3728 recipient of messages to dynamically match the incoming rate of message flow to its
3729 processing or forwarding capacity. Upon receipt of this command, the sender must add "value"
3730 number of the specified unit to the available credit balance for the specified destination.
3731 A value of (0xFFFFFFFF) indicates an infinite amount of credit. This disables any limit for
3732 the given unit until the credit balance is zeroed with message.stop or message.flush.
3733 </doc>
3734
3735 <!-- throws no-such-destination -->
3736
3737 <implement role="server" handle="MUST" />
3738 <implement role="client" handle="MUST" />
3739
3740 <field name="destination" type="destination"/>
3741 <field name="unit" type="credit-unit" required="true">
3742 <doc>
3743 The unit of value.
3744 </doc>
3745 </field>
3746 <field name="value" type="uint32">
3747 <doc>
3748 If the value is not set then this indicates an infinite amount of credit.
3749 </doc>
3750 </field>
3751 </command>
3752
3753 <!-- - Command: message.flush - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3754
3755 <command name="flush" code="0xb" label="force the sending of available messages">
3756 <doc>
3757 Forces the sender to exhaust his credit supply. The sender's credit will always be zero when
3758 this command completes. The command completes when immediately available message data has
3759 been transferred, or when the credit supply is exhausted.
3760 </doc>
3761
3762 <implement role="server" handle="MUST" />
3763
3764 <field name="destination" type="destination"/>
3765 </command>
3766
3767 <!-- - Command: message.stop - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3768
3769 <command name="stop" code="0xc" label="stop the sending of messages">
3770 <doc>
3771 On receipt of this command, a producer of messages MUST set his credit to zero for the given
3772 destination. When notifying of completion, credit MUST be zero and no further messages will
3773 be sent until such a time as further credit is received.
3774 </doc>
3775
3776 <implement role="server" handle="MUST" />
3777 <implement role="client" handle="MUST" />
3778
3779 <field name="destination" type="destination"/>
3780 </command>
3781
3782 </class>
3783
3784 <!-- == Class: tx ============================================================================ -->
3785
3786 <class name="tx" code="0x5" label="work with standard transactions">
3787 <doc>
3788 Standard transactions provide so-called "1.5 phase commit". We can ensure that work is never
3789 lost, but there is a chance of confirmations being lost, so that messages may be resent.
3790 Applications that use standard transactions must be able to detect and ignore duplicate
3791 messages.
3792 </doc>
3793
3794 <doc type="grammar">
3795 tx = C:SELECT
3796 / C:COMMIT
3797 / C:ROLLBACK
3798 </doc>
3799
3800 <!-- XXX: this isn't really a rule, as stated there is no way for
3801 a client library to implement this -->
3802 <rule name="duplicate-tracking">
3803 <doc>
3804 An client using standard transactions SHOULD be able to track all messages received within a
3805 reasonable period, and thus detect and reject duplicates of the same message. It SHOULD NOT
3806 pass these to the application layer.
3807 </doc>
3808 </rule>
3809
3810 <role name="server" implement="SHOULD" />
3811
3812 <!-- - Command: tx.select - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3813
3814 <command name="select" code="0x1" label="select standard transaction mode">
3815 <doc>
3816 This command sets the session to use standard transactions. The client must use this command
3817 exactly once on a session before using the Commit or Rollback commands.
3818 </doc>
3819
3820 <exception name="exactly-once" error-code="illegal-state">
3821 <doc>
3822 A client MUST NOT select standard transactions on a session that is already transactional.
3823 </doc>
3824 </exception>
3825
3826 <exception name="no-dtx" error-code="illegal-state">
3827 <doc>
3828 A client MUST NOT select standard transactions on a session that is already enlisted in a
3829 distributed transaction.
3830 </doc>
3831 </exception>
3832
3833 <exception name="explicit-accepts" error-code="not-allowed">
3834 <doc>
3835 On a session on which tx.select has been issued, a client MUST NOT issue a
3836 message.subscribe command with the accept-mode property set to any value other than
3837 explicit. Similarly a tx.select MUST NOT be issued on a session on which a there is a non
3838 cancelled subscriber with accept-mode of none.
3839 </doc>
3840 </exception>
3841
3842 <implement role="server" handle="MUST" />
3843 </command>
3844
3845 <!-- - Command: tx.commit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3846
3847 <command name="commit" code="0x2" label="commit the current transaction">
3848 <doc>
3849 This command commits all messages published and accepted in the current transaction. A
3850 new transaction starts immediately after a commit.
3851 </doc>
3852 <doc>
3853 In more detail, the commit acts on all messages which have been transferred from the Client
3854 to the Server, and on all acceptances of messages sent from Server to Client. Since the
3855 commit acts on commands sent in the same direction as the commit command itself, there is no
3856 ambiguity on the scope of the commands being committed. Further, the commit will not be
3857 completed until all preceding commands which it affects have been completed.
3858 </doc>
3859 <doc>
3860 Since transactions act on explicit accept commands, the only valid accept-mode for message
3861 subscribers is explicit. For transferring messages from Client to Server (publishing) all
3862 accept-modes are permitted.
3863 </doc>
3864
3865 <exception name="select-required" error-code="illegal-state">
3866 <doc>
3867 A client MUST NOT issue tx.commit on a session that has not been selected for standard
3868 transactions with tx.select.
3869 </doc>
3870 </exception>
3871
3872
3873
3874 <implement role="server" handle="MUST" />
3875 </command>
3876
3877 <!-- - Command: tx.rollback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
3878
3879 <command name="rollback" code="0x3" label="abandon the current transaction">
3880 <doc>
3881 This command abandons the current transaction. In particular the transfers from Client to
3882 Server (publishes) and accepts of transfers from Server to Client which occurred in the
3883 current transaction are discarded. A new transaction starts immediately after a rollback.
3884 </doc>
3885 <doc>
3886 In more detail, when a rollback is issued, any the effects of transfers which occurred from
3887 Client to Server are discarded. The Server will issue completion notification for all such
3888 transfers prior to the completion of the rollback. Similarly the effects of any
3889 message.accept issued from Client to Server prior to the issuance of the tx.rollback will be
3890 discarded; and notification of completion for all such commands will be issued before the
3891 issuance of the completion for the rollback.
3892 </doc>
3893 <doc>
3894 After the completion of the rollback, the client will still hold the messages which it has
3895 not yet accepted (including those for which accepts were previously issued within the
3896 transaction); i.e. the messages remain "acquired". If the Client wishes to release those
3897 messages back to the Server, then appropriate message.release commands must be issued.
3898 </doc>
3899
3900 <exception name="select-required" error-code="illegal-state">
3901 <doc>
3902 A client MUST NOT issue tx.rollback on a session that has not been selected for standard
3903 transactions with tx.select.
3904 </doc>
3905 </exception>
3906
3907 <implement role="server" handle="MUST" />
3908 </command>
3909
3910 </class>
3911
3912 <!-- == Class: dtx =========================================================================== -->
3913
3914 <class name="dtx" code="0x6" label="Demarcates dtx branches">
3915 <doc>
3916 This provides the X-Open XA distributed transaction protocol support. It allows a session
3917 to be selected for use with distributed transactions, the transactional boundaries for work on
3918 that session to be demarcated and allows the transaction manager to coordinate transaction
3919 outcomes.
3920 </doc>
3921
3922 <doc type="grammar">
3923 dtx-demarcation = C:SELECT *demarcation
3924 demarcation = C:START C:END
3925 </doc>
3926
3927 <doc type="grammar">
3928 dtx-coordination = *coordination
3929 coordination = command
3930 / outcome
3931 / recovery
3932 command = C:SET-TIMEOUT
3933 / C:GET-TIMEOUT
3934 outcome = one-phase-commit
3935 / one-phase-rollback
3936 / two-phase-commit
3937 / two-phase-rollback
3938 one-phase-commit = C:COMMIT
3939 one-phase-rollback = C:ROLLBACK
3940 two-phase-commit = C:PREPARE C:COMMIT
3941 two-phase-rollback = C:PREPARE C:ROLLBACK
3942 recovery = C:RECOVER *recovery-outcome
3943 recovery-outcome = one-phase-commit
3944 / one-phase-rollback
3945 / C:FORGET
3946
3947 </doc>
3948
3949 <rule name="transactionality">
3950 <doc>
3951 Enabling XA transaction support on a session requires that the server MUST manage
3952 transactions demarcated by start-end blocks. That is to say that on this XA-enabled session,
3953 work undergone within transactional blocks is performed on behalf a transaction branch
3954 whereas work performed outside of transactional blocks is NOT transactional.
3955 </doc>
3956 </rule>
3957
3958 <role name="server" implement="MAY" />
3959 <role name="client" implement="MAY" />
3960
3961 <!-- XA domains -->
3962
3963 <domain name="xa-status" type="uint16" label="XA return codes">
3964 <enum>
3965 <choice name="xa-ok" value="0">
3966 <doc>
3967 Normal execution completion (no error).
3968 </doc>
3969 </choice>
3970
3971 <choice name="xa-rbrollback" value="1">
3972 <doc>
3973 The rollback was caused for an unspecified reason.
3974 </doc>
3975 </choice>
3976
3977 <choice name="xa-rbtimeout" value="2">
3978 <doc>
3979 A transaction branch took too long.
3980 </doc>
3981 </choice>
3982
3983 <choice name="xa-heurhaz" value="3">
3984 <doc>
3985 The transaction branch may have been heuristically completed.
3986 </doc>
3987 </choice>
3988
3989 <choice name="xa-heurcom" value="4">
3990 <doc>
3991 The transaction branch has been heuristically committed.
3992 </doc>
3993 </choice>
3994
3995 <choice name="xa-heurrb" v