ホーム › Networking.WinHttp › WinHttpGetProxyForUrl

WinHttpGetProxyForUrl

関数

指定URLに使用すべきプロキシ情報を取得する。

DLLWINHTTP.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

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

BOOL WinHttpGetProxyForUrl(
    void* hSession,
    LPCWSTR lpcwszUrl,
    WINHTTP_AUTOPROXY_OPTIONS* pAutoProxyOptions,
    WINHTTP_PROXY_INFO* pProxyInfo
);

パラメーター

名前	型	方向	説明
hSession	void*	inout	WinHttpOpen 関数が返した WinHTTP セッションハンドルです。
lpcwszUrl	LPCWSTR	in	アプリケーションが送信しようとしている HTTP 要求の URL を格納する、null 終端された Unicode 文字列へのポインターです。
pAutoProxyOptions	WINHTTP_AUTOPROXY_OPTIONS*	inout	使用する自動プロキシオプションを指定する WINHTTP_AUTOPROXY_OPTIONS 構造体へのポインターです。
pProxyInfo	WINHTTP_PROXY_INFO*	inout	プロキシ設定を受け取る WINHTTP_PROXY_INFO 構造体へのポインターです。この構造体は、WINHTTP_OPTION_PROXY オプションを使用して要求ハンドルに適用されます。この構造体に格納されている lpszProxy 文字列と lpszProxyBypass 文字列は、(NULL でない場合) GlobalFree 関数を使用して解放してください。

戻り値の型: BOOL

公式ドキュメント

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

戻り値

関数が成功した場合、TRUE を返します。

関数が失敗した場合は FALSE を返します。拡張エラー情報を取得するには、 GetLastError を呼び出してください。

発生し得るエラーコードは次のとおりです。

エラーコード	説明
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR	指定した URL に対するプロキシが見つからない場合に WinHttpGetProxyForUrl が返します。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT	プロキシ自動構成 (PAC) ファイル内のスクリプトコードの実行中にエラーが発生しました。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	指定されたハンドルの種類が、この操作には適切ではありません。
ERROR_WINHTTP_INTERNAL_ERROR	内部エラーが発生しました。
ERROR_WINHTTP_INVALID_URL	URL が無効です。
ERROR_WINHTTP_LOGIN_FAILURE	ログインの試行に失敗しました。このエラーが発生した場合は、 WinHttpCloseHandle で要求ハンドルを閉じてください。このエラーを最初に発生させた関数を再試行する前に、新しい要求ハンドルを作成する必要があります。
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 プロキシ自動検出 (WPAD) プロトコルを実装します。WPAD プロトコルは、プロキシ自動構成 (PAC) ファイルをダウンロードします。このファイルは、特定のターゲット URL に使用するプロキシサーバーを識別するスクリプトです。PAC ファイルは通常、企業ネットワーク環境において IT 部門によって配置されます。PAC ファイルの URL は明示的に指定できるほか、WinHttpGetProxyForUrl にローカルネットワーク上の PAC ファイルの場所を自動的に検出するよう指示することもできます。

WinHttpGetProxyForUrl がサポートするのは、ECMAScript ベースの PAC ファイルのみです。

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

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

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

各言語での呼び出し定義

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

BOOL WinHttpGetProxyForUrl(
    void* hSession,
    LPCWSTR lpcwszUrl,
    WINHTTP_AUTOPROXY_OPTIONS* pAutoProxyOptions,
    WINHTTP_PROXY_INFO* pProxyInfo
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINHTTP.dll", SetLastError = true, ExactSpelling = true)]
static extern bool WinHttpGetProxyForUrl(
    IntPtr hSession,   // void* in/out
    [MarshalAs(UnmanagedType.LPWStr)] string lpcwszUrl,   // LPCWSTR
    IntPtr pAutoProxyOptions,   // WINHTTP_AUTOPROXY_OPTIONS* in/out
    IntPtr pProxyInfo   // WINHTTP_PROXY_INFO* in/out
);

<DllImport("WINHTTP.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function WinHttpGetProxyForUrl(
    hSession As IntPtr,   ' void* in/out
    <MarshalAs(UnmanagedType.LPWStr)> lpcwszUrl As String,   ' LPCWSTR
    pAutoProxyOptions As IntPtr,   ' WINHTTP_AUTOPROXY_OPTIONS* in/out
    pProxyInfo As IntPtr   ' WINHTTP_PROXY_INFO* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hSession : void* in/out
' lpcwszUrl : LPCWSTR
' pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* in/out
' pProxyInfo : WINHTTP_PROXY_INFO* in/out
Declare PtrSafe Function WinHttpGetProxyForUrl Lib "winhttp" ( _
    ByVal hSession As LongPtr, _
    ByVal lpcwszUrl As LongPtr, _
    ByVal pAutoProxyOptions As LongPtr, _
    ByVal pProxyInfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinHttpGetProxyForUrl = ctypes.windll.winhttp.WinHttpGetProxyForUrl
WinHttpGetProxyForUrl.restype = wintypes.BOOL
WinHttpGetProxyForUrl.argtypes = [
    ctypes.POINTER(None),  # hSession : void* in/out
    wintypes.LPCWSTR,  # lpcwszUrl : LPCWSTR
    ctypes.c_void_p,  # pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* in/out
    ctypes.c_void_p,  # pProxyInfo : WINHTTP_PROXY_INFO* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WINHTTP.dll')
WinHttpGetProxyForUrl = Fiddle::Function.new(
  lib['WinHttpGetProxyForUrl'],
  [
    Fiddle::TYPE_VOIDP,  # hSession : void* in/out
    Fiddle::TYPE_VOIDP,  # lpcwszUrl : LPCWSTR
    Fiddle::TYPE_VOIDP,  # pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* in/out
    Fiddle::TYPE_VOIDP,  # pProxyInfo : WINHTTP_PROXY_INFO* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winhttp")]
extern "system" {
    fn WinHttpGetProxyForUrl(
        hSession: *mut (),  // void* in/out
        lpcwszUrl: *const u16,  // LPCWSTR
        pAutoProxyOptions: *mut WINHTTP_AUTOPROXY_OPTIONS,  // WINHTTP_AUTOPROXY_OPTIONS* in/out
        pProxyInfo: *mut WINHTTP_PROXY_INFO  // WINHTTP_PROXY_INFO* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINHTTP.dll", SetLastError = true)]
public static extern bool WinHttpGetProxyForUrl(IntPtr hSession, [MarshalAs(UnmanagedType.LPWStr)] string lpcwszUrl, IntPtr pAutoProxyOptions, IntPtr pProxyInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WINHTTP_WinHttpGetProxyForUrl' -Namespace Win32 -PassThru
# $api::WinHttpGetProxyForUrl(hSession, lpcwszUrl, pAutoProxyOptions, pProxyInfo)

#uselib "WINHTTP.dll"
#func global WinHttpGetProxyForUrl "WinHttpGetProxyForUrl" sptr, sptr, sptr, sptr
; WinHttpGetProxyForUrl hSession, lpcwszUrl, varptr(pAutoProxyOptions), varptr(pProxyInfo)   ; 戻り値は stat
; hSession : void* in/out -> "sptr"
; lpcwszUrl : LPCWSTR -> "sptr"
; pAutoProxyOptions : WINHTTP_AUTOPROXY_OPTIONS* in/out -> "sptr"
; pProxyInfo : WINHTTP_PROXY_INFO* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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