WinHttpQueryHeaders 함수(winhttp.h)

아티클
03/04/2024

WinHttpQueryHeaders 함수는 HTTP 요청과 연결된 헤더 정보를 검색합니다.

구문 분석된 헤더 이름 및 값 문자열을 검색하는 방법을 제공하는 WinHttpQueryHeadersEx도 참조하세요.

구문

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

매개 변수

[in] hRequest

WinHttpOpenRequest에서 반환된 HINTERNET 요청 핸들입니다. WinHttpReceiveResponse는 이 핸들에 대해 호출되었고 WinHttpQueryHeaders 가 호출되기 전에 완료되어야 합니다.

[in] dwInfoLevel

쿼리 정보 플래그 페이지에 나열된 특성 및 한정자 플래그의 조합을 지정하는 DWORD 형식의 값입니다. 이러한 특성 및 한정자 플래그는 정보가 요청되고 있으며 형식을 지정하는 방법을 나타냅니다.

[in, optional] pwszName

헤더 이름을 포함하는 문자열에 대한 포인터입니다. dwInfoLevel의 플래그가 WINHTTP_QUERY_CUSTOM 않으면 이 매개 변수를 WINHTTP_HEADER_NAME_BY_INDEX 설정합니다.

[out] lpBuffer

정보를 수신하는 버퍼에 대한 포인터입니다. 이 매개 변수를 WINHTTP_NO_OUTPUT_BUFFER 설정하면 이 함수가 FALSE를 반환합니다. GetLastError를 호출하면 ERROR_INSUFFICIENT_BUFFER 반환되고 lpdwBufferLength에는 요청된 정보를 보유하는 데 필요한 바이트 수가 포함됩니다.

[in, out] lpdwBufferLength

데이터 버퍼의 길이를 바이트 단위로 지정하는 DWORD 형식의 값에 대한 포인터입니다. 함수가 반환되면 이 매개 변수는 버퍼에 기록된 정보의 길이를 지정하는 값에 대한 포인터를 포함합니다. 함수가 문자열을 반환하면 다음 규칙이 적용됩니다.

함수가 성공하면 lpdwBufferLength 는 종료 null에 대해 문자열 길이를 바이트 단위로 빼기 2를 지정합니다.
함수가 실패하고 ERROR_INSUFFICIENT_BUFFER 반환되면 lpdwBufferLength 는 애플리케이션이 문자열을 수신하기 위해 할당해야 하는 바이트 수를 지정합니다.

[in, out] lpdwIndex

이름이 같은 여러 헤더를 열거하는 데 사용되는 0부터 시작하는 헤더 인덱스에 대한 포인터입니다. 함수를 호출할 때 이 매개 변수는 반환할 지정된 헤더의 인덱스입니다. 함수가 반환되면 이 매개 변수는 다음 헤더의 인덱스입니다. 다음 인덱스 를 찾을 수 없으면 ERROR_WINHTTP_HEADER_NOT_FOUND 반환됩니다. 헤더의 첫 번째 발생만 반환되도록 지정하려면 이 매개 변수를 WINHTTP_NO_HEADER_INDEX 설정합니다.

반환 값

성공하면 TRUE를 반환하고 그렇지 않으면 FALSE를 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 반환된 오류 코드 중에는 다음과 같습니다.

오류 코드	Description
ERROR_WINHTTP_HEADER_NOT_FOUND	요청된 헤더를 찾을 수 없습니다.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	제공된 핸들이 올바른 상태가 아니므로 요청된 작업을 수행할 수 없습니다.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	제공된 핸들의 형식이 이 작업에 잘못되었습니다.
ERROR_WINHTTP_INTERNAL_ERROR	내부 오류가 발생했습니다.
ERROR_NOT_ENOUGH_MEMORY	요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다. (Windows 오류 코드)

설명

WinHTTP가 비동기 모드에서 사용되는 경우에도(즉, WinHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우) 이 함수는 동기적으로 작동합니다. 반환 값은 성공 또는 실패를 나타냅니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

기본적으로 WinHttpQueryHeaders 는 문자열을 반환합니다. 그러나 dwInfoLevel에 적절한 한정자 플래그를 포함하여 SYSTEMTIME 구조 또는 DWORD 형식의 데이터를 요청할 수 있습니다. 다음 표에서는 WinHttpQueryHeaders 가 해당 데이터 형식을 선택하는 데 사용하는 한정자 플래그와 함께 반환할 수 있는 가능한 데이터 형식을 보여줍니다.

데이터 형식	한정자 플래그
LPCWSTR	기본값 한정자 플래그가 필요하지 않습니다.
Systemtime	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

참고 Windows XP 및 Windows 2000의 경우 WinHttp 시작 페이지의 런타임 요구 사항 섹션을 참조하세요.

예제

다음 예제에서는 HINTERNET 핸들을 가져오고, HTTP 세션을 열고, 요청 헤더를 만들고 보내고, 반환된 응답 헤더를 검사하는 방법을 보여줍니다.

    DWORD dwSize = 0;
    LPVOID lpOutBuffer = NULL;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/1.0",
                             WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                             WINHTTP_NO_PROXY_NAME,
                             WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER,
                                       WINHTTP_DEFAULT_ACCEPT_TYPES,
                                       0);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0,
                                       0, 0);

    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // First, use WinHttpQueryHeaders to obtain the size of the buffer.
    if (bResults)
    {
        WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,
                             WINHTTP_HEADER_NAME_BY_INDEX, NULL,
                             &dwSize, WINHTTP_NO_HEADER_INDEX);

        // Allocate memory for the buffer.
        if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )
        {
            lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

            // Now, use WinHttpQueryHeaders to retrieve the header.
            bResults = WinHttpQueryHeaders( hRequest,
                                       WINHTTP_QUERY_RAW_HEADERS_CRLF,
                                       WINHTTP_HEADER_NAME_BY_INDEX,
                                       lpOutBuffer, &dwSize,
                                       WINHTTP_NO_HEADER_INDEX);
        }
    }

    // Print the header contents.
    if (bResults)
        printf("Header contents: \n%S",lpOutBuffer);

    // Free the allocated memory.
    delete [] lpOutBuffer;

    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n",GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP, Windows 2000 Professional SP3 포함 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003, Windows 2000 Server SP3 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winhttp.h
라이브러리	Winhttp.lib
DLL	Winhttp.dll
재배포 가능 파일	Windows XP 및 Windows 2000에서 WinHTTP 5.0 및 인터넷 Explorer 5.01 이상.