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 を呼び出します。 エラー コードを次の表に示します。
| エラー コード | 説明 |
|---|---|
|
サーバーへの接続に失敗した場合に返されます。 |
|
セキュリティで保護された 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 サイズ制限を超えたときに返されます。 |
|
サーバーから送信された Secure Sockets Layer (SSL) 証明書で、1 つ以上のエラーが見つかりました。 発生したエラーの種類を確認するには、状態コールバック関数の 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 が同期的に使用されている場合、つまり、 WINHTP_FLAG_ASYNC が WinHttpOpen で設定されていない場合、コールバック関数が登録されていても、完了状態でアプリケーションは呼び出されません。 このモードでは、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
4 GB を超えるアップロードのサポート
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 を使用すると、アプリケーションはサーバーに送信されたデータに対してチャンク転送エンコードを実行できます。 Transfer-Encoding ヘッダーが WinHttp 要求に存在する場合、WinHttpSendRequest の呼び出しの dwTotalLength パラメーターは WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH に設定され、アプリケーションは WinHttpWriteData への 1 つ以上の呼び出しでエンティティ本文を送信します。 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 |
| Library | Winhttp.lib |
| [DLL] | Winhttp.dll |
| 再頒布可能パッケージ | Windows XP および Windows 2000 では、WinHTTP 5.0 およびインターネット エクスプローラー 5.01 以降がインストールされています。 |
こちらもご覧ください
Microsoft Windows HTTP Services (WinHTTP) について
WINHTTP_STATUS_CALLBACK