ホーム › NetworkManagement.IpHelper › GetBestInterfaceEx

GetBestInterfaceEx

関数

指定宛先ソケットアドレスへの最適なインターフェイス索引を取得する。

DLLIPHLPAPI.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

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

DWORD GetBestInterfaceEx(
    SOCKADDR* pDestAddr,
    DWORD* pdwBestIfIndex
);

パラメーター

名前	型	方向	説明
pDestAddr	SOCKADDR*	in	最適な経路を持つインターフェイスを取得する対象となる宛先 IPv6 または IPv4 アドレス。sockaddr 構造体の形式で指定します。
pdwBestIfIndex	DWORD*	out	pDestAddr で指定された IPv6 または IPv4 アドレスへの最適な経路を持つインターフェイスのインデックスへのポインター。

戻り値の型: DWORD

公式ドキュメント

GetBestInterfaceEx 関数は、指定された IPv4 または IPv6 アドレスへの最適な経路を持つインターフェイスのインデックスを取得します。

戻り値

関数が成功した場合、戻り値は NO_ERROR です。

関数が失敗した場合、戻り値は次のいずれかのエラーコードになります。

戻り値	説明
ERROR_CAN_NOT_COMPLETE	操作を完了できませんでした。
ERROR_INVALID_PARAMETER	無効なパラメーターが関数に渡されました。このエラーは、pdwBestIfIndex パラメーターに NULL ポインターが渡された場合、または pDestAddr もしくは pdwBestIfIndex パラメーターがアクセスできないメモリを指している場合に返されます。また、pdwBestIfIndex パラメーターが書き込みできないメモリを指している場合にも返されることがあります。
ERROR_NOT_SUPPORTED	要求はサポートされていません。このエラーは、ローカルコンピューターに IPv4 スタックが存在しないのに pDestAddr パラメーターに IPv4 アドレスが指定された場合、またはローカルコンピューターに IPv6 スタックが存在しないのに pDestAddr パラメーターに IPv6 アドレスが指定された場合に返されます。
その他	FormatMessage 関数を使用して、返されたエラーに対応するメッセージ文字列を取得してください。

解説(Remarks)

GetBestInterfaceEx 関数は、IPv4 アドレスと IPv6 アドレスのどちらにも使用できる点で GetBestInterface 関数と異なります。

pDestAddr パラメーターが指す sockaddr 構造体の Family メンバーには、次のいずれかの値を設定する必要があります: AF_INET または AF_INET6。

Windows Vista 以降では、pdwBestIfIndex パラメーターは IP Helper によって内部的に NET_IFINDEX データ型へのポインターとして扱われます。

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

各言語での呼び出し定義

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

DWORD GetBestInterfaceEx(
    SOCKADDR* pDestAddr,
    DWORD* pdwBestIfIndex
);

[DllImport("IPHLPAPI.dll", ExactSpelling = true)]
static extern uint GetBestInterfaceEx(
    IntPtr pDestAddr,   // SOCKADDR*
    out uint pdwBestIfIndex   // DWORD* out
);

<DllImport("IPHLPAPI.dll", ExactSpelling:=True)>
Public Shared Function GetBestInterfaceEx(
    pDestAddr As IntPtr,   ' SOCKADDR*
    <Out> ByRef pdwBestIfIndex As UInteger   ' DWORD* out
) As UInteger
End Function

' pDestAddr : SOCKADDR*
' pdwBestIfIndex : DWORD* out
Declare PtrSafe Function GetBestInterfaceEx Lib "iphlpapi" ( _
    ByVal pDestAddr As LongPtr, _
    ByRef pdwBestIfIndex As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetBestInterfaceEx = ctypes.windll.iphlpapi.GetBestInterfaceEx
GetBestInterfaceEx.restype = wintypes.DWORD
GetBestInterfaceEx.argtypes = [
    ctypes.c_void_p,  # pDestAddr : SOCKADDR*
    ctypes.POINTER(wintypes.DWORD),  # pdwBestIfIndex : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('IPHLPAPI.dll')
GetBestInterfaceEx = Fiddle::Function.new(
  lib['GetBestInterfaceEx'],
  [
    Fiddle::TYPE_VOIDP,  # pDestAddr : SOCKADDR*
    Fiddle::TYPE_VOIDP,  # pdwBestIfIndex : DWORD* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "iphlpapi")]
extern "system" {
    fn GetBestInterfaceEx(
        pDestAddr: *mut SOCKADDR,  // SOCKADDR*
        pdwBestIfIndex: *mut u32  // DWORD* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("IPHLPAPI.dll")]
public static extern uint GetBestInterfaceEx(IntPtr pDestAddr, out uint pdwBestIfIndex);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_GetBestInterfaceEx' -Namespace Win32 -PassThru
# $api::GetBestInterfaceEx(pDestAddr, pdwBestIfIndex)

#uselib "IPHLPAPI.dll"
#func global GetBestInterfaceEx "GetBestInterfaceEx" sptr, sptr
; GetBestInterfaceEx varptr(pDestAddr), varptr(pdwBestIfIndex)   ; 戻り値は stat
; pDestAddr : SOCKADDR* -> "sptr"
; pdwBestIfIndex : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "IPHLPAPI.dll"
#cfunc global GetBestInterfaceEx "GetBestInterfaceEx" var, var
; res = GetBestInterfaceEx(pDestAddr, pdwBestIfIndex)
; pDestAddr : SOCKADDR* -> "var"
; pdwBestIfIndex : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "IPHLPAPI.dll"
#cfunc global GetBestInterfaceEx "GetBestInterfaceEx" sptr, sptr
; res = GetBestInterfaceEx(varptr(pDestAddr), varptr(pdwBestIfIndex))
; pDestAddr : SOCKADDR* -> "sptr"
; pdwBestIfIndex : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。