ホーム › Storage.FileSystem › GetFileBandwidthReservation

GetFileBandwidthReservation

関数

ファイルハンドルのI/O帯域幅予約情報を取得する。

DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

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

BOOL GetFileBandwidthReservation(
    HANDLE hFile,
    DWORD* lpPeriodMilliseconds,
    DWORD* lpBytesPerPeriod,
    BOOL* pDiscardable,
    DWORD* lpTransferSize,
    DWORD* lpNumOutstandingRequests
);

パラメーター

名前	型	方向	説明
hFile	HANDLE	in	ファイルへのハンドル。
lpPeriodMilliseconds	DWORD*	out	予約の期間（ミリ秒単位）を受け取る変数へのポインター。期間とは、I/O がカーネルに発行されてから、その I/O が完了すべき時点までの時間です。このハンドルに対して帯域幅が予約されていない場合は、このボリュームでサポートされる最小の予約期間が返されます。
lpBytesPerPeriod	DWORD*	out	ボリューム上で予約可能な、1 期間あたりの最大バイト数を受け取る変数へのポインター。このハンドルに対して帯域幅が予約されていない場合は、このボリュームでサポートされる 1 期間あたりの最大バイト数が返されます。
pDiscardable	BOOL*	out	ドライバーが期間内に I/O 操作を完了できない場合に、その I/O をエラーで完了させるべきときは TRUE。基盤となるサブシステムがこのような方法での失敗をサポートしていない場合は FALSE。
lpTransferSize	DWORD*	out	アプリケーションが発行する個々の I/O 要求の最小サイズ。すべての I/O 要求は TransferSize の倍数である必要があります。このハンドルに対して帯域幅が予約されていない場合は、このボリュームでサポートされる最小の転送サイズが返されます。
lpNumOutstandingRequests	DWORD*	out	オペレーティングシステムに対して未処理のままにできる TransferSize チャンクの数。

戻り値の型: BOOL

公式ドキュメント

指定したファイルが存在するボリュームの帯域幅予約プロパティを取得します。

戻り値

成功した場合は 0 以外、それ以外の場合は 0 を返します。

拡張エラー情報を取得するには、 GetLastError を呼び出します。

解説(Remarks)

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

テクノロジ	サポート
Server Message Block (SMB) 3.0 プロトコル	いいえ
SMB 3.0 トランスペアレントフェールオーバー (TFO)	いいえ
SMB 3.0 スケールアウトファイル共有 (SO)	いいえ
クラスター共有ボリュームファイルシステム (CsvFS)	いいえ
Resilient File System (ReFS)	はい

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

各言語での呼び出し定義

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

