WinHttpOpen 関数 (winhttp.h)

  • [アーティクル]

WinHttpOpen 関数は、アプリケーションの WinHTTP 関数の使用を初期化し、WinHTTP セッション ハンドルを返します。

構文

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

パラメーター

[in, optional] pszAgentW

WinHTTP 関数を呼び出すアプリケーションまたはエンティティの名前を含む文字列変数へのポインター。 この名前は、HTTP プロトコルの ユーザー エージェント として使用されます。

[in] dwAccessType

必要なアクセスの種類。 これには、次のいずれかの値を指定できます。

値 意味
WINHTTP_ACCESS_TYPE_NO_PROXY
 プロキシなしですべてのホスト名を直接解決します。
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
大事なこのオプションの使用は、Windows 8.1 以降では非推奨です。 代わりに WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY を使用してください。
 
レジストリから静的プロキシまたは直接構成を取得します。 WINHTTP_ACCESS_TYPE_DEFAULT_PROXY は、ブラウザー プロキシ設定を継承しません。

WinHTTP プロキシ構成は、次のいずれかのメカニズムによって設定されます。
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 プロキシ バイパス リストが指定され、解決される名前がプロキシをバイパスしない限り、プロキシに要求を渡します。 この場合、この関数は pwszProxyName と pwszProxyBypass に渡された値を使用します。
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 システムおよびユーザーごとのプロキシ設定 (インターネット エクスプローラー プロキシ構成を含む) を使用して、使用するプロキシ/プロキシを決定します。 複数のプロキシ間のフェールオーバー、インターフェイスごとに異なるプロキシ構成、認証を自動的に処理しようとします。 Windows 8.1 以降でサポートされています。

[in] pszProxyW

dwAccessType を WINHTTP_ACCESS_TYPE_NAMED_PROXY に設定してプロキシ アクセスを指定するときに使用するプロキシ サーバーの名前を含む文字列変数へのポインター。 WinHTTP 関数は、HTTP の CERN 型プロキシのみを認識します。 dwAccessType が WINHTTP_ACCESS_TYPE_NAMED_PROXY に設定されていない場合は、このパラメーターを WINHTTP_NO_PROXY_NAME に設定する必要があります。

[in] pszProxyBypassW

dwAccessType が WINHTTP_ACCESS_TYPE_NAMED_PROXY に設定されている場合にプロキシ経由でルーティングされない、オプションのセミコロン区切りのホスト名または IP アドレスの一覧、またはその両方を含む文字列変数へのポインター。 リストにはワイルドカード文字を含めることができます。 WinHttpOpen 関数はプロキシ バイパス リストとして使用するため、空の文字列を使用しないでください。 このパラメーターでリスト内の "<local>" マクロが唯一のエントリとして指定されている場合、この関数はピリオドを含まないホスト名をバイパスします。 dwAccessType が WINHTTP_ACCESS_TYPE_NAMED_PROXY に設定されていない場合は、このパラメーターを WINHTTP_NO_PROXY_BYPASS に設定する必要があります。

[in] dwFlags

この関数の動作に影響を与えるさまざまなオプションを示すフラグを含む符号なし long 整数値。 このパラメーターには、次の値を指定できます。

値 意味
WINHTTP_FLAG_ASYNC
 WinHTTP 関数を非同期的に使用します。 既定では、返された HINTERNET ハンドルを使用するすべての WinHTTP 関数が同期的に実行されます。 このフラグが設定されている場合、呼び出し元は WinHttpSetStatusCallback を使用してコールバック関数を指定する必要があります。
WINHTTP_FLAG_SECURE_DEFAULTS
 このフラグを設定すると、WinHttp では TLS 1.2 以降の使用が必要になります。 呼び出し元が WINHTTP_OPTION_SECURE_PROTOCOLS を設定して古い TLS バージョンを有効にしようとすると、 ERROR_ACCESS_DENIEDで失敗します。 さらに、TLS フォールバックは無効になります。 このフラグを設定すると、フラグWINHTTP_FLAG_ASYNCも設定されることに注意 してください。

戻り値

成功した場合は有効なセッション ハンドルを返し、それ以外の場合は NULL を 返します。 拡張エラー情報を取得するには、 GetLastError を呼び出します。 返されるエラー コードの中には、次のエラー コードがあります。

エラー コード 説明
ERROR_WINHTTP_INTERNAL_ERROR
 内部エラーが発生しました。
ERROR_NOT_ENOUGH_MEMORY
 要求された操作を完了するのに十分なメモリが使用できませんでした。 (Windows エラー コード)

注釈

非同期モードで WinHTTP を使用することを強くお勧めします (つまり、 WINHTTP_FLAG_ASYNC が WinHttpOpen で設定されている場合は、返される HINTERNET の使用が非同期になるようにします)。 戻り値は、成功または失敗を示します。 拡張エラー情報を取得するには、 GetLastError を呼び出します。

WinHttpOpen 関数は、アプリケーションによって呼び出される WinHTTP 関数の最初の関数です。 内部 WinHTTP データ構造を初期化し、アプリケーションからの今後の呼び出しに備えています。 アプリケーションで WinHTTP 関数の使用が完了したら、 WinHttpCloseHandle を呼び出して、セッション ハンドルと関連するリソースを解放する必要があります。

アプリケーションは WinHttpOpen に対して任意の数の呼び出しを行うことができますが、通常は 1 回の呼び出しで十分です。 WinHttpOpen を呼び出すたびに、新しいセッション コンテキストが開きます。 ユーザー データは複数のセッション コンテキスト間で共有されないため、複数のユーザーに代わって要求を行うアプリケーションでは、ユーザー固有の Cookie と認証状態を共有しないように、ユーザーごとに個別のセッションを作成する必要があります。 アプリケーションでは、 WinHttpOpen インスタンスごとに個別の動作を定義する必要があります。たとえば、それぞれに対して構成された異なるプロキシ サーバーなどです。

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

メモ Windows XP と Windows 2000 については、「 ランタイム要件」を参照してください。
 

例

次のコード例は、既定の接続タイムアウト値を取得する方法を示しています。


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

要件

   
サポートされている最小のクライアント 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 サービス (WinHTTP) について

WinHTTP バージョン

WinHttpCloseHandle