Export (0) Print
Expand All
Expand Minimize

OpenEncryptedFileRaw function

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.

ValueMeaning
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.

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 and Windows Server 2012, this function is supported by the following technologies.

TechnologySupported

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

Minimum supported client

Windows XP Professional [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinBase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

OpenEncryptedFileRawW (Unicode) and OpenEncryptedFileRawA (ANSI)

See also

BackupRead
BackupWrite
CloseEncryptedFileRaw
File Encryption
File Management Functions
ReadEncryptedFileRaw
WriteEncryptedFileRaw

 

 

Community Additions

ADD
Show:
© 2014 Microsoft