| 1 |
# frame_codec requirements |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
`frame_codec` is module that encodes/decodes frames (regardless of their type). |
| 6 |
|
| 7 |
## Exposed API |
| 8 |
|
| 9 |
```C |
| 10 |
typedef struct PAYLOAD_TAG |
| 11 |
{ |
| 12 |
const unsigned char* bytes; |
| 13 |
size_t length; |
| 14 |
} PAYLOAD; |
| 15 |
|
| 16 |
#define FRAME_TYPE_AMQP (uint8_t)0x00 |
| 17 |
|
| 18 |
#define FRAME_TYPE_SASL (uint8_t)0x01 |
| 19 |
|
| 20 |
typedef struct FRAME_CODEC_INSTANCE_TAG* FRAME_CODEC_HANDLE; |
| 21 |
typedef void(*ON_FRAME_RECEIVED)(void* context, const unsigned char* type_specific, uint32_t type_specific_size, const unsigned char* frame_body, uint32_t frame_body_size); |
| 22 |
typedef void(*ON_FRAME_CODEC_ERROR)(void* context); |
| 23 |
typedef void(*ON_BYTES_ENCODED)(void* context, const unsigned char* bytes, size_t length, bool encode_complete); |
| 24 |
|
| 25 |
MOCKABLE_FUNCTION(, FRAME_CODEC_HANDLE, frame_codec_create, ON_FRAME_CODEC_ERROR, on_frame_codec_error, void*, callback_context); |
| 26 |
MOCKABLE_FUNCTION(, void, frame_codec_destroy, FRAME_CODEC_HANDLE, frame_codec); |
| 27 |
MOCKABLE_FUNCTION(, int, frame_codec_set_max_frame_size, FRAME_CODEC_HANDLE, frame_codec, uint32_t, max_frame_size); |
| 28 |
MOCKABLE_FUNCTION(, int, frame_codec_subscribe, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type, ON_FRAME_RECEIVED, on_frame_received, void*, callback_context); |
| 29 |
MOCKABLE_FUNCTION(, int, frame_codec_unsubscribe, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type); |
| 30 |
MOCKABLE_FUNCTION(, int, frame_codec_receive_bytes, FRAME_CODEC_HANDLE, frame_codec, const unsigned char*, buffer, size_t, size); |
| 31 |
MOCKABLE_FUNCTION(, int, frame_codec_encode_frame, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type, const PAYLOAD*, payloads, size_t, payload_count, const unsigned char*, type_specific_bytes, uint32_t, type_specific_size, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 32 |
``` |
| 33 |
|
| 34 |
### frame_codec_create |
| 35 |
|
| 36 |
```C |
| 37 |
MOCKABLE_FUNCTION(, FRAME_CODEC_HANDLE, frame_codec_create, ON_FRAME_CODEC_ERROR, on_frame_codec_error, void*, callback_context); |
| 38 |
``` |
| 39 |
|
| 40 |
**SRS_FRAME_CODEC_01_021: [**frame_codec_create shall create a new instance of frame_codec and return a non-NULL handle to it on success.**]** |
| 41 |
**SRS_FRAME_CODEC_01_020: [**If the on_frame_codec_error argument is NULL, frame_codec_create shall return NULL.**]** |
| 42 |
**SRS_FRAME_CODEC_01_022: [**If allocating memory for the frame_codec instance fails, frame_codec_create shall return NULL.**]** |
| 43 |
**SRS_FRAME_CODEC_01_082: [**The initial max_frame_size_shall be 512.**]** |
| 44 |
**SRS_FRAME_CODEC_01_104: [**The callback_context shall be allowed to be NULL.**]** |
| 45 |
|
| 46 |
### frame_codec_destroy |
| 47 |
|
| 48 |
```C |
| 49 |
MOCKABLE_FUNCTION(, void, frame_codec_destroy, FRAME_CODEC_HANDLE, frame_codec); |
| 50 |
``` |
| 51 |
|
| 52 |
**SRS_FRAME_CODEC_01_023: [**frame_codec_destroy shall free all resources associated with a frame_codec instance.**]** |
| 53 |
**SRS_FRAME_CODEC_01_024: [**If frame_codec is NULL, frame_codec_destroy shall do nothing.**]** |
| 54 |
|
| 55 |
### frame_codec_set_max_frame_size |
| 56 |
|
| 57 |
```C |
| 58 |
MOCKABLE_FUNCTION(, int, frame_codec_set_max_frame_size, FRAME_CODEC_HANDLE, frame_codec, uint32_t, max_frame_size); |
| 59 |
``` |
| 60 |
|
| 61 |
**SRS_FRAME_CODEC_01_075: [**frame_codec_set_max_frame_size shall set the maximum frame size for a frame_codec.**]** |
| 62 |
**SRS_FRAME_CODEC_01_076: [**On success, frame_codec_set_max_frame_size shall return 0.**]** |
| 63 |
**SRS_FRAME_CODEC_01_077: [**If frame_codec is NULL, frame_codec_set_max_frame_size shall return a non-zero value.**]** |
| 64 |
**SRS_FRAME_CODEC_01_078: [**If max_frame_size is invalid according to the AMQP standard, frame_codec_set_max_frame_size shall return a non-zero value.**]** |
| 65 |
**SRS_FRAME_CODEC_01_079: [**The new frame size shall take effect immediately, even for a frame that is being decoded at the time of the call.**]** |
| 66 |
**SRS_FRAME_CODEC_01_081: [**If a frame being decoded already has a size bigger than the max_frame_size argument then frame_codec_set_max_frame_size shall return a non-zero value and the previous frame size shall be kept.**]** |
| 67 |
**SRS_FRAME_CODEC_01_097: [**Setting a frame size on a frame_codec that had a decode error shall fail.**]** |
| 68 |
|
| 69 |
### frame_codec_subscribe |
| 70 |
|
| 71 |
```C |
| 72 |
MOCKABLE_FUNCTION(, int, frame_codec_subscribe, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type, ON_FRAME_RECEIVED, on_frame_received, void*, callback_context); |
| 73 |
``` |
| 74 |
|
| 75 |
**SRS_FRAME_CODEC_01_033: [**frame_codec_subscribe subscribes for a certain type of frame received by the frame_codec instance identified by frame_codec.**]** |
| 76 |
**SRS_FRAME_CODEC_01_087: [**On success, frame_codec_subscribe shall return zero.**]** |
| 77 |
**SRS_FRAME_CODEC_01_034: [**If any of the frame_codec or on_frame_received arguments is NULL, frame_codec_subscribe shall return a non-zero value.**]** |
| 78 |
**SRS_FRAME_CODEC_01_035: [**After successfully registering a callback for a certain frame type, when subsequently that frame type is received the callbacks shall be invoked, passing to it the received frame and the callback_context value.**]** |
| 79 |
**SRS_FRAME_CODEC_01_036: [**Only one callback pair shall be allowed to be registered for a given frame type.**]** |
| 80 |
**SRS_FRAME_CODEC_01_037: [**If any failure occurs while performing the subscribe operation, frame_codec_subscribe shall return a non-zero value.**]** |
| 81 |
|
| 82 |
### frame_codec_unsubscribe |
| 83 |
|
| 84 |
```C |
| 85 |
MOCKABLE_FUNCTION(, int, frame_codec_unsubscribe, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type); |
| 86 |
``` |
| 87 |
|
| 88 |
**SRS_FRAME_CODEC_01_038: [**frame_codec_unsubscribe removes a previous subscription for frames of type type and on success it shall return 0.**]** |
| 89 |
**SRS_FRAME_CODEC_01_039: [**If frame_codec is NULL, frame_codec_unsubscribe shall return a non-zero value.**]** |
| 90 |
**SRS_FRAME_CODEC_01_040: [**If no subscription for the type frame type exists, frame_codec_unsubscribe shall return a non-zero value.**]** |
| 91 |
**SRS_FRAME_CODEC_01_041: [**If any failure occurs while performing the unsubscribe operation, frame_codec_unsubscribe shall return a non-zero value.**]** |
| 92 |
|
| 93 |
### frame_codec_receive_bytes |
| 94 |
|
| 95 |
```C |
| 96 |
MOCKABLE_FUNCTION(, int, frame_codec_receive_bytes, FRAME_CODEC_HANDLE, frame_codec, const unsigned char*, buffer, size_t, size); |
| 97 |
``` |
| 98 |
|
| 99 |
**SRS_FRAME_CODEC_01_025: [**frame_codec_receive_bytes decodes a sequence of bytes into frames and on success it shall return zero.**]** |
| 100 |
**SRS_FRAME_CODEC_01_026: [**If frame_codec or buffer are NULL, frame_codec_receive_bytes shall return a non-zero value.**]** |
| 101 |
**SRS_FRAME_CODEC_01_027: [**If size is zero, frame_codec_receive_bytes shall return a non-zero value.**]** |
| 102 |
**SRS_FRAME_CODEC_01_028: [**The sequence of bytes shall be decoded according to the AMQP ISO.**]** |
| 103 |
**SRS_FRAME_CODEC_01_029: [**The sequence of bytes does not have to be a complete frame, frame_codec shall be responsible for maintaining decoding state between frame_codec_receive_bytes calls.**]** |
| 104 |
**SRS_FRAME_CODEC_01_030: [**If a decoding error occurs, frame_codec_receive_bytes shall return a non-zero value.**]** |
| 105 |
**SRS_FRAME_CODEC_01_074: [**If a decoding error is detected, any subsequent calls on frame_codec_receive_bytes shall fail.**]** |
| 106 |
**SRS_FRAME_CODEC_01_031: [**When a complete frame is successfully decoded it shall be indicated to the upper layer by invoking the on_frame_received passed to frame_codec_subscribe.**]** |
| 107 |
**SRS_FRAME_CODEC_01_032: [**Besides passing the frame information, the callback_context value passed to frame_codec_subscribe shall be passed to the on_frame_received function.**]** |
| 108 |
**SRS_FRAME_CODEC_01_099: [**A pointer to the frame_body bytes shall also be passed to the on_frame_received.**]** |
| 109 |
**SRS_FRAME_CODEC_01_102: [**frame_codec_receive_bytes shall allocate memory to hold the frame_body bytes.**]** |
| 110 |
**SRS_FRAME_CODEC_01_101: [**If the memory for the frame_body bytes cannot be allocated, frame_codec_receive_bytes shall fail and return a non-zero value.**]** |
| 111 |
**SRS_FRAME_CODEC_01_100: [**If the frame body size is 0, the frame_body pointer passed to on_frame_received shall be NULL.**]** |
| 112 |
**SRS_FRAME_CODEC_01_096: [**If a frame bigger than the current max frame size is received, frame_codec_receive_bytes shall fail and return a non-zero value.**]** |
| 113 |
**SRS_FRAME_CODEC_01_103: [**Upon any decode error, if an error callback has been passed to frame_codec_create, then the error callback shall be called with the context argument being the frame_codec_error_callback_context argument passed to frame_codec_create.**]** |
| 114 |
|
| 115 |
### frame_codec_encode_frame |
| 116 |
|
| 117 |
```C |
| 118 |
MOCKABLE_FUNCTION(, int, frame_codec_encode_frame, FRAME_CODEC_HANDLE, frame_codec, uint8_t, type, const PAYLOAD*, payloads, size_t, payload_count, const unsigned char*, type_specific_bytes, uint32_t, type_specific_size, ON_BYTES_ENCODED, on_bytes_encoded, void*, callback_context); |
| 119 |
``` |
| 120 |
|
| 121 |
**SRS_FRAME_CODEC_01_042: [**frame_codec_encode_frame encodes the header, type specific bytes and frame payload of a frame that has frame_payload_size bytes.**]** |
| 122 |
**SRS_FRAME_CODEC_01_043: [**On success it shall return 0.**]** |
| 123 |
**SRS_FRAME_CODEC_01_110: [** If the `bytes` member of a payload entry is NULL, `frame_codec_encode_frame` shall fail and return a non-zero value. **]** |
| 124 |
**SRS_FRAME_CODEC_01_111: [** If the `length` member of a payload entry is 0, `frame_codec_encode_frame` shall fail and return a non-zero value. **]** |
| 125 |
**SRS_FRAME_CODEC_01_108: [** Memory shall be allocated to hold the entire frame. **]** |
| 126 |
**SRS_FRAME_CODEC_01_109: [** If allocating memory fails, `frame_codec_encode_frame` shall fail and return a non-zero value. **]** |
| 127 |
**SRS_FRAME_CODEC_01_044: [**If any of arguments `frame_codec` or `on_bytes_encoded` is NULL, `frame_codec_encode_frame` shall return a non-zero value.**]** |
| 128 |
**SRS_FRAME_CODEC_01_107: [**If the argument `payloads` is NULL and `payload_count` is non-zero, `frame_codec_encode_frame` shall return a non-zero value.**]** |
| 129 |
**SRS_FRAME_CODEC_01_090: [**If the type_specific_size - 2 does not divide by 4, frame_codec_encode_frame shall pad the type_specific bytes with zeroes so that type specific data is according to the AMQP ISO.**]** |
| 130 |
**SRS_FRAME_CODEC_01_092: [**If type_specific_size is too big to allow encoding the frame according to the AMQP ISO then frame_codec_encode_frame shall return a non-zero value.**]** |
| 131 |
**SRS_FRAME_CODEC_01_091: [**If the argument type_specific_size is greater than 0 and type_specific_bytes is NULL, frame_codec_encode_frame shall return a non-zero value.**]** |
| 132 |
**SRS_FRAME_CODEC_01_105: [**The frame_payload_size shall be computed by summing up the lengths of the payload segments identified by the payloads argument.**]** |
| 133 |
**SRS_FRAME_CODEC_01_106: [**All payloads shall be encoded in order as part of the frame.**]** |
| 134 |
**SRS_FRAME_CODEC_01_088: [**Encoded bytes shall be passed to the `on_bytes_encoded` callback in a single call, while setting the `encode complete` argument to true.**]** |
| 135 |
**SRS_FRAME_CODEC_01_095: [**If the frame_size needed for the frame is bigger than the maximum frame size, frame_codec_encode_frame shall fail and return a non-zero value.**]** |
| 136 |
|
| 137 |
## ISO section (receive) |
| 138 |
|
| 139 |
2.3 Framing |
| 140 |
|
| 141 |
**SRS_FRAME_CODEC_01_001: [**Frames are divided into three distinct areas: a fixed width frame header, a variable width extended header, and a variable width frame body.**]** |
| 142 |
|
| 143 |
... |
| 144 |
|
| 145 |
Figure 2.14: Frame Layout |
| 146 |
|
| 147 |
**SRS_FRAME_CODEC_01_002: [**frame header The frame header is a fixed size (8 byte) structure that precedes each frame.**]** |
| 148 |
**SRS_FRAME_CODEC_01_003: [**The frame header includes mandatory information necessary to parse the rest of the frame including size and type information.**]** |
| 149 |
**SRS_FRAME_CODEC_01_004: [**extended header The extended header is a variable width area preceding the frame body.**]** |
| 150 |
**SRS_FRAME_CODEC_01_005: [**This is an extension point defined for future expansion.**]** |
| 151 |
**SRS_FRAME_CODEC_01_006: [**The treatment of this area depends on the frame type.**]** |
| 152 |
**SRS_FRAME_CODEC_01_007: [**frame body The frame body is a variable width sequence of bytes the format of which depends on the frame type.**]** |
| 153 |
|
| 154 |
2.3.1 Frame Layout |
| 155 |
|
| 156 |
The diagram below shows the details of the general frame layout for all frame types. |
| 157 |
|
| 158 |
... |
| 159 |
|
| 160 |
Figure 2.15: General Frame Layout |
| 161 |
|
| 162 |
**SRS_FRAME_CODEC_01_008: [**SIZE Bytes 0-3 of the frame header contain the frame size.**]** |
| 163 |
**SRS_FRAME_CODEC_01_009: [**This is an unsigned 32-bit integer that MUST contain the total frame size of the frame header, extended header, and frame body.**]** |
| 164 |
**SRS_FRAME_CODEC_01_010: [**The frame is malformed if the size is less than the size of the frame header (8 bytes).**]** |
| 165 |
**SRS_FRAME_CODEC_01_011: [**DOFF Byte 4 of the frame header is the data offset.**]** |
| 166 |
**SRS_FRAME_CODEC_01_012: [**This gives the position of the body within the frame.**]** |
| 167 |
**SRS_FRAME_CODEC_01_013: [**The value of the data offset is an unsigned, 8-bit integer specifying a count of 4-byte words.**]** |
| 168 |
**SRS_FRAME_CODEC_01_014: [**Due to the mandatory 8-byte frame header, the frame is malformed if the value is less than 2.**]** |
| 169 |
**SRS_FRAME_CODEC_01_015: [**TYPE Byte 5 of the frame header is a type code.**]** |
| 170 |
**SRS_FRAME_CODEC_01_016: [**The type code indicates the format and purpose of the frame.**]** |
| 171 |
**SRS_FRAME_CODEC_01_017: [**The subsequent bytes in the frame header MAY be interpreted differently depending on the type of the frame.**]** |
| 172 |
**SRS_FRAME_CODEC_01_018: [**A type code of 0x00 indicates that the frame is an AMQP frame.**]** |
| 173 |
**SRS_FRAME_CODEC_01_019: [**A type code of 0x01 indicates that the frame is a SASL frame**]** , see Part 5: section 5.3. |
| 174 |
|
| 175 |
## ISO section (send) |
| 176 |
|
| 177 |
2.3 Framing |
| 178 |
|
| 179 |
**SRS_FRAME_CODEC_01_055: [**Frames are divided into three distinct areas: a fixed width frame header, a variable width extended header, and a variable width frame body.**]** |
| 180 |
|
| 181 |
... |
| 182 |
|
| 183 |
Figure 2.14: Frame Layout |
| 184 |
|
| 185 |
**SRS_FRAME_CODEC_01_056: [**frame header The frame header is a fixed size (8 byte) structure that precedes each frame.**]** |
| 186 |
**SRS_FRAME_CODEC_01_057: [**The frame header includes mandatory information necessary to parse the rest of the frame including size and type information.**]** |
| 187 |
**SRS_FRAME_CODEC_01_058: [**extended header The extended header is a variable width area preceding the frame body.**]** |
| 188 |
**SRS_FRAME_CODEC_01_059: [**This is an extension point defined for future expansion.**]** |
| 189 |
**SRS_FRAME_CODEC_01_060: [**The treatment of this area depends on the frame type.**]** |
| 190 |
**SRS_FRAME_CODEC_01_061: [**frame body The frame body is a variable width sequence of bytes the format of which depends on the frame type.**]** |
| 191 |
|
| 192 |
2.3.1 Frame Layout |
| 193 |
|
| 194 |
The diagram below shows the details of the general frame layout for all frame types. |
| 195 |
|
| 196 |
... |
| 197 |
|
| 198 |
Figure 2.15: General Frame Layout |
| 199 |
|
| 200 |
**SRS_FRAME_CODEC_01_062: [**SIZE Bytes 0-3 of the frame header contain the frame size.**]** |
| 201 |
**SRS_FRAME_CODEC_01_063: [**This is an unsigned 32-bit integer that MUST contain the total frame size of the frame header, extended header, and frame body.**]** |
| 202 |
**SRS_FRAME_CODEC_01_064: [**The frame is malformed if the size is less than the size of the frame header (8 bytes).**]** |
| 203 |
**SRS_FRAME_CODEC_01_065: [**DOFF Byte 4 of the frame header is the data offset.**]** |
| 204 |
**SRS_FRAME_CODEC_01_066: [**This gives the position of the body within the frame.**]** |
| 205 |
**SRS_FRAME_CODEC_01_067: [**The value of the data offset is an unsigned, 8-bit integer specifying a count of 4-byte words.**]** |
| 206 |
**SRS_FRAME_CODEC_01_068: [**Due to the mandatory 8-byte frame header, the frame is malformed if the value is less than 2.**]** |
| 207 |
**SRS_FRAME_CODEC_01_069: [**TYPE Byte 5 of the frame header is a type code.**]** |
| 208 |
**SRS_FRAME_CODEC_01_070: [**The type code indicates the format and purpose of the frame.**]** |
| 209 |
**SRS_FRAME_CODEC_01_071: [**The subsequent bytes in the frame header MAY be interpreted differently depending on the type of the frame.**]** |
| 210 |
**SRS_FRAME_CODEC_01_072: [**A type code of 0x00 indicates that the frame is an AMQP frame.**]** |
| 211 |
**SRS_FRAME_CODEC_01_073: [**A type code of 0x01 indicates that the frame is a SASL frame**]** , see Part 5: section 5.3. |