Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/httpheaders_requirements.md

raw
1 httpheaders requirements
2 ================
3
4 ## Overview
5
6 HttpHeaders is a utility module that handles message-headers. HttpHeaders uses Map function calls to store / retrieve http headers.
7
8 ## References
9 [http headers: http://tools.ietf.org/html/rfc2616 , section 4.2, section 4.1](http://tools.ietf.org/html/rfc2616)
10 [structure of header fields: http://tools.ietf.org/html/rfc822#section-3.1](http://tools.ietf.org/html/rfc822#section-3.1)
11
12 ## Exposed API
13 **SRS_HTTP_HEADERS_99_001: [** HttpHeaders shall have the following interface **]**
14 ```c
15 typedef enum HTTP_HEADERS_RESULT_TAG
16 {
17 HTTP_HEADERS_OK,
18 HTTP_HEADERS_INVALID_ARG,
19 HTTP_HEADERS_ALLOC_FAILED,
20 HTTP_HEADERS_INSUFFICIENT_BUFFER,
21 HTTP_HEADERS_ERROR
22 } HTTP_HEADERS_RESULT;
23
24 typedef void* HTTP_HEADERS_HANDLE;
25
26 extern HTTP_HEADERS_HANDLE HTTPHeaders_Alloc(void);
27 extern void HTTPHeaders_Free(HTTP_HEADERS_HANDLE httpHeadersHandle);
28 extern HTTP_HEADERS_RESULT HTTPHeaders_AddHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
29 extern HTTP_HEADERS_RESULT HTTPHeaders_ReplaceHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
30 extern const char* HTTPHeaders_FindHeaderValue(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name);
31 extern HTTP_HEADERS_RESULT HTTPHeaders_GetHeaderCount(HTTP_HEADERS_HANDLE httpHeadersHandle, size_t* headersCount);
32 extern HTTP_HEADERS_RESULT HTTPHeaders_GetHeader(HTTP_HEADERS_HANDLE handle, size_t index, char** destination);
33 extern HTTP_HEADERS_HANDLE HTTPHeaders_Clone(HTTP_HEADERS_HANDLE handle);
34 ```
35
36 An application would use HTTPHeaders_Alloc to create a new set of HTTP headers. After getting the handle, the application would build in several headers by consecutive calls to HTTPHeaders_AddHeaderNameValuePair.
37 When the headers are constructed, the application can retrieve the stored data by calling one of the following functions:
38 HTTPHeaders_FindHeaderValue - when the name of the header is known and it wants to know the value of that header
39 HTTPHeaders_GetHeaderCount - when the application needs to know the count of all the headers
40 HTTPHeaders_GetHeader - when the application needs to know the retrieve name+": "+value based on an index.
41
42 ### HTTPHeaders_Alloc
43 ```c
44 HTTP_HEADERS_HANDLE HTTPHeaders_Alloc(void);
45 ```
46
47 **SRS_HTTP_HEADERS_99_002: [** This API shall produce a HTTP_HANDLE that can later be used in subsequent calls to the module. **]**
48
49 **SRS_HTTP_HEADERS_99_003: [** The function shall return NULL when the function cannot execute properly **]**
50
51 **SRS_HTTP_HEADERS_99_004: [** After a successful init, HTTPHeaders_GetHeaderCount shall report 0 existing headers. **]**
52
53 ### HTTPHeaders_Free
54 ```c
55 HTTPHeaders_Free(HTTP_HEADERS_HANDLE httpHeadersHandle);
56 ```
57
58 **SRS_HTTP_HEADERS_99_005: [** Calling this API shall de-allocate the data structures allocated by previous API calls to the same handle. **]**
59
60 **SRS_HTTP_HEADERS_02_001: [** If httpHeadersHandle is NULL then HTTPHeaders_Free shall perform no action. **]**
61
62 ### HTTPHeaders_AddHeaderNameValuePair
63 ```c
64 HTTP_HEADERS_RESULT HTTPHeaders_AddHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
65 ```
66
67 **SRS_HTTP_HEADERS_99_012: [** Calling this API shall record a header from name and value parameters. **]**
68
69 **SRS_HTTP_HEADERS_99_013: [** The function shall return HTTP_HEADERS_OK when execution is successful. **]**
70
71 **SRS_HTTP_HEADERS_99_014: [** The function shall return when the handle is not valid or when name parameter is NULL or when value parameter is NULL. **]**
72
73 **SRS_HTTP_HEADERS_99_015: [** The function shall return HTTP_HEADERS_ALLOC_FAILED when an internal request to allocate memory fails. **]**
74
75 **SRS_HTTP_HEADERS_99_016: [** The function shall store the name:value pair in such a way that when later retrieved by a call to GetHeader it will return a string that shall strcmp equal to the name+": "+value. **]**
76
77 **SRS_HTTP_HEADERS_99_017: [** If the name already exists in the collection of headers, the function shall concatenate the new value after the existing value, separated by a comma and a space as in: old-value+", "+new-value. **]**
78
79 **SRS_HTTP_HEADERS_99_031: [** If name contains the character ":" then the return value shall be HTTP_HEADERS_INVALID_ARG. **]**
80
81 **SRS_HTTP_HEADERS_99_036: [** If name contains the characters outside character codes 33 to 126 then the return value shall be HTTP_HEADERS_INVALID_ARG **]** (so says http://tools.ietf.org/html/rfc822#section-3.1)
82
83 **SRS_HTTP_HEADERS_02_002: [** The LWS from the beginning of the value shall not be stored. **]**
84
85 ### HTTPHeaders_ReplaceHeaderNameValuePair
86 ```c
87 HTTP_HEADERS_RESULT HTTPHeaders_ReplaceHeaderNameValuePair(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name, const char* value);
88 ```
89
90 **SRS_HTTP_HEADERS_06_001: [** This API will perform exactly as HTTPHeaders_AddHeaderNameValuePair except that if the header name already exists the already existing value will be replaced as opposed to concatenated to. **]**
91
92 ### HTTPHeaders_FindHeaderValue
93 ```c
94 const char* HTTPHeaders_FindHeaderValue(HTTP_HEADERS_HANDLE httpHeadersHandle, const char* name);
95 ```
96
97 **SRS_HTTP_HEADERS_99_018: [** Calling this API shall retrieve the value for a previously stored name. **]**
98
99 **SRS_HTTP_HEADERS_99_022: [** The return value shall be NULL if name parameter is NULL or if httpHeadersHandle is NULL **]**
100
101 **SRS_HTTP_HEADERS_99_020: [** The return value shall be different than NULL when the name matches the name of a previously stored name:value pair. **]**
102
103 **SRS_HTTP_HEADERS_99_021: [** In this case the return value shall point to a string that shall strcmp equal to the original stored string. **]**
104
105 ### HTTPHeaders_GetHeaderCount
106 ```c
107 HTTP_HEADERS_RESULT HTTPHeaders_GetHeaderCount(HTTP_HEADERS_HANDLE httpHeadersHandle, size_t* headersCount);
108 ```
109
110 **SRS_HTTP_HEADERS_99_023: [** Calling this API shall provide the number of stored headers. **]**
111
112 **SRS_HTTP_HEADERS_99_024: [** The function shall return HTTP_HEADERS_INVALID_ARG when an invalid handle is passed. **]**
113
114 **SRS_HTTP_HEADERS_99_025: [** The function shall return HTTP_HEADERS_INVALID_ARG when headersCount is NULL. **]**
115
116 **SRS_HTTP_HEADERS_99_026: [** The function shall write in *headersCount the number of currently stored headers and shall return HTTP_HEADERS_OK **]**
117
118 **SRS_HTTP_HEADERS_99_037: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs. **]**
119
120 ### HTTPHeaders_GetHeader
121 ```c
122 HTTP_HEADERS_RESULT HTTPHeaders_GetHeader(HTTP_HEADERS_HANDLE handle, size_t index, char** destination);
123 ```
124
125 **SRS_HTTP_HEADERS_99_027: [** Calling this API shall produce the string value+": "+pair) for the index header in the *destination parameter. **]**
126
127 **SRS_HTTP_HEADERS_99_028: [** The function shall return HTTP_HEADERS_INVALID_ARG if the handle is invalid. **]**
128
129 **SRS_HTTP_HEADERS_99_029: [** The function shall return HTTP_HEADERS_INVALID_ARG if index is not valid (for example, out of range) for the currently stored headers. **]**
130
131 **SRS_HTTP_HEADERS_99_032: [** The function shall return HTTP_HEADERS_INVALID_ARG if the destination is NULL **]**
132
133 **SRS_HTTP_HEADERS_99_034: [** The function shall return HTTP_HEADERS_ERROR when an internal error occurs **]**
134
135 **SRS_HTTP_HEADERS_99_035: [** The function shall return HTTP_HEADERS_OK when the function executed without error. **]**
136
137 ### HTTPHeaders_Clone
138 ```c
139 extern HTTP_HEADERS_HANDLE HTTPHeaders_Clone(HTTP_HEADERS_HANDLE handle);
140 ```
141 HTTPHeaders_Clone produces a clone of the handle parameter.
142
143 **SRS_HTTP_HEADERS_02_003: [** If handle is NULL then HTTPHeaders_Clone shall return NULL. **]**
144
145 **SRS_HTTP_HEADERS_02_004: [** Otherwise HTTPHeaders_Clone shall clone the content of handle to a new handle. **]**
146
147 **SRS_HTTP_HEADERS_02_005: [** If cloning fails for any reason, then HTTPHeaders_Clone shall return NULL. **]**