HTTPClient_AddRangeHeader

Add the byte range request header to the request headers store in HTTPRequestHeaders_t.pBuffer.

HTTPStatus_t HTTPClient_AddRangeHeader( HTTPRequestHeaders_t * pRequestHeaders,
                                        int32_t rangeStartOrlastNbytes,
                                        int32_t rangeEnd );

For example, if requesting for the first 1kB of a file the following would be written: Range: bytes=0-1023\r\n\r\n.

The trailing \r\n that denotes the end of the header lines is overwritten, if it already exists in the buffer.

There are 3 different forms of range specification, determined by the combination of rangeStartOrLastNBytes and rangeEnd parameter values:

1. Request containing both parameters for the byte range [rangeStart, rangeEnd] where rangeStartOrLastNBytes <= rangeEnd. Example request header line: Range: bytes=0-1023\r\n for requesting bytes in the range [0, 1023].
   Example

   HTTPStatus_t httpLibraryStatus = HTTPSuccess;
   // Assume that requestHeaders has already been initialized with
   // HTTPClient_InitializeRequestHeaders().
   HTTPRequestHeaders_t requestHeaders;
    
   // Request for bytes 0 to 1023.
   httpLibraryStatus = HTTPClient_AddRangeHeader( &requestHeaders, 0, 1023 );

2. Request for the last N bytes, represented by rangeStartOrlastNbytes. rangeStartOrlastNbytes should be negative and rangeEnd should be HTTP_RANGE_REQUEST_END_OF_FILE. Example request header line: Range: bytes=-512\r\n for requesting the last 512 bytes (or bytes in the range [512, 1023] for a 1KB sized file).
   Example

   HTTPStatus_t httpLibraryStatus = HTTPSuccess;
   // Assume that requestHeaders has already been initialized with
   // HTTPClient_InitializeRequestHeaders().
   HTTPRequestHeaders_t requestHeaders;
    
   // Request for the last 512 bytes.
   httpLibraryStatus = HTTPClient_AddRangeHeader( &requestHeaders, -512, HTTP_RANGE_REQUEST_END_OF_FILE)

3. Request for all bytes (till the end of byte sequence) from byte N, represented by rangeStartOrlastNbytes. rangeStartOrlastNbytes should be >= 0 and rangeEnd should be HTTP_RANGE_REQUEST_END_OF_FILE.
   Example request header line: Range: bytes=256-\r\n for requesting all bytes after and including byte 256 (or bytes in the range [256,1023] for a 1kB sized file).
   Example

   HTTPStatus_t httpLibraryStatus = HTTPSuccess;
   // Assume that requestHeaders has already been initialized with
   // HTTPClient_InitializeRequestHeaders().
   HTTPRequestHeaders_t requestHeaders;
    
   // Request for all bytes from byte 256 onward.
   httpLibraryStatus = HTTPClient_AddRangeHeader( &requestHeaders, 256, HTTP_RANGE_REQUEST_END_OF_FILE)

Parameters

[in]	pRequestHeaders	Request header buffer information.
[in]	rangeStartOrlastNbytes	Represents either the starting byte for a range OR the last N number of bytes in the requested file.
[in]	rangeEnd	The ending range for the requested file. For end of file byte in Range Specifications 2. and 3., HTTP_RANGE_REQUEST_END_OF_FILE should be passed.

Returns

Returns the following status codes: HTTPSuccess, if successful. HTTPInvalidParameter, if input parameters are invalid, including when the rangeStartOrlastNbytes and rangeEnd parameter combination is invalid. HTTPInsufficientMemory, if the passed HTTPRequestHeaders_t.pBuffer contains insufficient remaining memory for storing the range request.