Backs up a file or directory, including the security information
#include <WinAPIFiles.au3>
_WinAPI_BackupRead ( $hFile, $pBuffer, $iLength, ByRef $iBytes, ByRef $pContext [, $bSecurity = False] )
| $hFile | Handle to the file or directory to be backed up. To obtain the handle, call the _WinAPI_CreateFileEx() function. The SACLs are not read unless the file handle was created with the $ACCESS_SYSTEM_SECURITY access right. |
| $pBuffer | A pointer to a buffer that receives the data. |
| $iLength | The size of the buffer, in bytes. The buffer size must be greater than the size of the $tagWIN32_STREAM_ID structure. (see also MSDN for more information) |
| $iBytes | The number of bytes read. |
| $pContext | A pointer to an internal data structure used by this function to maintain context information during a backup operation. You must set this variable to 0 before the first call to _WinAPI_BackupRead() for the specified file or directory. The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change this variable or the variable that it points to between calls to _WinAPI_BackupRead(). |
| $bSecurity | [optional] Specifies whether the function will backup the access-control list (ACL) data, valid values: True - The ACL data will be backed up. False - The ACL data will be omitted (Default). |
| Success: | True. |
| Failure: | False, call _WinAPI_GetLastError() to get extended error information. |
The _WinAPI_BackupRead() is not intended for use in backing up files encrypted under the Encrypted File System (EFS).
If an error occurs during the data reading, the calling process can skip the bad data by calling the _WinAPI_BackupSeek() function.
When you are done using _WinAPI_BackupRead(), you must call _WinAPI_BackupReadAbort() function with the appropriate parameter to release the memory used by the internal data structure.
The file or directory should be restored using the _WinAPI_BackupWrite() function.
_WinAPI_BackupReadAbort, _WinAPI_BackupSeek, _WinAPI_BackupWrite
Search BackupRead in MSDN Library.
#include <MsgBoxConstants.au3>
#include <WinAPIFiles.au3>
#include <WinAPIHObj.au3>
#include <WinAPIMem.au3>
#include <WinAPIProc.au3>
#include <WinAPIShPath.au3>
Local Const $sFile = @ScriptFullPath
; Enable "SeBackupPrivilege" and "SeRestorePrivilege" privileges to perform backup and restore operation
Local $hToken = _WinAPI_OpenProcessToken(BitOR($TOKEN_ADJUST_PRIVILEGES, $TOKEN_QUERY))
Local $aAdjust, $aPrivileges[2] = [$SE_BACKUP_NAME, $SE_RESTORE_NAME]
_WinAPI_AdjustTokenPrivileges($hToken, $aPrivileges, $SE_PRIVILEGE_ENABLED, $aAdjust)
If @error Or @extended Then
MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', 'You do not have the required privileges.')
Exit
EndIf
; Create a memory buffer where to store the backup data
Local $iBytes = 4096 + FileGetSize($sFile)
Local $pBuffer = _WinAPI_CreateBuffer($iBytes)
; Back up a file, including the security information
Local $pContext = 0
Local $hFile = _WinAPI_CreateFileEx($sFile, $OPEN_EXISTING, $GENERIC_READ)
If Not _WinAPI_BackupRead($hFile, $pBuffer, $iBytes, $iBytes, $pContext, 1) Then
MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', 'Unable to back up a file.')
Exit
EndIf
_WinAPI_BackupReadAbort($pContext)
_WinAPI_CloseHandle($hFile)
; Restore a file (.bak) and the ACL data
$pContext = 0
$hFile = _WinAPI_CreateFileEx(_WinAPI_PathRenameExtension($sFile, '.bak'), $CREATE_ALWAYS, BitOR($GENERIC_WRITE, $WRITE_DAC, $WRITE_OWNER))
If Not _WinAPI_BackupWrite($hFile, $pBuffer, $iBytes, $iBytes, $pContext, 1) Then
MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', 'Unable to restore a file.')
Exit
EndIf
_WinAPI_BackupWriteAbort($pContext)
_WinAPI_CloseHandle($hFile)
; Free the used memory
_WinAPI_FreeMemory($pBuffer)
; Restore "SeBackupPrivilege" and "SeRestorePrivilege" privileges by default
_WinAPI_AdjustTokenPrivileges($hToken, $aAdjust, 0, $aAdjust)
_WinAPI_CloseHandle($hToken)