Função OpenFile (winbase.h)

Artigo
08/27/2023

Cria, abre, reabre ou exclui um arquivo.

Nota Essa função tem funcionalidades limitadas e não é recomendada. Para desenvolvimento de novos aplicativos, use a função CreateFile .

Sintaxe

HFILE OpenFile(
  [in]  LPCSTR     lpFileName,
  [out] LPOFSTRUCT lpReOpenBuff,
  [in]  UINT       uStyle
);

Parâmetros

[in] lpFileName

O nome do arquivo.

A cadeia de caracteres deve consistir em caracteres do conjunto de caracteres do Windows de 8 bits. A função OpenFile não dá suporte a nomes de arquivo Unicode nem a abertura de pipes nomeados.

[out] lpReOpenBuff

Um ponteiro para a estrutura OFSTRUCT que recebe informações sobre um arquivo quando ele é aberto pela primeira vez.

A estrutura pode ser usada em chamadas subsequentes para a função OpenFile para ver um arquivo aberto.

A estrutura OFSTRUCT contém um membro de cadeia de caracteres de caminho com um comprimento limitado a OFS_MAXPATHNAME caracteres, que tem 128 caracteres. Por isso, você não pode usar a função OpenFile para abrir um arquivo com um comprimento de caminho que exceda 128 caracteres. A função CreateFile não tem essa limitação de comprimento do caminho.

[in] uStyle

A ação a ser tomada.

Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
OF_CANCEL 0x00000800	Ignorado. Para produzir uma caixa de diálogo que contém um botão Cancelar , use OF_PROMPT.
OF_CREATE 0x00001000	Cria um arquivo novo. Se o arquivo existir, ele será truncado para zero (0).
OF_DELETE 0x00000200	Exclui um arquivo.
OF_EXIST 0x00004000	Abre um arquivo e o fecha. Use isso para testar a existência de um arquivo.
OF_PARSE 0x00000100	Preenche a estrutura OFSTRUCT , mas não faz mais nada.
OF_PROMPT 0x00002000	Exibe uma caixa de diálogo se um arquivo solicitado não existir. Uma caixa de diálogo informa a um usuário que o sistema não pode encontrar um arquivo e que ele contém botões Repetir e Cancelar . O botão Cancelar orienta o OpenFile a retornar uma mensagem de erro não encontrada.
OF_READ 0x00000000	Abre um arquivo somente leitura.
OF_READWRITE 0x00000002	abre um arquivo com permissões de leitura/gravação.
OF_REOPEN 0x00008000	Abre um arquivo usando informações no buffer de reabertura.
OF_SHARE_COMPAT 0x00000000	Para sistemas de arquivos baseados em MS-DOS, abre um arquivo com modo de compatibilidade, permite que qualquer processo em um computador especificado abra o arquivo várias vezes. Outros esforços para abrir um arquivo com outros modos de compartilhamento falham. Esse sinalizador é mapeado para os sinalizadores FILE_SHARE_WRITE FILE_SHARE_READ\| da função CreateFile.
OF_SHARE_DENY_NONE 0x00000040	Abre um arquivo sem negar acesso de leitura ou gravação a outros processos. Em sistemas de arquivos baseados em MS-DOS, se o arquivo tiver sido aberto no modo de compatibilidade por qualquer outro processo, a função falhará. Esse sinalizador é mapeado para os sinalizadores FILE_SHARE_WRITE FILE_SHARE_READ\| da função CreateFile.
OF_SHARE_DENY_READ 0x00000030	Abre um arquivo e nega o acesso de leitura a outros processos. Em sistemas de arquivos baseados em MS-DOS, se o arquivo tiver sido aberto no modo de compatibilidade ou para acesso de leitura por qualquer outro processo, a função falhará. Esse sinalizador é mapeado para o sinalizador FILE_SHARE_WRITE da função CreateFile .
OF_SHARE_DENY_WRITE 0x00000020	Abre um arquivo e nega o acesso de gravação a outros processos. Em sistemas de arquivos baseados em MS-DOS, se um arquivo tiver sido aberto no modo de compatibilidade ou para acesso de gravação por qualquer outro processo, a função falhará. Esse sinalizador é mapeado para o sinalizador FILE_SHARE_READ da função CreateFile .
OF_SHARE_EXCLUSIVE 0x00000010	Abre um arquivo com modo exclusivo e nega o acesso de leitura/gravação a outros processos. Se um arquivo tiver sido aberto em qualquer outro modo para acesso de leitura/gravação, mesmo pelo processo atual, a função falhará.
OF_VERIFY	Verifica se a data e a hora de um arquivo são iguais às de quando ele foi aberto anteriormente. Isso é útil como uma marcar extra para arquivos somente leitura.
OF_WRITE 0x00000001	abre um arquivo para acesso somente gravação.

Valor retornado

Se a função for bem-sucedida, o valor retornado especificará um identificador de arquivo a ser usado ao executar a E/S do arquivo. Para fechar o arquivo, chame a função CloseHandle usando esse identificador.

Se a função falhar, o valor retornado será HFILE_ERROR. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se o parâmetro lpFileName especificar apenas um nome de arquivo e uma extensão, essa função procurará um arquivo correspondente nos seguintes diretórios e a ordem mostrada:

O diretório em que um aplicativo é carregado.
O diretório atual.
O diretório do sistema Windows.
Use a função GetSystemDirectory para obter o caminho desse diretório.
O diretório do sistema Windows de 16 bits.
Não há uma função que recupere o caminho desse diretório, mas ela é pesquisada.
O diretório do Windows.
Use a função GetWindowsDirectory para obter o caminho desse diretório.
Os diretórios listados na variável de ambiente PATH.

O parâmetro lpFileName não pode conter caracteres curinga.

A função OpenFile não dá suporte ao sinalizador OF_SEARCH que a função OpenFile do Windows de 16 bits dá suporte. O sinalizador OF_SEARCH orienta o sistema a pesquisar um arquivo correspondente mesmo quando um nome de arquivo inclui um caminho completo. Use a função SearchPath para pesquisar um arquivo.

Uma violação de compartilhamento ocorrerá se for feita uma tentativa de abrir um arquivo ou diretório para exclusão em um computador remoto quando o valor do parâmetro uStyle for o sinalizador de acesso OF_DELETE OU'ed com qualquer outro sinalizador de acesso e o arquivo ou diretório remoto não tiver sido aberto com FILE_SHARE_DELETE acesso de compartilhamento. Para evitar a violação de compartilhamento nesse cenário, abra o arquivo ou diretório remoto com OF_DELETE acesso somente ou chame DeleteFile sem primeiro abrir o arquivo ou diretório para exclusão.

No Windows 8 e Windows Server 2012, 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	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

CsvFs fará E/S redirecionada em caso de arquivos compactados.

Requisitos


Cliente mínimo com suporte	Windows XP [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 (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll