WinHttpQueryHeadersEx function (winhttp.h)
Retrieves header information associated with an HTTP request; offers a way to retrieve parsed header name and value strings.
Syntax
WINHTTPAPI DWORD WinHttpQueryHeadersEx(
HINTERNET hRequest,
DWORD dwInfoLevel,
ULONGLONG ullFlags,
UINT uiCodePage,
PDWORD pdwIndex,
PWINHTTP_HEADER_NAME pHeaderName,
PVOID pBuffer,
PDWORD pdwBufferLength,
PWINHTTP_EXTENDED_HEADER *ppHeaders,
PDWORD pdwHeadersCount
);
Parameters
hRequest
Type: _In_ HINTERNET
Request handle returned by WinHttpOpenRequest. The WinHttpReceiveResponse call for this handle must have completed before calling WinHttpQueryHeadersEx. If you're querying trailers, then the WinHttpReadData call for this handle must return 0 bytes read before calling WinHttpQueryHeadersEx.
dwInfoLevel
Type: _In_ DWORD
Value of type DWORD that specifies a combination of attribute and modifier flags listed in the Query info flags topic. These attribute and modifier flags indicate the information that is being requested, and how it is to be formatted.
Note
The following flags return ERROR_INVALID_PARAMETER if used: WINHTTP_QUERY_VERSION, WINHTTP_QUERY_STATUS_CODE, WINHTTP_QUERY_STATUS_TEXT, WINHTTP_QUERY_FLAG_NUMBER, WINHTTP_QUERY_FLAG_NUMBER64, WINHTTP_QUERY_FLAG_SYSTEMTIME, and WINHTTP_QUERY_RAW_HEADERS_CRLF.
The flag WINHTTP_QUERY_EX_ALL_HEADERS returns all the headers.
If you're not querying for all of the headers, then you can pass the flag corresponding to a specific known header, or you can pass WINHTTP_QUERY_CUSTOM along with a string for the header name in the pHeaderName parameter.
Passing WINHTTP_QUERY_FLAG_WIRE_ENCODING returns the headers in the format in which they're sent over the wire (you should access/set the psz* members of WINHTTP_EXTENDED_HEADER and WINHTTP_HEADER_NAME). If you don't set the wire encoding flag, then the default behavior is to return headers in Unicode format (you should access/set the pwsz* members of WINHTTP_EXTENDED_HEADER and WINHTTP_HEADER_NAME).
ullFlags
Type: _In_ ULONGLONG
Reserved. Set to 0.
uiCodePage
Type: _In_ UINT
The code page to use for Unicode conversion. You should pass in 0 for default behavior (CP_ACP), or when using WINHTTP_QUERY_FLAG_WIRE_ENCODING. No validation is done for this parameter.
pdwIndex
Type: _Inout_opt_ PDWORD
The address of a zero-based index used to enumerate multiple headers with the same name. When calling the function, this parameter is the index of the specified header to return. When the function returns, this parameter is the index of the next header. Pass NULL to access the first instance of a given header.
pHeaderName
Type: _Inout_opt_ PWINHTTP_HEADER_NAME
The address of a WINHTTP_HEADER_NAME structure.
Set pHeaderName to NULL when retrieving all headers. If this parameter is not NULL, and you pass WINHTTP_QUERY_CUSTOM with dwInfoLevel, then WinHttpQueryHeadersEx will retrieve only the header specified by this parameter. If you pass WINHTTP_QUERY_FLAG_WIRE_ENCODING with dwInfoLevel, then you should use the pszName member (if the flag is not set, then use pwszName member).
pBuffer
Type: _Out_writes_bytes_to_opt_(*pdwBufferLength, *pdwBufferLength) LPVOID
A caller-provided buffer to store the parsed header pointers and the headers. If this parameter is NULL or too small, then WinHttpQueryHeadersEx returns ERROR_INSUFFICIENT_BUFFER, and the pdwBufferLength parameter contains the required buffer size in bytes.
pdwBufferLength
Type: _Inout_ PDWORD
Length of the caller-provided buffer. If pBuffer is NULL or too small, then WinHttpQueryHeadersEx writes the required buffer size in bytes to this parameter.
ppHeaders
Type: _Out_writes_opt_(*pdwHeadersCount) PWINHTTP_EXTENDED_HEADER*
A handle to an array of WINHTTP_EXTENDED_HEADER for accessing parsed header names/values. You should pass in the address of a WINHTTP_EXTENDED_HEADER pointer that's initialized to NULL. Upon completion, you should access the pszName/pszValue parameters if using WINHTTP_QUERY_FLAG_WIRE_ENCODING, and pwszName/pwszValue otherwise.
pdwHeadersCount
Type: _Out_ PDWORD
The number of headers returned. You shouldn't try to access beyond ppHeaders[cHeaders - 1], because that is out of bounds of the array.
Return value
A status code indicating the result of the operation. Among the error codes returned are the following.
| Error Code | Description |
|---|---|
|
The requested header could not be located. |
|
The requested operation cannot be carried out because the handle supplied is not in the correct state. |
|
The type of handle supplied is incorrect for this operation. |
|
An internal error has occurred. |
|
Not enough memory was available to complete the requested operation. (Windows error code) |
Remarks
WinHttpQueryHeadersEx builds on the functionality of WinHttpQueryHeaders. WinHttpQueryHeaders allows you to query request or response headers (or response trailers) in the form of a string, a number (DWORD), or a timestamp (SYSTEMTIME). Querying for all headers returns a single serialized string with CRLF or NULL characters delimiting different headers. For example, "Name1: value1\r\nName2: value2\r\n\r\n". Or "Name1: value1\0Name2: value2\0\0". A double delimiter is used to indicate the end of the string.
WinHttpQueryHeadersEx gives you a way to retrieve parsed header name and value strings.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10 Build 20348 |
| Minimum supported server | Windows 10 Build 20348 |
| Target Platform | Windows |
| Header | winhttp.h |
| Library | Winhttp.lib |
| DLL | Winhttp.dll |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for