OpenEncryptedFileRaw function (Windows)

Switch View :

ScriptFree

OpenEncryptedFileRaw function

Applies to: desktop apps only

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 WINAPI OpenEncryptedFileRaw(
  __in   LPCTSTR lpFileName,
  __in   ULONG ulFlags,
  __out  PVOID *pvContext
);

Parameters

lpFileName [in]

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

ulFlags [in]

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.

pvContext [out]

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.

The BackupRead and BackupWrite functions handle backup and restore of unencrypted files.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Header	WinBase.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll
Unicode and ANSI names	OpenEncryptedFileRawW (Unicode) and OpenEncryptedFileRawA (ANSI)