BackupRead

関数

ファイルとそのストリームをバックアップ用に逐次読み取る。

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

シグネチャ

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

BOOL BackupRead(
    HANDLE hFile,
    BYTE* lpBuffer,
    DWORD nNumberOfBytesToRead,
    DWORD* lpNumberOfBytesRead,
    BOOL bAbort,
    BOOL bProcessSecurity,
    void** lpContext
);

パラメーター

名前	型	方向	説明
hFile	HANDLE	in	バックアップ対象のファイルまたはディレクトリへのハンドル。ハンドルを取得するには、CreateFile 関数を呼び出します。ファイルハンドルが ACCESS_SYSTEM_SECURITY アクセス権を指定して作成されていない限り、SACL は読み取られません。詳細については、ファイルのセキュリティとアクセス権を参照してください。ハンドルは同期(非オーバーラップ)である必要があります。つまり、CreateFile を呼び出す際に FILE_FLAG_OVERLAPPED フラグを設定してはなりません。この関数は受け取ったハンドルが同期であるかどうかを検証しないため、同期ハンドルに対してエラーコードを返すことはありませんが、非同期(オーバーラップ)ハンドルを指定して呼び出すと、デバッグが非常に困難な微妙なエラーが発生する可能性があります。 CreateFile が FILE_FLAG_NO_BUFFERING フラグを指定して呼び出された場合、BackupRead 関数は失敗することがあります。この場合、GetLastError 関数は ERROR_INVALID_PARAMETER を返します。
lpBuffer	BYTE*	out	データを受け取るバッファへのポインター。
nNumberOfBytesToRead	DWORD	in	バッファの長さ(バイト単位)。バッファのサイズは WIN32_STREAM_ID 構造体のサイズよりも大きくなければなりません。
lpNumberOfBytesRead	DWORD*	out	読み取られたバイト数を受け取る変数へのポインター。関数が 0 以外の値を返し、lpNumberOfBytesRead が指す変数が 0 の場合、ファイルハンドルに関連付けられたすべてのデータが読み取られたことを意味します。
bAbort	BOOL	in	ハンドルに対する BackupRead の使用を終了したかどうかを示します。ファイルをバックアップしている間は、このパラメーターに FALSE を指定します。BackupRead の使用が完了したら、このパラメーターに TRUE を指定し、適切な lpContext を渡して、BackupRead をもう一度呼び出す必要があります。bAbort が TRUE の場合は lpContext を渡す必要があり、その他のパラメーターはすべて無視されます。
bProcessSecurity	BOOL	in	この関数がファイルまたはディレクトリのアクセス制御リスト(ACL)データを復元するかどうかを示します。 bProcessSecurity が TRUE の場合、ACL データがバックアップされます。
lpContext	void**	inout	BackupRead がバックアップ操作中にコンテキスト情報を保持するために使用する内部データ構造へのポインターを受け取る変数へのポインター。指定したファイルまたはディレクトリに対して BackupRead を最初に呼び出す前に、lpContext が指す変数を NULL に設定する必要があります。関数はデータ構造用のメモリを割り当て、その構造を指すように変数を設定します。BackupRead の呼び出しの間に、lpContext またはそれが指す変数を変更してはなりません。データ構造で使用されているメモリを解放するには、バックアップ操作の完了時に bAbort パラメーターを TRUE に設定して BackupRead を呼び出します。

戻り値の型: BOOL

公式ドキュメント

セキュリティ情報を含めて、ファイルまたはディレクトリをバックアップします。

戻り値

関数が成功した場合、戻り値は 0 以外の値になります。

関数が失敗した場合、戻り値は 0 になり、I/O エラーが発生したことを示します。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

この関数は、Encrypted File System で暗号化されたファイルのバックアップに使用することを意図したものではありません。その目的には ReadEncryptedFileRaw を使用してください。

BackupRead がデータを読み取っている間にエラーが発生した場合、呼び出し側プロセスは BackupSeek 関数を呼び出すことで不良データをスキップできます。

ファイルまたはディレクトリは BackupWrite 関数を使用して復元する必要があります。

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

各言語での呼び出し定義

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

