ホーム › Networking.WinHttp › WinHttpGetProxyForUrlEx

WinHttpGetProxyForUrlEx

関数

指定URLのプロキシ情報を非同期で取得する。

DLLWINHTTP.dll呼出規約winapi対応OSwindows8.0

シグネチャ

// WINHTTP.dll
#include <windows.h>

DWORD WinHttpGetProxyForUrlEx(
    void* hResolver,
    LPCWSTR pcwszUrl,
    WINHTTP_AUTOPROXY_OPTIONS* pAutoProxyOptions,
    UINT_PTR pContext   // optional
);

パラメーター

名前	型	方向	説明
hResolver	void*	in	WinHttpCreateProxyResolver 関数によって返された WinHTTP リゾルバーハンドルです。
pcwszUrl	LPCWSTR	in	プロキシ情報を決定する対象の URL を含む、null 終端の Unicode 文字列へのポインターです。
pAutoProxyOptions	WINHTTP_AUTOPROXY_OPTIONS*	in	使用する自動プロキシオプションを指定する WINHTTP_AUTOPROXY_OPTIONS 構造体へのポインターです。
pContext	UINT_PTR	inoptional	完了コールバック関数に渡されるコンテキストデータです。

戻り値の型: DWORD

公式ドキュメント

指定された URL のプロキシデータを取得します。(WinHttpGetProxyForUrlEx)

戻り値

操作の結果を示すステータスコードです。

以下のコードが返される場合があります。	説明
ERROR_IO_PENDING	操作は非同期に継続中です。
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR	指定された URL のプロキシが見つからない場合に WinHttpGetProxyForUrlEx によって返されます。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT	プロキシ自動構成 (PAC) ファイル内のスクリプトコードの実行中にエラーが発生しました。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	指定されたハンドルの種類が、この操作に対して正しくありません。
ERROR_WINHTTP_INVALID_URL	URL が無効です。
ERROR_WINHTTP_OPERATION_CANCELLED	操作がキャンセルされました。通常、これは操作の完了前に、要求が実行されていたハンドルが閉じられたために発生します。
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT	PAC ファイルをダウンロードできませんでした。たとえば、PAC URL が参照するサーバーに到達できなかったか、サーバーが 404 NOT FOUND 応答を返した可能性があります。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	PAC ファイルの URL に、"http:" または "https:" 以外のスキームが指定されています。
ERROR_NOT_ENOUGH_MEMORY	要求された操作を完了するのに十分なメモリがありませんでした。(Windows エラーコード)

解説(Remarks)

この関数は、HTTP 要求のプロキシ設定を自動構成するための Web Proxy Auto-Discovery (WPAD) プロトコルを実装します。WPAD プロトコルは、指定されたターゲット URL に使用するプロキシサーバーを特定するスクリプトであるプロキシ自動構成 (PAC) ファイルをダウンロードします。PAC ファイルは通常、企業ネットワーク環境内の IT 部門によって展開されます。PAC ファイルの URL は明示的に指定することも、ローカルネットワーク上の PAC ファイルの場所を自動的に検出するよう WinHttpGetProxyForUrlEx に指示することもできます。

WinHttpGetProxyForUrlEx は、ECMAScript ベースの PAC ファイルのみをサポートします。

WinHttpGetProxyForUrlEx は、URL ごとに呼び出す必要があります。これは、PAC ファイルが URL ごとに異なるプロキシサーバーを返す可能性があるためです。これは、PAC ファイルにより、IT 部門がターゲット URL (lpcwszUrl パラメーターで指定) をプロキシサーバー配列内の特定のプロキシにマッピング (ハッシュ) することで、プロキシサーバーの負荷分散を実装できるため有用です。

WinHttpGetProxyForUrlEx は、pAutoProxyOptions 構造体の dwFlags メンバーで自動検出が指定されている場合に、自動プロキシ URL と自動プロキシスクリプトをキャッシュします。詳細については、自動プロキシキャッシュを参照してください。

WinHttpGetProxyForUrlEx は、WinHttpGetProxyForUrl では提供されない、完全に非同期かつキャンセル可能な API を提供します。また、WinHttpGetProxyForUrlEx は PAC スクリプトによって返された完全なプロキシリストをアプリケーションに提供するため、アプリケーションは "DIRECT" へのフェールオーバーをより適切に処理でき、必要に応じて SOCKS を理解できます。

WinHttpGetProxyForUrlEx は常に非同期に実行され、成功した場合は直ちに ERROR_IO_PENDING を返します。コールバックは、WinHttpOpen によって提供される hSession に対して WinHttpSetStatusCallback を呼び出すことで設定されます。あるいは、WinHttpCreateProxyResolver によって提供される hResolver に対して WinHttpSetStatusCallback を呼び出すことで、呼び出しごとに固有のコールバックを設定できます。

WinHttpSetStatusCallback は、WinHttpCreateProxyResolver の前に呼び出す必要があります。WinHttpSetStatusCallback を呼び出す際は、WINHTTP_CALLBACK_FLAG_REQUEST_ERROR | WINHTTP_CALLBACK_FLAG_GETPROXYFORURL_COMPLETE を使用してください。コールバックの使用方法については、WINHTTP_STATUS_CALLBACK を参照してください。

