ReadEncryptedFileRaw function (winbase.h)

Backs up (export) encrypted files. This is one of a group of Encrypted File System (EFS) functions that is intended to implement backup and restore functionality, while maintaining files in their encrypted state.

Syntax

DWORD ReadEncryptedFileRaw(
  [in]           PFE_EXPORT_FUNC pfExportCallback,
  [in, optional] PVOID           pvCallbackContext,
  [in]           PVOID           pvContext
);

Parameters

[in] pfExportCallback

A pointer to the export callback function. The system calls the callback function multiple times, each time passing a block of the file's data to the callback function until the entire file has been read. For more information, see ExportCallback.

[in, optional] pvCallbackContext

A pointer to an application-defined and allocated context block. The system passes this pointer to the callback function as a parameter so that the callback function can have access to application-specific data. This can be a structure and can contain any data the application needs, such as the handle to the file that will contain the backup copy of the encrypted file.

[in] pvContext

A pointer to a system-defined context block. The context block is returned by the OpenEncryptedFileRaw function. Do not modify it.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, it returns a nonzero error code defined in WinError.h. You can use FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic text description of the error.

Remarks

The file being backed up is not decrypted; it is backed up in its encrypted state.

To back up an encrypted file, call OpenEncryptedFileRaw to open the file. Then call ReadEncryptedFileRaw, passing it the address of an application-defined export callback function. The system calls this callback function multiple times until the entire file's contents have been read and backed up. When the backup is complete, call CloseEncryptedFileRaw to free resources and close the file. See ExportCallback for details about how to declare the export callback function.

To restore an encrypted file, call OpenEncryptedFileRaw, specifying CREATE_FOR_IMPORT in the ulFlags parameter. Then call WriteEncryptedFileRaw, passing it the address of an application-defined import callback function. The system calls this callback function multiple times until the entire file's contents have been read and restored. When the restore is complete, call CloseEncryptedFileRaw to free resources and close the file. See ImportCallback for details about how to declare the import callback function.

This function is intended for the backup of only encrypted files; see BackupRead for backup of unencrypted files.

In Windows 8, Windows Server 2012, and later, this function is supported by the following technologies.

Technology Supported
Server Message Block (SMB) 3.0 protocol Yes
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 with Scale-out File Shares (SO) No
Cluster Shared Volume File System (CsvFS) No
Resilient File System (ReFS) No
 

SMB 3.0 does not support EFS on shares with continuous availability capability.

Requirements

Requirement Value
Minimum supported client Windows XP Professional [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header winbase.h (include Windows.h)
Library Advapi32.lib
DLL Advapi32.dll
API set ext-ms-win-advapi32-encryptedfile-l1-1-0 (introduced in Windows 8)

See also

BackupRead

CloseEncryptedFileRaw

File Encryption

File Management Functions

OpenEncryptedFileRaw

WriteEncryptedFileRaw