Debian Codegraph @

src/vendor/azure-uamqp-c/devdoc/frame_codec_requirements.md

raw
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.