ホーム › NetworkManagement.WNet › MultinetGetConnectionPerformanceA

MultinetGetConnectionPerformanceA

関数

ネットワーク接続の性能情報を取得する(ANSI版)。

DLLMPR.dll文字セットANSI (-A)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// MPR.dll  (ANSI / -A)
#include <windows.h>

DWORD MultinetGetConnectionPerformanceA(
    NETRESOURCEA* lpNetResource,
    NETCONNECTINFOSTRUCT* lpNetConnectInfoStruct
);

パラメーター

名前

型

方向

説明

lpNetResource

NETRESOURCEA*

ネットワークリソースを指定する NETRESOURCE 構造体へのポインター。このコンテキストでは、次のメンバーが特別な意味を持ちます。

メンバー	意味
lpLocalName	照会対象のネットワークリソースにリダイレクトされている、"F:" や "LPT1" などのローカルデバイスを指定するバッファーへのポインター。このメンバーが NULL または空文字列の場合、ネットワークリソースは lpRemoteName メンバーで指定します。このフラグがローカルデバイスを指定している場合、lpRemoteName は無視されます。
lpRemoteName	照会するネットワークリソースへのポインター。そのリソースには、現在接続が確立されている必要があります。たとえば、リソースがファイルサーバー上のファイルである場合、そのファイルを開いておくことで接続が確保されます。
lpProvider	通常は NULL に設定しますが、リソースが存在するネットワークが分かっている場合は、リソースの所有者 (プロバイダー) へのポインターを指定できます。 lpProvider メンバーが NULL でない場合、システムは指定された名前のネットワークに関する情報のみを返そうとします。

lpNetConnectInfoStruct

NETCONNECTINFOSTRUCT*

out

データを受け取る NETCONNECTINFOSTRUCT 構造体へのポインター。

戻り値の型: DWORD

公式ドキュメント

ネットワークリソースへのアクセスに使用される接続について、予想されるパフォーマンスに関する情報を返します。(ANSI)

戻り値

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

関数が失敗した場合、戻り値はシステムエラーコードであり、たとえば次のいずれかの値になります。

戻り値	説明
ERROR_NOT_SUPPORTED	ネットワークリソースがこの情報を提供していません。
ERROR_NOT_CONNECTED	lpNetResource パラメーターが指す NETRESOURCE 構造体の lpLocalName メンバーがリダイレクトされたデバイスを指定していないか、lpRemoteName メンバーが現在接続されているリソースの名前を指定していません。
ERROR_NO_NET_OR_BAD_PATH	ネットワークコンポーネントが開始されていないか、指定されたリソース名が認識されないため、操作を完了できませんでした。
ERROR_BAD_DEVICE	lpLocalName メンバーで指定されたローカルデバイスが無効です。
ERROR_BAD_NET_NAME	ネットワーク名が見つかりません。このエラーは、lpNetResource パラメーターが指す NETRESOURCE 構造体の lpLocalName メンバーが NULL であり、かつ lpNetResource が指す NETRESOURCE 構造体の lpRemoteName メンバーも NULL であるか、どのネットワークでも認識できなかった場合に返されます。
ERROR_INVALID_ADDRESS	無効なアドレスにアクセスしようとしました。このエラーは、lpNetResource または lpNetConnectInfoStruct パラメーターが NULL であった場合に返されます。
ERROR_INVALID_PARAMETER	不正なパラメーターが渡されました。このエラーは、lpNetConnectInfoStruct パラメーターが、cbStructure メンバーに適切な構造体サイズが設定された NETCONNECTINFOSTRUCT 構造体を指していない場合に返されます。
ERROR_NO_NETWORK	ネットワークが利用できません。
ERROR_EXTENDED_ERROR	ネットワーク固有のエラーが発生しました。エラーの説明を取得するには、 WNetGetLastError を呼び出します。

解説(Remarks)

MultinetGetConnectionPerformance 関数は、情報を NETCONNECTINFOSTRUCT 構造体に格納して返します。

MultinetGetConnectionPerformance 関数が返す情報は推定値にすぎません。ネットワークのトラフィックやルーティングによって、返される結果の精度が左右されることがあります。

