WinHttpSendRequest 함수(winhttp.h)
WinHttpSendRequest 함수는 지정된 요청을 HTTP 서버로 보냅니다.
구문
WINHTTPAPI BOOL WinHttpSendRequest(
[in] HINTERNET hRequest,
[in, optional] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in, optional] LPVOID lpOptional,
[in] DWORD dwOptionalLength,
[in] DWORD dwTotalLength,
[in] DWORD_PTR dwContext
);
매개 변수
[in] hRequest
WinHttpOpenRequest에서 반환된 HINTERNET 핸들입니다.
[in, optional] lpszHeaders
요청에 추가할 추가 헤더가 포함된 문자열에 대한 포인터입니다. 추가할 추가 헤더가 없는 경우 이 매개 변수를 WINHTTP_NO_ADDITIONAL_HEADERS 수 있습니다.
[in] dwHeadersLength
추가 헤더의 길이(문자)를 포함하는 부호 없는 long 정수 값입니다. 이 매개 변수가 -1L 이고 pwszHeaders 가 NULL이 아닌 경우 이 함수는 pwszHeaders 가 null로 종료되고 길이가 계산된다고 가정합니다.
[in, optional] lpOptional
요청 헤더 바로 다음에 보낼 선택적 데이터가 포함된 버퍼에 대한 포인터입니다. 이 매개 변수는 일반적으로 POST 및 PUT 작업에 사용됩니다. 선택적 데이터는 서버에 게시된 리소스 또는 데이터일 수 있습니다. 보낼 선택적 데이터가 없는 경우 이 매개 변수를 WINHTTP_NO_REQUEST_DATA 수 있습니다.
dwOptionalLength 매개 변수가 0이면 이 매개 변수가 무시되고 NULL로 설정됩니다.
이 버퍼는 요청 핸들이 닫히거나 WinHttpReceiveResponse 호출이 완료될 때까지 계속 사용할 수 있어야 합니다.
[in] dwOptionalLength
선택적 데이터의 길이(바이트)를 포함하는 부호 없는 long 정수 값입니다. 보낼 선택적 데이터가 없는 경우 이 매개 변수는 0일 수 있습니다.
lpOptional 매개 변수가 NULL이 아닌 경우 이 매개 변수는 유효한 길이를 포함해야 합니다. 그렇지 않으면 lpOptional 이 무시되고 NULL로 설정됩니다.
[in] dwTotalLength
전송된 총 데이터의 길이(바이트)를 포함하는 부호 없는 long 정수 값입니다. 이 매개 변수는 요청의 Content-Length 헤더를 지정합니다. 이 매개 변수의 값이 dwOptionalLength에 지정된 길이보다 크면 WinHttpWriteData 를 사용하여 추가 데이터를 보낼 수 있습니다.
dwTotalLength 는 동일한 요청에 대해 WinHttpSendRequest 호출 간에 변경되지 않아야 합니다. dwTotalLength를 변경해야 하는 경우 호출자는 새 요청을 만들어야 합니다.
[in] dwContext
요청 핸들을 사용하여 모든 콜백 함수에 전달되는 애플리케이션 정의 값을 포함하는 포인터 크기 변수에 대한 포인터입니다.
반환 값
성공하면 TRUE를 반환하고 그렇지 않으면 FALSE를 반환합니다. 확장 오류 정보는 GetLastError를 호출합니다. 오류 코드는 다음 표에 나와 있습니다.
| 오류 코드 | Description |
|---|---|
|
서버에 연결하지 못한 경우 반환됩니다. |
|
보안 HTTP 서버에는 클라이언트 인증서가 필요합니다. 애플리케이션은 WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST 옵션을 사용하여 WinHttpQueryOption을 호출하여 인증서 발급자 목록을 검색합니다.
서버에서 클라이언트 인증서를 요청하지만 필요하지 않은 경우 애플리케이션은 WINHTTP_OPTION_CLIENT_CERT_CONTEXT 옵션을 사용하여 WinHttpSetOption을 번갈아 호출할 수 있습니다. 이 경우 애플리케이션은 WinHttpSetOption의 lpBuffer 매개 변수에 WINHTTP_NO_CLIENT_CERT_CONTEXT 매크로를 지정합니다. 자세한 내용은 WINHTTP_OPTION_CLIENT_CERT_CONTEXT 옵션을 참조하세요. Windows Server 2003 SP1, Windows XP SP2 및 Windows 2000: 이 오류는 지원되지 않습니다. |
|
서버와의 연결이 다시 설정되거나 종료되었거나 호환되지 않는 SSL 프로토콜이 발견되었습니다. 예를 들어 WinHTTP 버전 5.1은 클라이언트가 특별히 사용하도록 설정하지 않는 한 SSL2를 지원하지 않습니다. |
|
제공된 핸들이 올바른 상태가 아니므로 요청된 작업을 수행할 수 없습니다. |
|
제공된 핸들의 형식이 이 작업에 잘못되었습니다. |
|
내부 오류가 발생했습니다. |
|
URL이 올바르지 않습니다. |
|
로그인 시도가 실패했습니다. 이 오류가 발생하면 WinHttpCloseHandle을 사용하여 요청 핸들을 닫아야 합니다. 원래 이 오류를 생성한 함수를 다시 시도하기 전에 새 요청 핸들을 만들어야 합니다. |
|
서버 이름을 확인할 수 없습니다. |
|
작업이 완료되기 전에 요청이 작동 중인 핸들이 닫혔기 때문에 작업이 취소되었습니다. |
|
들어오는 응답이 내부 WinHTTP 크기 제한을 초과하면 반환됩니다. |
|
서버에서 보낸 SSL(Secure Sockets Layer) 인증서에서 하나 이상의 오류가 발견되었습니다. 발생한 오류 유형을 확인하려면 상태 콜백 함수의 WINHTTP_CALLBACK_STATUS_SECURE_FAILURE 알림을 통해 확인합니다. 자세한 내용은 WINHTTP_STATUS_CALLBACK. |
|
WinHTTP 함수 지원이 종료되거나 언로드됩니다. |
|
요청 시간이 초과된 경우 |
|
URL은 "http:" 또는 "https:" 이외의 체계를 지정했습니다. |
|
요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다. (Windows 오류 코드) Windows Server 2003, Windows XP 및 Windows 2000: WINHTTP_OPTION_PORT_RESERVATION 옵션으로 설정된 TCP 예약 범위가 이 요청을 보낼 만큼 크지 않습니다. |
|
dwTotalLength 매개 변수에 지정된 콘텐츠 길이가 Content-Length 헤더에 지정된 길이와 일치하지 않습니다.
lpOptional 매개 변수는 NULL이어야 하며 Transfer-Encoding 헤더가 있는 경우 dwOptionalLength 매개 변수는 0이어야 합니다. Transfer-Encoding 헤더가 있는 경우 Content-Length 헤더를 사용할 수 없습니다. |
|
리디렉션 또는 인증 문제로 인해 애플리케이션 에서 WinHttpSendRequest 를 다시 호출해야 합니다.
Windows Server 2003 SP1, Windows XP SP2 및 Windows 2000: 이 오류는 지원되지 않습니다. |
설명
WinHTTP가 비동기 모드에서 사용되는 경우에도, 즉 WinHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우 이 함수는 동기적으로 또는 비동기적으로 작동할 수 있습니다. 두 경우 모두 요청이 성공적으로 전송되면 완료 상태 WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE 설정하여 애플리케이션이 다시 호출됩니다. WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 완료는 작업이 비동기적으로 완료되었지만 실패했음을 나타냅니다. WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE 상태 콜백을 받으면 애플리케이션이 WinHttpReceiveResponse를 사용하여 서버에서 응답을 받기 시작할 수 있습니다. 그 전에는 다른 비동기 함수를 호출할 수 없으며, 그렇지 않으면 ERROR_WINHTTP_INCORRECT_HANDLE_STATE 반환됩니다.
애플리케이션은 요청 핸들이 닫히거나 WinHttpReceiveResponse에 대한 호출이 완료될 때까지 lpOptional이 가리키는 버퍼를 삭제하거나 변경해서는 안 됩니다. 응답 수신 과정에서 선택적 데이터가 필요한 인증 챌린지 또는 리디렉션이 발생할 수 있기 때문입니다. WinHttpCloseHandle을 사용하여 작업을 중단해야 하는 경우 애플리케이션은 ERROR_WINHTTP_OPERATION_CANCELLED 오류 코드가 있는 콜백 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 받을 때까지 버퍼를 유효한 상태로 유지해야 합니다.
WinHTTP를 동기적으로 사용하는 경우, 즉 winHttpOpen에서 WINHTP_FLAG_ASYNC 설정되지 않은 경우 콜백 함수가 등록된 경우에도 완료 상태 애플리케이션이 호출되지 않습니다. 이 모드에서는 WinHttpSendRequest가 반환되면 애플리케이션에서 WinHttpReceiveResponse를 호출할 수 있습니다.
WinHttpSendRequest 함수는 지정된 요청을 HTTP 서버로 보내고 클라이언트가 요청과 함께 보낼 추가 헤더를 지정할 수 있도록 합니다.
또한 이 함수를 사용하면 클라이언트가 요청 헤더 바로 다음에 HTTP 서버로 보낼 선택적 데이터를 지정할 수 있습니다. 이 기능은 일반적으로 PUT 및 POST와 같은 쓰기 작업에 사용됩니다.
애플리케이션은 WinHttpSendRequest에 대한 여러 호출에서 동일한 HTTP 요청 핸들을 사용하여 동일한 요청을 다시 보낼 수 있지만 애플리케이션은 이 함수를 다시 호출하기 전에 이전 호출에서 반환된 모든 데이터를 읽어야 합니다.
이 함수와 함께 추가된 요청 헤더의 이름과 값의 유효성이 검사됩니다. 헤더는 잘 구성되어야 합니다. 유효한 HTTP 헤더에 대한 자세한 내용은 RFC 2616을 참조하세요. 잘못된 헤더를 사용하면 이 함수가 실패하고 GetLastError가ERROR_INVALID_PARAMETER 반환합니다. 잘못된 헤더가 추가되지 않았습니다.
Windows 2000: 여러 스레드에서 요청을 보낼 때 네트워크 및 CPU 성능이 크게 저하될 수 있습니다.
Windows XP 및 Windows 2000: 런타임 요구 사항을 참조하세요.
WinHttpSetStatusCallback
winHttpSetStatusCallback과 함께 상태 콜백 함수가 설치된 경우 WinHttpSetStatusCallback의 dwNotificationFlags 매개 변수에 설정된 다음 알림 중에서 요청을 보내는 진행률을 나타냅니다.- WINHTTP_CALLBACK_STATUS_DETECTING_PROXY(구현되지 않음)
- WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE(비동기 모드에서만 해당)
- WINHTTP_CALLBACK_STATUS_REDIRECT
- WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
- WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
- WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
- WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
- WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
4GB 초과 업로드 지원
Windows Vista 및 Windows Server 2008부터 WinHttp는 Content-Length 헤더를 사용하여 LARGE_INTEGER 크기(2^64바이트)까지 파일 업로드를 지원합니다. WinHttpSendRequest 호출에 지정된 페이로드 길이는 DWORD 크기(2^32바이트)로 제한됩니다. DWORD보다 큰 URL에 데이터를 업로드하려면 애플리케이션이 요청의 Content-Length 헤더에 길이를 제공해야 합니다. 이 경우 WinHttp 클라이언트 애플리케이션은 dwTotalLength 매개 변수가 WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH 설정된 WinHttpSendRequest를 호출합니다.Content-Length 헤더가 2^32보다 작은 길이를 지정하는 경우 애플리케이션은 WinHttpSendRequest 호출에서도 콘텐츠 길이를 지정해야 합니다. dwTotalLength 매개 변수가 Content-Length 헤더에 지정된 길이와 일치하지 않으면 호출이 실패하고 ERROR_INVALID_PARAMETER 반환합니다.
Content-Length 헤더는 WinHttpAddRequestHeaders 호출에 추가하거나 다음 코드 예제와 같이 WinHttpSendRequest의 lpszHeader 매개 변수에 지정할 수 있습니다.
BOOL fRet = WinHttpSendRequest(
hReq,
L"Content-Length: 68719476735\r\n",
-1L,
WINHTTP_NO_REQUEST_DATA,
0,
WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
pMyContent);
Transfer-Encoding 헤더
Windows Vista 및 Windows Server 2008부터 WinHttp를 사용하면 애플리케이션이 서버로 전송된 데이터에 대해 청크 분할 전송 인코딩을 수행할 수 있습니다. winHttp 요청에 Transfer-Encoding 헤더가 있으면 WinHttpSendRequest 호출의 dwTotalLength 매개 변수가 WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH 설정되고 애플리케이션은 WinHttpWriteData에 대한 하나 이상의 호출로 엔터티 본문을 보냅니다. WinHttpSendRequest의 lpOptional 매개 변수는 NULL이어야 하고 dwOptionLength 매개 변수는 0이어야 합니다. 그렇지 않으면 ERROR_WINHTTP_INVALID_PARAMETER 오류가 반환됩니다. 청크 분할된 데이터 전송을 종료하기 위해 애플리케이션은 길이가 0인 청크를 생성하고 WinHttpWriteData에 대한 마지막 호출에서 보냅니다.예제
다음 코드 예제에서는 HINTERNET 핸들을 가져오고, HTTP 세션을 열고, 요청 헤더를 만들고, 해당 헤더를 서버에 보내는 방법을 보여줍니다.
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.wingtiptoys.com",
INTERNET_DEFAULT_HTTP_PORT, 0);
// Create an HTTP Request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"PUT",
L"/writetst.txt",
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);
// Place additional code here.
// Report 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 및 인터넷 Explorer 5.01 이상. |
추가 정보
Microsoft Windows HTTP 서비스 정보(WinHTTP)
WINHTTP_STATUS_CALLBACK
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기