OpenEncryptedFileRawA function (winbase.h)

Opens an encrypted file in order to backup (export) or restore (import) the file. 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 OpenEncryptedFileRawA(
  [in]  LPCSTR lpFileName,
  [in]  ULONG  ulFlags,
  [out] PVOID  *pvContext
);

Parameters

[in] lpFileName

The name of the file to be opened. The string must consist of characters from the Windows character set.

[in] ulFlags

The operation to be performed. This parameter may be one of the following values.

Value Meaning
0
Open the file for export (backup).
CREATE_FOR_IMPORT
1
The file is being opened for import (restore).
CREATE_FOR_DIR
2
Import (restore) a directory containing encrypted files. This must be combined with one of the previous two flags to indicate the operation.
OVERWRITE_HIDDEN
4
Overwrite a hidden file on import.

[out] pvContext

The address of a context block that must be presented in subsequent calls to ReadEncryptedFileRaw, WriteEncryptedFileRaw, or CloseEncryptedFileRaw. Do not modify it.

Return value

If the function succeeds, it returns 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 caller must either have read or write access to the file, or it must have backup privilege SeBackupPrivilege on the machine on which the files reside in order for the call to succeed.

To back up an encrypted file, call OpenEncryptedFileRaw to open the file and then call ReadEncryptedFileRaw. When the backup is complete, call CloseEncryptedFileRaw.

To restore an encrypted file, call OpenEncryptedFileRaw, specifying CREATE_FOR_IMPORT in the ulFlags parameter, and then call WriteEncryptedFileRaw once. When the operation is completed, call CloseEncryptedFileRaw.

OpenEncryptedFileRaw fails if lpFileName exceeds MAX_PATH characters when opening an encrypted file on a remote machine.

If the caller does not have access to the key for the file, the caller needs SeBackupPrivilege to export encrypted files or SeRestorePrivilege to import encrypted files.

The BackupRead and BackupWrite functions handle backup and restore 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.

Note

The winbase.h header defines OpenEncryptedFileRaw as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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

BackupWrite

CloseEncryptedFileRaw

File Encryption

File Management Functions

ReadEncryptedFileRaw

WriteEncryptedFileRaw