MultinetGetConnectionPerformance 関数を使用して情報を要求できるのは、ネットワークリソースにリダイレクトされているローカルデバイス、または現在接続が存在するネットワークリソースに限られる点に注意してください。

lpNetResource パラメーターが指す NETRESOURCE 構造体の lpRemoteName メンバーに UNC パスを指定する場合、lpRemoteName メンバーはファイル名ではなくディレクトリ名でなければなりません。

この関数の代表的な使い方は、ネットワークサーバー上のファイルを開き (これによりファイルへの接続が確保されます)、この関数を呼び出して、その結果をファイル I/O の管理方法を決定するために利用するというものです。たとえば、ファイル全体をクライアント上の一時ファイルに読み込むか、サーバー上のファイルに直接アクセスするかを判断できます。

メモ

winnetwk.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして MultinetGetConnectionPerformance を定義しています。このエンコーディング中立のエイリアスと、エンコーディング中立でないコードを混在させて使用すると、不一致が生じてコンパイルエラーや実行時エラーの原因になることがあります。詳細については、「関数プロトタイプの規則」を参照してください。

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

各言語での呼び出し定義

// MPR.dll  (ANSI / -A)
#include <windows.h>

DWORD MultinetGetConnectionPerformanceA(
    NETRESOURCEA* lpNetResource,
    NETCONNECTINFOSTRUCT* lpNetConnectInfoStruct
);

[DllImport("MPR.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint MultinetGetConnectionPerformanceA(
    IntPtr lpNetResource,   // NETRESOURCEA*
    IntPtr lpNetConnectInfoStruct   // NETCONNECTINFOSTRUCT* out
);

<DllImport("MPR.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function MultinetGetConnectionPerformanceA(
    lpNetResource As IntPtr,   ' NETRESOURCEA*
    lpNetConnectInfoStruct As IntPtr   ' NETCONNECTINFOSTRUCT* out
) As UInteger
End Function

' lpNetResource : NETRESOURCEA*
' lpNetConnectInfoStruct : NETCONNECTINFOSTRUCT* out
Declare PtrSafe Function MultinetGetConnectionPerformanceA Lib "mpr" ( _
    ByVal lpNetResource As LongPtr, _
    ByVal lpNetConnectInfoStruct As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

MultinetGetConnectionPerformanceA = ctypes.windll.mpr.MultinetGetConnectionPerformanceA
MultinetGetConnectionPerformanceA.restype = wintypes.DWORD
MultinetGetConnectionPerformanceA.argtypes = [
    ctypes.c_void_p,  # lpNetResource : NETRESOURCEA*
    ctypes.c_void_p,  # lpNetConnectInfoStruct : NETCONNECTINFOSTRUCT* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MPR.dll')
MultinetGetConnectionPerformanceA = Fiddle::Function.new(
  lib['MultinetGetConnectionPerformanceA'],
  [
    Fiddle::TYPE_VOIDP,  # lpNetResource : NETRESOURCEA*
    Fiddle::TYPE_VOIDP,  # lpNetConnectInfoStruct : NETCONNECTINFOSTRUCT* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "mpr")]
extern "system" {
    fn MultinetGetConnectionPerformanceA(
        lpNetResource: *mut NETRESOURCEA,  // NETRESOURCEA*
        lpNetConnectInfoStruct: *mut NETCONNECTINFOSTRUCT  // NETCONNECTINFOSTRUCT* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MPR.dll", CharSet = CharSet.Ansi)]
public static extern uint MultinetGetConnectionPerformanceA(IntPtr lpNetResource, IntPtr lpNetConnectInfoStruct);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MPR_MultinetGetConnectionPerformanceA' -Namespace Win32 -PassThru
# $api::MultinetGetConnectionPerformanceA(lpNetResource, lpNetConnectInfoStruct)

#uselib "MPR.dll"
#func global MultinetGetConnectionPerformanceA "MultinetGetConnectionPerformanceA" sptr, sptr
; MultinetGetConnectionPerformanceA varptr(lpNetResource), varptr(lpNetConnectInfoStruct)   ; 戻り値は stat
; lpNetResource : NETRESOURCEA* -> "sptr"
; lpNetConnectInfoStruct : NETCONNECTINFOSTRUCT* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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