WinHttpOpenRequest 関数 (winhttp.h)

  • [アーティクル]

WinHttpOpenRequest 関数は、HTTP 要求ハンドルを作成します。

構文

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

パラメーター

[in] hConnect

WinHttpConnect によって返される HTTP セッションへの HINTERNET 接続ハンドル。

[in] pwszVerb

要求で使用する HTTP 動詞 を含む文字列へのポインター。 このパラメーターが NULL の場合、関数は HTTP 動詞として GET を使用します。 メモ この文字列はすべて大文字にする必要があります。 多くのサーバーは HTTP 動詞を大文字と小文字を区別して扱います。インターネット エンジニアリング タスク フォース (IETF) のコメント要求 (RFC) では、これらの動詞のスペルは大文字のみを使用します。

[in] pwszObjectName

指定した HTTP 動詞のターゲット リソースの名前を含む文字列へのポインター。 これは通常、ファイル名、実行可能モジュール、または検索指定子です。

[in] pwszVersion

HTTP バージョンを含む文字列へのポインター。 このパラメーターが NULL の場合、関数は HTTP/1.1 を使用します。

[in] pwszReferrer

要求 pwszObjectName の URL が取得されたドキュメントの URL を指定する文字列へのポインター。 このパラメーターが WINHTTP_NO_REFERER に設定されている場合、参照ドキュメントは指定されません。

[in] ppwszAcceptTypes

クライアントが受け入れるメディアの種類を指定する文字列ポインターの null で終わる配列へのポインター。 このパラメーターが WINHTTP_DEFAULT_ACCEPT_TYPES に設定されている場合、クライアントで受け入れられる型はありません。 通常、サーバーは、クライアントが "text/*" 型のドキュメントのみを受け入れることを示す、受け入れ可能な型の欠如を処理します。つまり、テキスト ドキュメントのみであり、画像やその他のバイナリ ファイルはありません。 有効なメディアの種類の一覧については、IANA で定義されているメディアの種類に http://www.iana.org/assignments/media-types/関するページを参照してください。

[in] dwFlags

インターネット フラグ値を含む符号なし long 整数値。 これは、次の値のなかから 1 つまたは複数を指定できます。

値 意味
WINHTTP_FLAG_BYPASS_PROXY_CACHE
 このフラグは、 WINHTTP_FLAG_REFRESHと同じ動作を提供します。
WINHTTP_FLAG_ESCAPE_DISABLE
 pwszObjectName に渡された URL 内の安全でない文字は、エスケープ シーケンスに変換されません。
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
 pwszObjectName に渡される URL のクエリ コンポーネント内の安全でない文字は、エスケープ シーケンスに変換されません。
WINHTTP_FLAG_ESCAPE_PERCENT
 pwszObjectName に渡される文字列は、LPCWSTR から LPSTR に変換されます。 すべての安全でない文字は、パーセント記号を含むエスケープ シーケンスに変換されます。 既定では、パーセント記号を除くすべての安全でない文字はエスケープ シーケンスに変換されます。
WINHTTP_FLAG_NULL_CODEPAGE
 pwszObjectName に渡される文字列は、WCHAR で表される有効な ANSI 文字で構成されているものと見なされます。 安全でない文字に対してチェックは実行されません。

Windows 7: このオプションは廃止されました。
WINHTTP_FLAG_REFRESH
 キャッシュされたバージョンのリソースをプロキシ サーバーから送信するのではなく、要求を元のサーバーに転送する必要があることを示します。 このフラグを使用すると、"Pragma: no-cache" ヘッダーが要求ハンドルに追加されます。 HTTP/1.1 要求ヘッダーを作成するときに、"Cache-Control: no-cache" も追加されます。
WINHTTP_FLAG_SECURE
 安全なトランザクション セマンティクスを使用します。 これは、Secure Sockets Layer (SSL)/Transport Layer Security (TLS) の使用に変換されます。

戻り値

成功した場合は有効な HTTP 要求ハンドルを返し、成功しない場合は NULL を 返します。 拡張エラー情報については、 GetLastError を呼び出します。 返されるエラー コードは次のとおりです。

エラー コード 説明
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 指定されたハンドルの種類が、この操作に対して正しくありません。
ERROR_WINHTTP_INTERNAL_ERROR
 内部エラーが発生しました。
ERROR_WINHTTP_INVALID_URL
 URL が無効です。
ERROR_WINHTTP_OPERATION_CANCELLED
 通常、操作が完了する前に要求が操作されていたハンドルが閉じられたため、操作が取り消されました。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
 URL で、"http:" または "https:" 以外のスキームが指定されました。
ERROR_NOT_ENOUGH_MEMORY
 要求された操作を完了するのに十分なメモリが使用できませんでした。 (Windows エラー コード)

注釈

戻り値は成功または失敗を示します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

WinHttpOpenRequest 関数は、新しい HTTP 要求ハンドルを作成し、指定されたパラメーターをそのハンドルに格納します。 HTTP 要求ハンドルは、HTTP サーバーに送信する要求を保持し、要求の一部として送信されるすべての RFC822/MIME/HTTP ヘッダーを含みます。

pwszVerb が "HEAD" に設定されている場合、Content-Length ヘッダーは無視されます。

状態コールバック関数が WinHttpSetStatusCallback と共にインストールされている場合、 WINHTTP_CALLBACK_STATUS_HANDLE_CREATED 通知は 、WinHttpOpenRequest が要求ハンドルを作成したことを示します。

呼び出し元のアプリケーションで WinHttpOpenRequest によって返される HINTERNET ハンドルの使用が完了したら、WinHttpCloseHandle 関数を使用して閉じる必要があります。

メモ Windows XP と Windows 2000 については、WinHttp スタート ページの 「ランタイム要件 」セクションを参照してください。
 

例

この例では、 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 any errors.
    if (!bResults)
        printf( "Error %d has occurred.\n", GetLastError());

    // Close any 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 バージョン

WinHttpConnect

WinHttpOpen