WINHTTP_STATUS_CALLBACK 콜백 함수(winhttp.h)

아티클
08/27/2023

WINHTTP_STATUS_CALLBACK 형식은 애플리케이션에서 정의한 상태 콜백 함수를 나타냅니다.

구문

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

매개 변수

[in] hInternet

콜백 함수가 호출되는 핸들입니다.

[in] dwContext

hInternet 매개 변수의 핸들과 연결된 애플리케이션 정의 컨텍스트 값을 지정하는 DWORD에 대한 포인터입니다.

컨텍스트 값은 WINHTTP_OPTION_CONTEXT_VALUE 옵션으로 WinHttpSetOption을 호출하여 세션, 연결 또는 요청 핸들에 할당할 수 있습니다. 또는 WinHttpSendRequest 를 사용하여 컨텍스트 값을 요청 핸들과 연결할 수 있습니다.

[in] dwInternetStatus

콜백 함수가 호출되는 이유를 나타내는 상태 코드를 지정하는 DWORD 를 가리킵니다. 다음 값 중 하나일 수 있습니다.

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

서버에 대한 연결을 닫습니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

서버에 성공적으로 연결되었습니다. lpvStatusInformation 매개 변수에는 점선 표기법으로 서버의 IP 주소를 나타내는 LPWSTR에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

서버에 연결. lpvStatusInformation 매개 변수에는 점선 표기법으로 서버의 IP 주소를 나타내는 LPWSTR에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

서버에 대한 연결을 성공적으로 닫습니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

WinHttpReadData를 사용하여 데이터를 검색할 수 있습니다. lpvStatusInformation 매개 변수는 사용 가능한 데이터 바이트 수를 포함하는 DWORD를 가리킵니다. dwStatusInformationLength 매개 변수 자체는 4(DWORD의 크기)입니다.

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

HINTERNET 핸들이 만들어졌습니다. lpvStatusInformation 매개 변수에는 HINTERNET 핸들에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

이 핸들 값이 종료되었습니다. lpvStatusInformation 매개 변수에는 HINTERNET 핸들에 대한 포인터가 포함되어 있습니다. 이 핸들에 대한 콜백은 더 이상 없습니다.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

응답 헤더가 수신되었으며 WinHttpQueryHeaders에서 사용할 수 있습니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

서버에서 중간(100 수준) 상태 코드 메시지를 받았습니다. lpvStatusInformation 매개 변수에는 상태 코드를 나타내는 DWORD에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

서버의 IP 주소를 찾았습니다. lpvStatusInformation 매개 변수에는 확인된 이름을 나타내는 LPWSTR에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

서버에서 데이터를 성공적으로 읽었습니다. lpvStatusInformation 매개 변수에는 WinHttpReadData 호출에 지정된 버퍼에 대한 포인터가 포함되어 있습니다. dwStatusInformationLength 매개 변수에는 읽은 바이트 수가 포함됩니다.

WinHttpWebSocketReceive에서 사용하는 경우 lpvStatusInformation 매개 변수는 WINHTTP_WEB_SOCKET_STATUS 구조체에 대한 포인터를 포함하고 dwStatusInformationLength 매개 변수는 lpvStatusInformation의 크기를 나타냅니다.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

서버가 요청에 응답할 때까지 대기합니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_REDIRECT

HTTP 요청이 요청을 자동으로 리디렉션하려고 합니다. lpvStatusInformation 매개 변수에는 새 URL을 나타내는 LPWSTR에 대한 포인터가 포함되어 있습니다. 이 시점에서 애플리케이션은 리디렉션 응답을 사용하여 서버에서 반환된 모든 데이터를 읽고 응답 헤더를 쿼리할 수 있습니다. 핸들을 닫아 작업을 취소할 수도 있습니다.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

HTTP 요청을 보내는 동안 오류가 발생했습니다. lpvStatusInformation 매개 변수에는 WINHTTP_ASYNC_RESULT 구조체에 대한 포인터가 포함되어 있습니다. 해당 dwResult 멤버는 호출된 함수의 ID를 나타내고 dwError는 반환 값을 나타냅니다.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

서버로 정보 요청을 성공적으로 보냈습니다. lpvStatusInformation 매개 변수에는 전송된 바이트 수를 나타내는 DWORD에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

서버 이름의 IP 주소를 조회합니다. lpvStatusInformation 매개 변수에는 확인 중인 서버 이름에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

서버에서 응답을 받았습니다. lpvStatusInformation 매개 변수에는 수신된 바이트 수를 나타내는 DWORD에 대한 포인터가 포함되어 있습니다.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

서버에 대한 보안(HTTPS) 연결을 설정하는 동안 하나 이상의 오류가 발생했습니다. lpvStatusInformation 매개 변수에는 오류 값의 비트 OR 조합인 DWORD에 대한 포인터가 포함되어 있습니다. 자세한 내용은 lpvStatusInformation에 대한 설명을 참조하세요.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

