WinHttpQueryDataAvailable 함수(winhttp.h)

WinHttpQueryDataAvailable 함수는 WinHttpReadData로 읽을 수 있는 데이터 양을 바이트 단위로 반환합니다.

구문

WINHTTPAPI BOOL WinHttpQueryDataAvailable(
  [in]  HINTERNET hRequest,
  [out] LPDWORD   lpdwNumberOfBytesAvailable
);

매개 변수

[in] hRequest

WinHttpOpenRequest에서 반환된 유효한 HINTERNET 핸들입니다. WinHttpReceiveResponse 는 이 핸들에 대해 호출되었고 WinHttpQueryDataAvailable 이 호출되기 전에 완료되어야 합니다.

[out] lpdwNumberOfBytesAvailable

사용 가능한 바이트 수를 받는 부호 없는 긴 정수 변수에 대한 포인터입니다. WinHTTP가 비동기 모드에서 사용되는 경우 항상 이 매개 변수를 NULL 로 설정하고 콜백 함수에서 데이터를 검색합니다. 이렇게 하지 않으면 메모리 오류가 발생할 수 있습니다.

반환 값

함수가 성공하면 TRUE 를 반환하고, 그렇지 않으면 FALSE 를 반환합니다. 확장 오류 데이터를 얻으려면 GetLastError를 호출합니다. 반환된 오류 코드 중에는 다음이 있습니다.

오류 코드 Description
ERROR_WINHTTP_CONNECTION_ERROR
서버와의 연결이 다시 설정되거나 종료되었거나 호환되지 않는 SSL 프로토콜이 발견되었습니다. 예를 들어 WinHTTP 버전 5.1은 클라이언트가 특별히 사용하도록 설정하지 않는 한 SSL2를 지원하지 않습니다.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
제공된 핸들이 올바른 상태가 아니므로 요청된 작업을 완료할 수 없습니다.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
이 작업에 대해 제공된 핸들의 형식이 올바르지 않습니다.
ERROR_WINHTTP_INTERNAL_ERROR
내부 오류가 발생했습니다.
ERROR_WINHTTP_OPERATION_CANCELLED
작업이 완료되기 전에 요청이 작동 중인 핸들이 닫혔기 때문에 작업이 취소되었습니다.
ERROR_WINHTTP_TIMEOUT
요청 시간이 초과되었습니다.
ERROR_NOT_ENOUGH_MEMORY
메모리가 부족하여 요청된 작업을 완료할 수 없습니다. (Windows 오류 코드)

설명

WinHTTP가 비동기 모드에서 사용되는 경우에도(즉, winHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우) 이 함수는 동기적으로 또는 비동기적으로 작동할 수 있습니다. FALSE를 반환하는 경우 실패했으며 GetLastError를 호출하여 확장된 오류 정보를 가져올 수 있습니다. TRUE를 반환하는 경우 WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE 완료를 사용하여 이 함수가 성공했는지 여부와 매개 변수 값을 확인합니다. WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 완료는 작업이 비동기적으로 완료되었지만 실패했음을 나타냅니다.

경고 WinHTTP가 비동기 모드에서 사용되는 경우 항상 lpdwNumberOfBytesAvailable 매개 변수를 NULL 로 설정하고 콜백 함수에서 사용할 수 있는 바이트를 검색합니다. 그렇지 않으면 메모리 오류가 발생할 수 있습니다.
 
이 함수는 WinHttpReadData에 대한 후속 호출을 통해 즉시 읽을 수 있는 데이터 바이트 수를 반환합니다. 사용할 수 있는 데이터가 없고 파일의 끝에 도달하지 않은 경우 두 가지 중 하나가 발생합니다. 세션이 동기적이면 데이터를 사용할 수 있게 될 때까지 요청이 대기합니다. 세션이 비동기인 경우 함수는 TRUE를 반환하고 데이터를 사용할 수 있게 되면 WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE 사용하여 콜백 함수를 호출하고 WinHttpReadData를 호출하여 즉시 읽을 수 있는 바이트 수를 나타냅니다.

WinHttpQueryDataAvailable 호출로 표시된 사용 가능한 모든 데이터를 읽을 때까지 남아 있는 데이터의 양은 다시 계산되지 않습니다.

WinHttpReadData의 반환 값을 사용하여 응답이 완전히 읽혀진 시기를 확인합니다.

중요WinHttpQueryDataAvailable 의 반환 값을 사용하여 응답의 끝에 도달했는지 여부를 결정하지 마세요. 모든 서버가 응답을 제대로 종료하지 않고 부적절하게 종료된 응답으로 인해 WinHttpQueryDataAvailable 에서 더 많은 데이터를 예상할 수 있기 때문입니다.
 
WinHttpOpenRequest 함수에서 만들고 WinHttpSendRequest에서 보낸 HINTERNET 핸들의 경우 WinHttpQueryDataAvailable을 사용하려면 먼저 핸들에서 WinHttpReceiveResponse 호출을 수행해야 합니다.

WinHttpSetStatusCallback과 함께 상태 콜백 함수가 설치된 경우 WinHttpSetStatusCallbackdwNotificationFlags 매개 변수에 설정된 다음 알림 중에서 사용 가능한 데이터를 확인하는 진행률을 나타냅니다.

  • WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
  • WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
  • WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE
참고 Windows XP 및 Windows 2000에 대한 자세한 내용은 런타임 요구 사항을 참조하세요.
 

예제

다음 예제에서는 보안 트랜잭션 의미 체계를 사용하여 HTTPS 서버에서 리소스를 다운로드하는 방법을 보여 줍니다. 샘플 코드는 WinHTTP API를 초기화하고 대상 HTTPS 서버를 선택한 다음 이 보안 리소스에 대한 요청을 열고 보냅니다.
WinHttpQueryDataAvailable 은 요청 핸들과 함께 사용하여 다운로드할 수 있는 데이터의 양을 확인한 다음 WinHttpReadData 를 사용하여 해당 데이터를 읽습니다. 이 프로세스는 전체 문서를 검색하고 표시할 때까지 반복됩니다.

중요

일부 데이터를 최대한 빨리 원하는 경우(즉, 데이터를 수신할 때 데이터를 처리하고 구문 분석하는 경우) WinHttpQueryDataAvailableWinHttpReadData를 호출해야 합니다. 전체 응답을 최대한 빨리 다운로드하려는 경우 WinHttpReadData 가 완료하기 전에 버퍼를 채우려고 하기 때문에 WinHttpReadData 를 직접 호출합니다.

또한 아래 코드 예제는 모든 루프 반복에 할당합니다. 성능이 중요한 프로덕션 코드의 경우 적절한 크기의 버퍼(1메가바이트)로 시작하고 필요한 경우 크기를 조정할 수 있습니다. 실제로 WinHttpQueryDataAvailable 은 8킬로바이트 이하를 반환합니다.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/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_HTTPS_PORT, 0);

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

    // 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);

    // Continue to verify data until there is nothing left.
    if (bResults)
        do 
        {

            // Verify available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf( "Error %u in WinHttpQueryDataAvailable.\n",
                        GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


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

    // Close 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 및 Internet Explorer 5.01 이상

추가 정보

Microsoft Windows HTTP 서비스 정보(WinHTTP)

WinHTTP 버전

WinHttpCloseHandle

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest

WinHttpReadData

WinHttpSendRequest