ステータス WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE のコールバックが返されると、アプリケーションは WinHttpGetProxyForUrlEx の発行に使用したリゾルバーハンドルに対して WinHttpGetProxyResult を呼び出して、その呼び出しの結果を受け取ることができます。

ERROR_IO_PENDING を返した後に呼び出しが失敗した場合は、WINHTTP_CALLBACK_STATUS_REQUEST_ERROR のコールバックが発行されます。

この関数は常にプロセス外で実行されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WINHTTP.dll
#include <windows.h>

DWORD WinHttpGetProxyForUrlEx(
    void* hResolver,
    LPCWSTR pcwszUrl,
    WINHTTP_AUTOPROXY_OPTIONS* pAutoProxyOptions,
    UINT_PTR pContext   // optional
);

[DllImport("WINHTTP.dll", ExactSpelling = true)]
static extern uint WinHttpGetProxyForUrlEx(
    IntPtr hResolver,   // void*
    [MarshalAs(UnmanagedType.LPWStr)] string pcwszUrl,   // LPCWSTR
    IntPtr pAutoProxyOptions,   // WINHTTP_AUTOPROXY_OPTIONS*
    UIntPtr pContext   // UINT_PTR optional
);

<DllImport("WINHTTP.dll", ExactSpelling:=True)>
Public Shared Function WinHttpGetProxyForUrlEx(
    hResolver As IntPtr,   ' void*
    <MarshalAs(UnmanagedType.LPWStr)> pcwszUrl As String,   ' LPCWSTR
    pAutoProxyOptions As IntPtr,   ' WINHTTP_AUTOPROXY_OPTIONS*
    pContext As UIntPtr   ' UINT_PTR optional
) As UInteger
End Function

' hResolver : void*
' pcwszUrl : LPCWSTR
' pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS*
' pContext : UINT_PTR optional
Declare PtrSafe Function WinHttpGetProxyForUrlEx Lib "winhttp" ( _
    ByVal hResolver As LongPtr, _
    ByVal pcwszUrl As LongPtr, _
    ByVal pAutoProxyOptions As LongPtr, _
    ByVal pContext As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinHttpGetProxyForUrlEx = ctypes.windll.winhttp.WinHttpGetProxyForUrlEx
WinHttpGetProxyForUrlEx.restype = wintypes.DWORD
WinHttpGetProxyForUrlEx.argtypes = [
    ctypes.POINTER(None),  # hResolver : void*
    wintypes.LPCWSTR,  # pcwszUrl : LPCWSTR
    ctypes.c_void_p,  # pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS*
    ctypes.c_size_t,  # pContext : UINT_PTR optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WINHTTP.dll')
WinHttpGetProxyForUrlEx = Fiddle::Function.new(
  lib['WinHttpGetProxyForUrlEx'],
  [
    Fiddle::TYPE_VOIDP,  # hResolver : void*
    Fiddle::TYPE_VOIDP,  # pcwszUrl : LPCWSTR
    Fiddle::TYPE_VOIDP,  # pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS*
    Fiddle::TYPE_UINTPTR_T,  # pContext : UINT_PTR optional
  ],
  -Fiddle::TYPE_INT)

#[link(name = "winhttp")]
extern "system" {
    fn WinHttpGetProxyForUrlEx(
        hResolver: *mut (),  // void*
        pcwszUrl: *const u16,  // LPCWSTR
        pAutoProxyOptions: *mut WINHTTP_AUTOPROXY_OPTIONS,  // WINHTTP_AUTOPROXY_OPTIONS*
        pContext: usize  // UINT_PTR optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WINHTTP.dll")]
public static extern uint WinHttpGetProxyForUrlEx(IntPtr hResolver, [MarshalAs(UnmanagedType.LPWStr)] string pcwszUrl, IntPtr pAutoProxyOptions, UIntPtr pContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WINHTTP_WinHttpGetProxyForUrlEx' -Namespace Win32 -PassThru
# $api::WinHttpGetProxyForUrlEx(hResolver, pcwszUrl, pAutoProxyOptions, pContext)

#uselib "WINHTTP.dll"
#func global WinHttpGetProxyForUrlEx "WinHttpGetProxyForUrlEx" sptr, sptr, sptr, sptr
; WinHttpGetProxyForUrlEx hResolver, pcwszUrl, varptr(pAutoProxyOptions), pContext   ; 戻り値は stat
; hResolver : void* -> "sptr"
; pcwszUrl : LPCWSTR -> "sptr"
; pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* -> "sptr"
; pContext : UINT_PTR optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WINHTTP.dll"
#cfunc global WinHttpGetProxyForUrlEx "WinHttpGetProxyForUrlEx" sptr, wstr, var, sptr
; res = WinHttpGetProxyForUrlEx(hResolver, pcwszUrl, pAutoProxyOptions, pContext)
; hResolver : void* -> "sptr"
; pcwszUrl : LPCWSTR -> "wstr"
; pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* -> "var"
; pContext : UINT_PTR optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WINHTTP.dll"
#cfunc global WinHttpGetProxyForUrlEx "WinHttpGetProxyForUrlEx" sptr, wstr, sptr, sptr
; res = WinHttpGetProxyForUrlEx(hResolver, pcwszUrl, varptr(pAutoProxyOptions), pContext)
; hResolver : void* -> "sptr"
; pcwszUrl : LPCWSTR -> "wstr"
; pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* -> "sptr"
; pContext : UINT_PTR optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。