서버에 정보 요청을 보냅니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

요청이 성공적으로 완료되었습니다. lpvStatusInformation 매개 변수는 WinHttpSendRequest(초기 요청 본문)에 전달된 lpOptional 값이며, dwStatusInformationLength 매개 변수는 성공적으로 작성된 초기 본문 바이트 수를 나타냅니다(WinHttpSendRequest에 전달된 dwOptionalLength 값).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

데이터가 서버에 성공적으로 기록되었습니다. lpvStatusInformation 매개 변수에는 작성된 바이트 수를 나타내는 DWORD에 대한 포인터가 포함되어 있습니다.

WinHttpWebSocketSend에서 사용하는 경우 lpvStatusInformation 매개 변수는 WINHTTP_WEB_SOCKET_STATUS 구조체에 대한 포인터를 포함하고 dwStatusInformationLength 매개 변수는 lpvStatusInformation의 크기를 나타냅니다.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

WinHttpGetProxyForUrlEx 호출로 시작된 작업이 완료되었습니다. WinHttpReadData를 사용하여 데이터를 검색할 수 있습니다.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

WinHttpWebSocketClose 호출을 통해 연결이 성공적으로 닫혔습니다. lpvStatusInformation 매개 변수는 NULL입니다.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

WinHttpWebSocketShutdown 호출을 통해 연결이 성공적으로 종료되었습니다. lpvStatusInformation 매개 변수는 NULL입니다.

[in] lpvStatusInformation

콜백 함수에 대한 이 호출과 관련한 정보를 지정하는 버퍼에 대한 포인터입니다. 이러한 데이터의 형식은 dwInternetStatus 인수의 값에 따라 달라집니다. 자세한 내용은 dwInternetStatus를 참조하세요.

dwInternetStatus 인수가 WINHTTP_CALLBACK_STATUS_SECURE_FAILURE 경우 lpvStatusInformation은 다음 값 중 하나 이상의 비트 OR 조합인 DWORD를 가리킵니다.

값	의미
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	인증 해지 검사를 사용하도록 설정했지만 해지 검사에서 인증서가 해지되었는지 여부를 확인하지 못했습니다. 해지를 확인하는 데 사용되는 서버에 연결할 수 없습니다.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	SSL 인증서가 잘못되었습니다.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	SSL 인증서가 해지되었습니다.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	이 함수는 서버의 인증서를 생성한 인증 기관에 익숙하지 않습니다.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	SSL 인증서 일반 이름(호스트 이름 필드)이 올바르지 않습니다. 예를 들어 www.microsoft.com 입력한 경우 인증서의 일반 이름이 www.msn.com.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	서버에서 받은 SSL 인증서 날짜가 잘못되었습니다. 인증서가 만료되었습니다.
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	애플리케이션에서 SSL 라이브러리를 로드하는 동안 내부 오류가 발생했습니다.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT 상태 콜백은 lpvStatusInformation에서 가리키는 LPWSTR의 문자 수에 해당하는 dwStatusInformationLength 값을 제공합니다.

반환 값

없음

설명

콜백 함수는 별도의 요청에 대해 다른 스레드에서 호출되고 현재 요청에 대해 동일한 스레드에서 다시 입력될 수 있으므로 스레드 안전 및 재진입이어야 합니다. 따라서 처리하는 동안 재진입을 안전하게 처리하도록 코딩되어야 합니다. dwInternetStatus 매개 변수가 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 동일한 경우 이 콜백은 마지막 콜백으로 보장되고 이 요청에 대한 다른 메시지가 처리될 때 발생하지 않으므로 동일한 요청에 대한 재진입을 처리할 수 없습니다.

상태 콜백 함수는 알림 플래그를 통해 비동기 작업의 상태에 대한 업데이트를 받습니다. 특정 작업이 완료되었음을 나타내는 알림을 완료 알림 또는 완료라고 합니다. 다음 표에는 6개의 완료 플래그와 이 플래그가 수신될 때 완료되는 해당 함수가 나열되어 있습니다.

완료 플래그	함수
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	위의 함수는 오류가 발생할 때 작동합니다.

콜백은 요청을 처리하는 동안 이루어지므로 애플리케이션은 네트워크에서 데이터 처리량 저하를 방지하기 위해 콜백 함수에서 가능한 한 적은 시간을 소비해야 합니다. 예를 들어 콜백 함수에 대화 상자를 표시하는 작업은 서버가 요청을 종료하는 긴 작업일 수 있습니다.

콜백 함수는 요청을 시작한 스레드와 다른 스레드 컨텍스트에서 호출할 수 있습니다.

마찬가지로 WinHttp를 비동기적으로 호출할 때 콜백 스레드 선호도는 없습니다. 한 스레드에서 호출을 시작할 수 있지만 다른 스레드는 콜백을 받을 수 있습니다.

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

요구 사항

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

추가 정보

WinHTTP 버전

WinHttpSetStatusCallback

다음을 통해 공유