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

서버에서 SSL(Secure Sockets Layer) 인증서를 검색하는 동안 하나 이상의 오류가 발생했습니다. lpvStatusInformation 매개 변수에는 플래그가 포함됩니다. 자세한 내용은 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 값을 제공합니다.

반환 값

없음

설명

콜백 함수는 별도의 요청에 대해 다른 스레드에서 호출되고 현재 요청에 대해 동일한 스레드에서 다시 입력될 수 있으므로 threadsafe 및 reentrant여야 합니다. 따라서 처리하는 동안 재진입을 안전하게 처리하도록 코딩해야 합니다. 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 및 인터넷 Explorer 5.01 이상.

추가 정보

WinHTTP 버전

WinHttpSetStatusCallback