From 8f90ae8dfdf5efbb6c8429897dc95cad621af00b Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Wed, 10 Mar 2010 12:40:13 +0100 Subject: wire formats in docs clarified --- doc/zmq_pgm.txt | 40 +++++++++++++++++++++++++++++++--------- doc/zmq_tcp.txt | 22 +++++++++++++--------- 2 files changed, 44 insertions(+), 18 deletions(-) diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index c92824e..ffbe9bd 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -81,20 +81,42 @@ order specifying either the offset of the first message 'frame' in the datagram or containing the value 0xFFFF if the datagram contains solely an intermediate part of a larger message. -A single PGM datagram as used by 0MQ can thus be defined by the following ABNF -grammar: +The payload of a single PGM datagram as used by 0MQ can thus be defined by the +following ABNF grammar: .... -datagram = message / intermediate -message = (frame-offset *data 1*frame) <1> -intermediate = (escape 1*data) -frame-offset = 2OCTET -escape = %xFF %xFF -data = 1*OCTET +datagram = (offset data) +offset = 2OCTET +data = *OCTET .... -<1> 'frame' as defined in linkzmq:zmq_tcp[7]. +As already explained above, the data from consecutive datagrams are interpreted +as a bytestream that's parsed according to the grammar described in +linkzmq:zmq_tcp[7]. +Each packet thus looks like this: + +---- ++-----------+------------+------------------+----------------------+ +| IP header | PGM header | offset (16 bits) | data | ++-----------+------------+------------------+----------------------+ +---- + +Following example shows how messages are arranged in subsequent packets: + +---- ++---------------+--------+-----------+-----------------------------+ +| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) | ++---------------+--------+-----------+-----------------------------+ + ++---------------+--------+-----------------------------------------+ +| PGM/IPheaders | 0xFFFF | message 2 (part 2) | ++---------------+--------+-----------------------------------------+ + ++---------------+--------+--------------------------+-----------+ +| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 | ++---------------+--------+--------------------------+-----------+ +---- EXAMPLE ------- diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index c6eba21..3f21352 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -54,32 +54,35 @@ A 'peer address' may be specified by either of the following: WIRE FORMAT ----------- 0MQ messages are transmitted over TCP in frames consisting of the message -length followed by the message data. The size of the message data MUST -correspond to the message length. A single 'frame' can be defined by the +length followed by flags byte and the message data. The length MUST correspond +to the length of the remaining part of the frame. + +. A single 'frame' can be defined by the following ABNF grammar: .... - frame = (message-length message-data) - message-length = OCTET / (escape 8OCTET) + frame = (length flags data) + length = OCTET / (escape 8OCTET) + flags = OCTET escape = %xFF - message-data = *OCTET + data = *OCTET .... -For messages of 0 to 254 octets in length, the message length is represented by +For messages of 0 to 253 octets in length, the message length is represented by a single octet: .... 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message size | Message body ... | +| Message size | Flags | Message body ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message body ... +-+-+-+-+-+-+- ... .... -For messages of 255 or more octets in length, the message length is represented +For messages of 254 or more octets in length, the message length is represented by a single octet with the value `255` followed by the message length represented as a 64-bit unsigned integer in network byte order: @@ -91,12 +94,13 @@ represented as a 64-bit unsigned integer in network byte order: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message size ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message size | Message body ... | +| Message size | Flags | Message body ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message body ... +-+-+-+-+-+-+-+ ... .... +The flags field is reserved and MUST be set to 0. EXAMPLES -------- -- cgit v1.2.3