BOOL GetFileBandwidthReservation(
    HANDLE hFile,
    DWORD* lpPeriodMilliseconds,
    DWORD* lpBytesPerPeriod,
    BOOL* pDiscardable,
    DWORD* lpTransferSize,
    DWORD* lpNumOutstandingRequests
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool GetFileBandwidthReservation(
    IntPtr hFile,   // HANDLE
    out uint lpPeriodMilliseconds,   // DWORD* out
    out uint lpBytesPerPeriod,   // DWORD* out
    out bool pDiscardable,   // BOOL* out
    out uint lpTransferSize,   // DWORD* out
    out uint lpNumOutstandingRequests   // DWORD* out
);

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetFileBandwidthReservation(
    hFile As IntPtr,   ' HANDLE
    <Out> ByRef lpPeriodMilliseconds As UInteger,   ' DWORD* out
    <Out> ByRef lpBytesPerPeriod As UInteger,   ' DWORD* out
    <Out> ByRef pDiscardable As Boolean,   ' BOOL* out
    <Out> ByRef lpTransferSize As UInteger,   ' DWORD* out
    <Out> ByRef lpNumOutstandingRequests As UInteger   ' DWORD* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hFile : HANDLE
' lpPeriodMilliseconds : DWORD* out
' lpBytesPerPeriod : DWORD* out
' pDiscardable : BOOL* out
' lpTransferSize : DWORD* out
' lpNumOutstandingRequests : DWORD* out
Declare PtrSafe Function GetFileBandwidthReservation Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByRef lpPeriodMilliseconds As Long, _
    ByRef lpBytesPerPeriod As Long, _
    ByRef pDiscardable As Long, _
    ByRef lpTransferSize As Long, _
    ByRef lpNumOutstandingRequests As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetFileBandwidthReservation = ctypes.windll.kernel32.GetFileBandwidthReservation
GetFileBandwidthReservation.restype = wintypes.BOOL
GetFileBandwidthReservation.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    ctypes.POINTER(wintypes.DWORD),  # lpPeriodMilliseconds : DWORD* out
    ctypes.POINTER(wintypes.DWORD),  # lpBytesPerPeriod : DWORD* out
    ctypes.c_void_p,  # pDiscardable : BOOL* out
    ctypes.POINTER(wintypes.DWORD),  # lpTransferSize : DWORD* out
    ctypes.POINTER(wintypes.DWORD),  # lpNumOutstandingRequests : DWORD* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetFileBandwidthReservation = Fiddle::Function.new(
  lib['GetFileBandwidthReservation'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpPeriodMilliseconds : DWORD* out
    Fiddle::TYPE_VOIDP,  # lpBytesPerPeriod : DWORD* out
    Fiddle::TYPE_VOIDP,  # pDiscardable : BOOL* out
    Fiddle::TYPE_VOIDP,  # lpTransferSize : DWORD* out
    Fiddle::TYPE_VOIDP,  # lpNumOutstandingRequests : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn GetFileBandwidthReservation(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpPeriodMilliseconds: *mut u32,  // DWORD* out
        lpBytesPerPeriod: *mut u32,  // DWORD* out
        pDiscardable: *mut i32,  // BOOL* out
        lpTransferSize: *mut u32,  // DWORD* out
        lpNumOutstandingRequests: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true)]
public static extern bool GetFileBandwidthReservation(IntPtr hFile, out uint lpPeriodMilliseconds, out uint lpBytesPerPeriod, out bool pDiscardable, out uint lpTransferSize, out uint lpNumOutstandingRequests);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetFileBandwidthReservation' -Namespace Win32 -PassThru
# $api::GetFileBandwidthReservation(hFile, lpPeriodMilliseconds, lpBytesPerPeriod, pDiscardable, lpTransferSize, lpNumOutstandingRequests)

#uselib "KERNEL32.dll"
#func global GetFileBandwidthReservation "GetFileBandwidthReservation" sptr, sptr, sptr, sptr, sptr, sptr
; GetFileBandwidthReservation hFile, varptr(lpPeriodMilliseconds), varptr(lpBytesPerPeriod), varptr(pDiscardable), varptr(lpTransferSize), varptr(lpNumOutstandingRequests)   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; lpPeriodMilliseconds : DWORD* out -> "sptr"
; lpBytesPerPeriod : DWORD* out -> "sptr"
; pDiscardable : BOOL* out -> "sptr"
; lpTransferSize : DWORD* out -> "sptr"
; lpNumOutstandingRequests : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetFileBandwidthReservation "GetFileBandwidthReservation" sptr, var, var, var, var, var
; res = GetFileBandwidthReservation(hFile, lpPeriodMilliseconds, lpBytesPerPeriod, pDiscardable, lpTransferSize, lpNumOutstandingRequests)
; hFile : HANDLE -> "sptr"
; lpPeriodMilliseconds : DWORD* out -> "var"
; lpBytesPerPeriod : DWORD* out -> "var"
; pDiscardable : BOOL* out -> "var"
; lpTransferSize : DWORD* out -> "var"
; lpNumOutstandingRequests : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetFileBandwidthReservation "GetFileBandwidthReservation" sptr, sptr, sptr, sptr, sptr, sptr
; res = GetFileBandwidthReservation(hFile, varptr(lpPeriodMilliseconds), varptr(lpBytesPerPeriod), varptr(pDiscardable), varptr(lpTransferSize), varptr(lpNumOutstandingRequests))
; hFile : HANDLE -> "sptr"
; lpPeriodMilliseconds : DWORD* out -> "sptr"
; lpBytesPerPeriod : DWORD* out -> "sptr"
; pDiscardable : BOOL* out -> "sptr"
; lpTransferSize : DWORD* out -> "sptr"
; lpNumOutstandingRequests : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。