BOOL BackupRead(
    HANDLE hFile,
    BYTE* lpBuffer,
    DWORD nNumberOfBytesToRead,
    DWORD* lpNumberOfBytesRead,
    BOOL bAbort,
    BOOL bProcessSecurity,
    void** lpContext
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool BackupRead(
    IntPtr hFile,   // HANDLE
    IntPtr lpBuffer,   // BYTE* out
    uint nNumberOfBytesToRead,   // DWORD
    out uint lpNumberOfBytesRead,   // DWORD* out
    bool bAbort,   // BOOL
    bool bProcessSecurity,   // BOOL
    IntPtr lpContext   // void** in/out
);

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function BackupRead(
    hFile As IntPtr,   ' HANDLE
    lpBuffer As IntPtr,   ' BYTE* out
    nNumberOfBytesToRead As UInteger,   ' DWORD
    <Out> ByRef lpNumberOfBytesRead As UInteger,   ' DWORD* out
    bAbort As Boolean,   ' BOOL
    bProcessSecurity As Boolean,   ' BOOL
    lpContext As IntPtr   ' void** in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hFile : HANDLE
' lpBuffer : BYTE* out
' nNumberOfBytesToRead : DWORD
' lpNumberOfBytesRead : DWORD* out
' bAbort : BOOL
' bProcessSecurity : BOOL
' lpContext : void** in/out
Declare PtrSafe Function BackupRead Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpBuffer As LongPtr, _
    ByVal nNumberOfBytesToRead As Long, _
    ByRef lpNumberOfBytesRead As Long, _
    ByVal bAbort As Long, _
    ByVal bProcessSecurity As Long, _
    ByVal lpContext As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

BackupRead = ctypes.windll.kernel32.BackupRead
BackupRead.restype = wintypes.BOOL
BackupRead.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    ctypes.POINTER(ctypes.c_ubyte),  # lpBuffer : BYTE* out
    wintypes.DWORD,  # nNumberOfBytesToRead : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpNumberOfBytesRead : DWORD* out
    wintypes.BOOL,  # bAbort : BOOL
    wintypes.BOOL,  # bProcessSecurity : BOOL
    ctypes.c_void_p,  # lpContext : void** in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
BackupRead = Fiddle::Function.new(
  lib['BackupRead'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpBuffer : BYTE* out
    -Fiddle::TYPE_INT,  # nNumberOfBytesToRead : DWORD
    Fiddle::TYPE_VOIDP,  # lpNumberOfBytesRead : DWORD* out
    Fiddle::TYPE_INT,  # bAbort : BOOL
    Fiddle::TYPE_INT,  # bProcessSecurity : BOOL
    Fiddle::TYPE_VOIDP,  # lpContext : void** in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn BackupRead(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpBuffer: *mut u8,  // BYTE* out
        nNumberOfBytesToRead: u32,  // DWORD
        lpNumberOfBytesRead: *mut u32,  // DWORD* out
        bAbort: i32,  // BOOL
        bProcessSecurity: i32,  // BOOL
        lpContext: *mut *mut ()  // void** in/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 BackupRead(IntPtr hFile, IntPtr lpBuffer, uint nNumberOfBytesToRead, out uint lpNumberOfBytesRead, bool bAbort, bool bProcessSecurity, IntPtr lpContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_BackupRead' -Namespace Win32 -PassThru
# $api::BackupRead(hFile, lpBuffer, nNumberOfBytesToRead, lpNumberOfBytesRead, bAbort, bProcessSecurity, lpContext)

#uselib "KERNEL32.dll"
#func global BackupRead "BackupRead" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; BackupRead hFile, varptr(lpBuffer), nNumberOfBytesToRead, varptr(lpNumberOfBytesRead), bAbort, bProcessSecurity, lpContext   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; lpBuffer : BYTE* out -> "sptr"
; nNumberOfBytesToRead : DWORD -> "sptr"
; lpNumberOfBytesRead : DWORD* out -> "sptr"
; bAbort : BOOL -> "sptr"
; bProcessSecurity : BOOL -> "sptr"
; lpContext : void** in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global BackupRead "BackupRead" sptr, var, int, var, int, int, sptr
; res = BackupRead(hFile, lpBuffer, nNumberOfBytesToRead, lpNumberOfBytesRead, bAbort, bProcessSecurity, lpContext)
; hFile : HANDLE -> "sptr"
; lpBuffer : BYTE* out -> "var"
; nNumberOfBytesToRead : DWORD -> "int"
; lpNumberOfBytesRead : DWORD* out -> "var"
; bAbort : BOOL -> "int"
; bProcessSecurity : BOOL -> "int"
; lpContext : void** in/out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global BackupRead "BackupRead" sptr, sptr, int, sptr, int, int, sptr
; res = BackupRead(hFile, varptr(lpBuffer), nNumberOfBytesToRead, varptr(lpNumberOfBytesRead), bAbort, bProcessSecurity, lpContext)
; hFile : HANDLE -> "sptr"
; lpBuffer : BYTE* out -> "sptr"
; nNumberOfBytesToRead : DWORD -> "int"
; lpNumberOfBytesRead : DWORD* out -> "sptr"
; bAbort : BOOL -> "int"
; bProcessSecurity : BOOL -> "int"
; lpContext : void** in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。