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.
[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 that 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 is 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) |