| 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. **]** |