Função OpenEncryptedFileRawA (winbase.h)

Artigo
08/27/2023

Abre um arquivo criptografado para fazer backup (exportar) ou restaurar (importar) o arquivo. Essa é uma das funções do EFS (Encrypted File System) que se destina a implementar a funcionalidade de backup e restauração, mantendo arquivos em seu estado criptografado.

Sintaxe

DWORD OpenEncryptedFileRawA(
  [in]  LPCSTR lpFileName,
  [in]  ULONG  ulFlags,
  [out] PVOID  *pvContext
);

Parâmetros

[in] lpFileName

O nome do arquivo a ser aberto. A cadeia de caracteres deve consistir em caracteres do conjunto de caracteres do Windows.

[in] ulFlags

A operação a ser executada. Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
0	Abra o arquivo para exportação (backup).
CREATE_FOR_IMPORT 1	O arquivo está sendo aberto para importação (restauração).
CREATE_FOR_DIR 2	Importar (restaurar) um diretório que contém arquivos criptografados. Isso deve ser combinado com um dos dois sinalizadores anteriores para indicar a operação.
OVERWRITE_HIDDEN 4	Substituir um arquivo oculto na importação.

[out] pvContext

O endereço de um bloco de contexto que deve ser apresentado em chamadas subsequentes para ReadEncryptedFileRaw, WriteEncryptedFileRaw ou CloseEncryptedFileRaw. Não modifique-a.

Retornar valor

Se a função for bem-sucedida, ela retornará ERROR_SUCCESS.

Se a função falhar, ela retornará um código de erro diferente de zero definido em WinError.h. Você pode usar FormatMessage com o sinalizador FORMAT_MESSAGE_FROM_SYSTEM para obter uma descrição de texto genérica do erro.

Comentários

O chamador deve ter acesso de leitura ou gravação ao arquivo ou deve ter o privilégio de backup SeBackupPrivilege no computador no qual os arquivos residem para que a chamada seja bem-sucedida.

Para fazer backup de um arquivo criptografado, chame OpenEncryptedFileRaw para abrir o arquivo e, em seguida, chame ReadEncryptedFileRaw. Quando o backup for concluído, chame CloseEncryptedFileRaw.

Para restaurar um arquivo criptografado, chame OpenEncryptedFileRaw, especificando CREATE_FOR_IMPORT no parâmetro ulFlags e, em seguida, chame WriteEncryptedFileRaw uma vez. Quando a operação for concluída, chame CloseEncryptedFileRaw.

OpenEncryptedFileRaw falhará se lpFileName exceder MAX_PATH caracteres ao abrir um arquivo criptografado em um computador remoto.

Se o chamador não tiver acesso à chave do arquivo, ele precisará de SeBackupPrivilege para exportar arquivos criptografados ou SeRestorePrivilege para importar arquivos criptografados.

As funções BackupRead e BackupWrite lidam com backup e restauração de arquivos não criptografados.

Em Windows 8, Windows Server 2012 e posteriores, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	No
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	No
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	No
ReFS (Sistema de Arquivos Resiliente)	No

O SMB 3.0 não dá suporte ao EFS em compartilhamentos com capacidade de disponibilidade contínua.

Observação

O cabeçalho winbase.h define OpenEncryptedFileRaw como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (incluir Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll
Conjunto de APIs	ext-ms-win-advapi32-encryptedfile-l1-1-0 (introduzido no Windows 8)