| 1 |
# amqp_frame_codec requirements |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
`amqp_frame_codec` is module that encodes/decodes AMQP frames per the AMQP ISO. |
| 6 |
|
| 7 |
## Exposed API |
| 8 |
|
| 9 |
```C |
| 10 |
#define AMQP_OPEN (uint64_t)0x10 |
| 11 |
#define AMQP_BEGIN (uint64_t)0x11 |
| 12 |
#define AMQP_ATTACH (uint64_t)0x12 |
| 13 |
#define AMQP_FLOW (uint64_t)0x13 |
| 14 |
#define AMQP_TRANSFER (uint64_t)0x14 |
| 15 |
#define AMQP_DISPOSITION (uint64_t)0x15 |
| 16 |
#define AMQP_DETACH (uint64_t)0x16 |
| 17 |
#define AMQP_END (uint64_t)0x17 |
| 18 |
#define AMQP_CLOSE (uint64_t)0x18 |
| 19 |
|
| 20 |
typedef struct AMQP_FRAME_CODEC_INSTANCE_TAG* AMQP_FRAME_CODEC_HANDLE; |
| 21 |
typedef void(*AMQP_EMPTY_FRAME_RECEIVED_CALLBACK)(void* context, uint16_t channel); |
| 22 |
typedef void(*AMQP_FRAME_RECEIVED_CALLBACK)(void* context, uint16_t channel, AMQP_VALUE performative, const unsigned char* payload_bytes, uint32_t frame_payload_size); |
| 23 |
typedef void(*AMQP_FRAME_CODEC_ERROR_CALLBACK)(void* context); |
| 24 |
|
| 25 |
MOCKABLE_FUNCTION(, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec_create, FRAME_CODEC_HANDLE, frame_codec, AMQP_FRAME_RECEIVED_CALLBACK, frame_received_callback, AMQP_EMPTY_FRAME_RECEIVED_CALLBACK, empty_frame_received_callback, AMQP_FRAME_CODEC_ERROR_CALLBACK, amqp_frame_codec_error_callback, void*, callback_context); |
| 26 |
MOCKABLE_FUNCTION(, void, amqp_frame_codec_destroy, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec); |
| 27 |
MOCKABLE_FUNCTION(, int, amqp_frame_codec_encode_frame, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec, uint16_t, channel, AMQP_VALUE, performative, const PAYLOAD*, payloads, size_t, payload_count, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 28 |
MOCKABLE_FUNCTION(, int, amqp_frame_codec_encode_empty_frame, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec, uint16_t, channel, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 29 |
``` |
| 30 |
|
| 31 |
### amqp_frame_codec_create |
| 32 |
```C |
| 33 |
MOCKABLE_FUNCTION(, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec_create, FRAME_CODEC_HANDLE, frame_codec, AMQP_FRAME_RECEIVED_CALLBACK, frame_received_callback, AMQP_EMPTY_FRAME_RECEIVED_CALLBACK, empty_frame_received_callback, AMQP_FRAME_CODEC_ERROR_CALLBACK, amqp_frame_codec_error_callback, void*, callback_context); |
| 34 |
``` |
| 35 |
|
| 36 |
**SRS_AMQP_FRAME_CODEC_01_011: [**amqp_frame_codec_create shall create an instance of an amqp_frame_codec and return a non-NULL handle to it.**]** |
| 37 |
**SRS_AMQP_FRAME_CODEC_01_012: [**If any of the arguments frame_codec, frame_received_callback, amqp_frame_codec_error_callback or empty_frame_received_callback is NULL, amqp_frame_codec_create shall return NULL.**]** |
| 38 |
**SRS_AMQP_FRAME_CODEC_01_013: [**amqp_frame_codec_create shall subscribe for AMQP frames with the given frame_codec.**]** |
| 39 |
**SRS_AMQP_FRAME_CODEC_01_014: [**If subscribing for AMQP frames fails, amqp_frame_codec_create shall fail and return NULL.**]** |
| 40 |
**SRS_AMQP_FRAME_CODEC_01_018: [**amqp_frame_codec_create shall create a decoder to be used for decoding AMQP values.**]** |
| 41 |
**SRS_AMQP_FRAME_CODEC_01_019: [**If creating the decoder fails, amqp_frame_codec_create shall fail and return NULL.**]** |
| 42 |
**SRS_AMQP_FRAME_CODEC_01_020: [**If allocating memory for the new amqp_frame_codec fails, then amqp_frame_codec_create shall fail and return NULL.**]** |
| 43 |
|
| 44 |
### amqp_frame_codec_destroy |
| 45 |
|
| 46 |
```C |
| 47 |
MOCKABLE_FUNCTION(, void, amqp_frame_codec_destroy, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec); |
| 48 |
``` |
| 49 |
|
| 50 |
**SRS_AMQP_FRAME_CODEC_01_015: [**amqp_frame_codec_destroy shall free all resources associated with the amqp_frame_codec instance.**]** |
| 51 |
**SRS_AMQP_FRAME_CODEC_01_016: [**If amqp_frame_codec is NULL, amqp_frame_codec_destroy shall do nothing.**]** |
| 52 |
**SRS_AMQP_FRAME_CODEC_01_017: [**amqp_frame_codec_destroy shall unsubscribe from receiving AMQP frames from the frame_codec that was passed to amqp_frame_codec_create.**]** |
| 53 |
**SRS_AMQP_FRAME_CODEC_01_021: [**The decoder created in amqp_frame_codec_create shall be destroyed by amqp_frame_codec_destroy.**]** |
| 54 |
|
| 55 |
### amqp_frame_codec_encode_frame |
| 56 |
|
| 57 |
```C |
| 58 |
MOCKABLE_FUNCTION(, int, amqp_frame_codec_encode_frame, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec, uint16_t, channel, AMQP_VALUE, performative, const PAYLOAD*, payloads, size_t, payload_count, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 59 |
``` |
| 60 |
|
| 61 |
**SRS_AMQP_FRAME_CODEC_01_022: [**amqp_frame_codec_encode_frame shall encode the frame header and AMQP performative in an AMQP frame and on success it shall return 0.**]** |
| 62 |
**SRS_AMQP_FRAME_CODEC_01_024: [**If frame_codec, performative or on_bytes_encoded is NULL, amqp_frame_codec_encode_frame shall fail and return a non-zero value.**]** |
| 63 |
**SRS_AMQP_FRAME_CODEC_01_025: [**amqp_frame_codec_encode_frame shall encode the frame header by using frame_codec_encode_frame.**]** |
| 64 |
**SRS_AMQP_FRAME_CODEC_01_026: [**The payload frame size shall be computed based on the encoded size of the performative and its fields plus the sum of the payload sizes passed via the payloads argument.**]** |
| 65 |
**SRS_AMQP_FRAME_CODEC_01_027: [**The encoded size of the performative and its fields shall be obtained by calling amqpvalue_get_encoded_size.**]** |
| 66 |
**SRS_AMQP_FRAME_CODEC_01_029: [**If any error occurs during encoding, amqp_frame_codec_encode_frame shall fail and return a non-zero value.**]** |
| 67 |
**SRS_AMQP_FRAME_CODEC_01_030: [**Encoding of the AMQP performative and its fields shall be done by calling amqpvalue_encode.**]** |
| 68 |
**SRS_AMQP_FRAME_CODEC_01_028: [**The encode result for the performative shall be placed in a PAYLOAD structure.**]** |
| 69 |
**SRS_AMQP_FRAME_CODEC_01_070: [**The payloads argument for frame_codec_encode_frame shall be made of the payload for the encoded performative and the payloads passed to amqp_frame_codec_encode_frame.**]** |
| 70 |
|
| 71 |
### amqp_frame_codec_encode_empty_frame |
| 72 |
|
| 73 |
```C |
| 74 |
MOCKABLE_FUNCTION(, int, amqp_frame_codec_encode_empty_frame, AMQP_FRAME_CODEC_HANDLE, amqp_frame_codec, uint16_t, channel, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 75 |
``` |
| 76 |
|
| 77 |
**SRS_AMQP_FRAME_CODEC_01_042: [**amqp_frame_codec_encode_empty_frame shall encode a frame with no payload.**]** |
| 78 |
**SRS_AMQP_FRAME_CODEC_01_043: [**On success, amqp_frame_codec_encode_empty_frame shall return 0.**]** |
| 79 |
**SRS_AMQP_FRAME_CODEC_01_044: [**amqp_frame_codec_encode_empty_frame shall use frame_codec_encode_frame to encode the frame.**]** |
| 80 |
**SRS_AMQP_FRAME_CODEC_01_045: [**If amqp_frame_codec is NULL, amqp_frame_codec_encode_empty_frame shall fail and return a non-zero value.**]** |
| 81 |
**SRS_AMQP_FRAME_CODEC_01_046: [**If encoding fails in any way, amqp_frame_codec_encode_empty_frame shall fail and return a non-zero value.**]** |
| 82 |
|
| 83 |
### Receive frames |
| 84 |
|
| 85 |
**SRS_AMQP_FRAME_CODEC_01_048: [**When a frame header is received from frame_codec and the frame payload size is 0, empty_frame_received_callback shall be invoked, while passing the channel number as argument.**]** |
| 86 |
**SRS_AMQP_FRAME_CODEC_01_049: [**If not enough type specific bytes are received to decode the channel number, the decoding shall stop with an error.**]** |
| 87 |
**SRS_AMQP_FRAME_CODEC_01_050: [**All subsequent decoding shall fail and no AMQP frames shall be indicated from that point on to the consumers of amqp_frame_codec.**]** |
| 88 |
**SRS_AMQP_FRAME_CODEC_01_051: [**If the frame payload is greater than 0, amqp_frame_codec shall decode the performative as a described AMQP type.**]** |
| 89 |
**SRS_AMQP_FRAME_CODEC_01_052: [**Decoding the performative shall be done by feeding the bytes to the decoder create in amqp_frame_codec_create.**]** |
| 90 |
**SRS_AMQP_FRAME_CODEC_01_067: [**When the performative is decoded, the rest of the frame_bytes shall not be given to the AMQP decoder, but they shall be buffered so that later they are given to the frame_received callback.**]** |
| 91 |
**SRS_AMQP_FRAME_CODEC_01_054: [**Once the performative is decoded and all frame payload bytes are received, the callback frame_received_callback shall be called.**]** |
| 92 |
**SRS_AMQP_FRAME_CODEC_01_055: [**The decoded channel and performative shall be passed to frame_received_callback.**]** |
| 93 |
**SRS_AMQP_FRAME_CODEC_01_056: [**The AMQP frame payload size passed to frame_received_callback shall be computed from the frame payload size received from frame_codec and substracting the performative size.**]** |
| 94 |
**SRS_AMQP_FRAME_CODEC_01_068: [**A pointer to all the payload bytes shall also be passed to frame_received_callback.**]** |
| 95 |
**SRS_AMQP_FRAME_CODEC_01_060: [**If any error occurs while decoding a frame, the decoder shall switch to an error state where decoding shall not be possible anymore.**]** |
| 96 |
**SRS_AMQP_FRAME_CODEC_01_069: [**If any error occurs while decoding a frame, the decoder shall indicate the error by calling the amqp_frame_codec_error_callback and passing to it the callback context argument that was given in amqp_frame_codec_create.**]** |
| 97 |
|
| 98 |
### ISO section (receive) |
| 99 |
|
| 100 |
2.3.2 AMQP Frames |
| 101 |
|
| 102 |
**SRS_AMQP_FRAME_CODEC_01_001: [**Bytes 6 and 7 of an AMQP frame contain the channel number **]** (see section 2.1). |
| 103 |
**SRS_AMQP_FRAME_CODEC_01_002: [**The frame body is defined as a performative followed by an opaque payload.**]** |
| 104 |
**SRS_AMQP_FRAME_CODEC_01_003: [**The performative MUST be one of those defined in section 2.7 and is encoded as a described type in the AMQP type system.**]** |
| 105 |
**SRS_AMQP_FRAME_CODEC_01_004: [**The remaining bytes in the frame body form the payload for that frame.**]** The presence and format of the payload is defined by the semantics of the given performative. |
| 106 |
|
| 107 |
... |
| 108 |
|
| 109 |
Figure 2.16: AMQP Frame Layout |
| 110 |
|
| 111 |
**SRS_AMQP_FRAME_CODEC_01_007: [**An AMQP frame with no body MAY be used to generate artificial traffic as needed to satisfy any negotiated idle timeout interval **]** (see subsection 2.4.5). |
| 112 |
|
| 113 |
### ISO section (send) |
| 114 |
|
| 115 |
2.3.2 AMQP Frames |
| 116 |
|
| 117 |
**SRS_AMQP_FRAME_CODEC_01_005: [**Bytes 6 and 7 of an AMQP frame contain the channel number **]** (see section 2.1). |
| 118 |
**SRS_AMQP_FRAME_CODEC_01_006: [**The frame body is defined as a performative followed by an opaque payload.**]** |
| 119 |
**SRS_AMQP_FRAME_CODEC_01_008: [**The performative MUST be one of those defined in section 2.7 and is encoded as a described type in the AMQP type system.**]** |
| 120 |
**SRS_AMQP_FRAME_CODEC_01_009: [**The remaining bytes in the frame body form the payload for that frame.**]** The presence and format of the payload is defined by the semantics of the given performative. |
| 121 |
|
| 122 |
... |
| 123 |
|
| 124 |
Figure 2.16: AMQP Frame Layout |
| 125 |
|
| 126 |
**SRS_AMQP_FRAME_CODEC_01_010: [**An AMQP frame with no body MAY be used to generate artificial traffic as needed to satisfy any negotiated idle timeout interval **]** (see subsection 2.4.5). |