BackupWrite

関数

バックアップデータをファイルへ逐次書き込んで復元する。

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

シグネチャ

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

BOOL BackupWrite(
    HANDLE hFile,
    BYTE* lpBuffer,
    DWORD nNumberOfBytesToWrite,
    DWORD* lpNumberOfBytesWritten,
    BOOL bAbort,
    BOOL bProcessSecurity,
    void** lpContext
);

パラメーター

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

戻り値の型: BOOL

公式ドキュメント

BackupRead を使用してバックアップしたファイルまたはディレクトリを復元します。

戻り値

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

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

解説(Remarks)

この関数は、暗号化ファイルシステム(Encrypted File System) で暗号化されたファイルの復元には使用しません。その目的には WriteEncryptedFileRaw を使用してください。

バックアップメディアから読み取るデータは、 WIN32_STREAM_ID 構造体で区切られたサブストリームでなければなりません。

BACKUP_LINK ストリームタイプを使用すると、ハードリンクを持つファイルを復元できます。

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

各言語での呼び出し定義

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

BOOL BackupWrite(
    HANDLE hFile,
    BYTE* lpBuffer,
    DWORD nNumberOfBytesToWrite,
    DWORD* lpNumberOfBytesWritten,
    BOOL bAbort,
    BOOL bProcessSecurity,
    void** lpContext
);

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

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function BackupWrite(
    hFile As IntPtr,   ' HANDLE
    lpBuffer As IntPtr,   ' BYTE*
    nNumberOfBytesToWrite As UInteger,   ' DWORD
    <Out> ByRef lpNumberOfBytesWritten 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*
' nNumberOfBytesToWrite : DWORD
' lpNumberOfBytesWritten : DWORD* out
' bAbort : BOOL
' bProcessSecurity : BOOL
' lpContext : void** in/out
Declare PtrSafe Function BackupWrite Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpBuffer As LongPtr, _
    ByVal nNumberOfBytesToWrite As Long, _
    ByRef lpNumberOfBytesWritten 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

BackupWrite = ctypes.windll.kernel32.BackupWrite
BackupWrite.restype = wintypes.BOOL
BackupWrite.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    ctypes.POINTER(ctypes.c_ubyte),  # lpBuffer : BYTE*
    wintypes.DWORD,  # nNumberOfBytesToWrite : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpNumberOfBytesWritten : 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')
BackupWrite = Fiddle::Function.new(
  lib['BackupWrite'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpBuffer : BYTE*
    -Fiddle::TYPE_INT,  # nNumberOfBytesToWrite : DWORD
    Fiddle::TYPE_VOIDP,  # lpNumberOfBytesWritten : 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 BackupWrite(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpBuffer: *mut u8,  // BYTE*
        nNumberOfBytesToWrite: u32,  // DWORD
        lpNumberOfBytesWritten: *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 BackupWrite(IntPtr hFile, IntPtr lpBuffer, uint nNumberOfBytesToWrite, out uint lpNumberOfBytesWritten, bool bAbort, bool bProcessSecurity, IntPtr lpContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_BackupWrite' -Namespace Win32 -PassThru
# $api::BackupWrite(hFile, lpBuffer, nNumberOfBytesToWrite, lpNumberOfBytesWritten, bAbort, bProcessSecurity, lpContext)

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

出力引数:

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