Compartilhar via


Função OpenFileById (winbase.h)

Abre o arquivo que corresponde ao identificador especificado.

Sintaxe

HANDLE OpenFileById(
  [in]           HANDLE                hVolumeHint,
  [in]           LPFILE_ID_DESCRIPTOR  lpFileId,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwFlagsAndAttributes
);

Parâmetros

[in] hVolumeHint

Um identificador para qualquer arquivo em um volume ou compartilhamento no qual o arquivo a ser aberto é armazenado.

[in] lpFileId

Um ponteiro para um FILE_ID_DESCRIPTOR que identifica o arquivo a ser aberto.

[in] dwDesiredAccess

O acesso ao objeto . O acesso pode ser leitura, gravação ou ambos.

Para obter mais informações, consulte Segurança de arquivo e direitos de acesso. Não é possível solicitar um modo de acesso que entre em conflito com o modo de compartilhamento especificado em uma solicitação aberta que tenha um identificador aberto.

Se esse parâmetro for zero (0), o aplicativo poderá consultar atributos de arquivo e dispositivo sem acessar um dispositivo. Isso é útil para um aplicativo determinar o tamanho de uma unidade de disquete e os formatos aos quais ele dá suporte sem a necessidade de um disquete em uma unidade. Ele também pode ser usado para testar a existência de um arquivo ou diretório sem abri-los para acesso de leitura ou gravação.

[in] dwShareMode

O modo de compartilhamento de um objeto, que pode ser lido, gravado, ambos ou nenhum.

Não é possível solicitar um modo de compartilhamento que entre em conflito com o modo de acesso especificado em uma solicitação aberta que tenha um identificador aberto, pois isso resultaria na seguinte violação de compartilhamento: (ERROR_SHARING_VIOLATION). Para obter mais informações, consulte Como criar e abrir arquivos.

Se esse parâmetro for zero (0) e OpenFileById for bem-sucedido, o objeto não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador seja fechado. Para obter mais informações, confira a seção Comentários deste tópico.

As opções de compartilhamento permanecem em vigor até que você feche o identificador de um objeto .

Para permitir que um processo compartilhe um objeto enquanto outro processo tem o objeto aberto, use uma combinação de um ou mais dos valores a seguir para especificar o modo de acesso que eles podem solicitar para abrir o objeto.

Valor Significado
FILE_SHARE_DELETE
0x00000004
Habilita operações abertas subsequentes em um objeto para solicitar acesso de exclusão.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de exclusão.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de exclusão, a função falhará.

FILE_SHARE_READ
0x00000001
Habilita operações abertas subsequentes em um objeto para solicitar acesso de leitura.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de leitura.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de leitura, a função falhará.

FILE_SHARE_WRITE
0x00000002
Habilita operações abertas subsequentes em um objeto para solicitar acesso de gravação.

Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de gravação.

Se esse sinalizador não for especificado, mas o objeto tiver sido aberto para acesso de gravação ou tiver um mapeamento de arquivo com acesso de gravação, a função falhará.

[in, optional] lpSecurityAttributes

Reservado.

[in] dwFlagsAndAttributes

Os sinalizadores de arquivo.

Quando OpenFileById abre um arquivo, ele combina os sinalizadores de arquivo com atributos de arquivo existentes e ignora todos os atributos de arquivo fornecidos. Esse parâmetro pode incluir qualquer combinação dos sinalizadores a seguir.

Valor Significado
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Um arquivo está sendo aberto para uma operação de backup ou restauração. O sistema garante que o processo de chamada substitua as verificações de segurança de arquivo quando o processo tiver privilégios de SE_BACKUP_NAME e SE_RESTORE_NAME . Para obter mais informações, consulte Alterando privilégios em um token.

Você deve definir esse sinalizador para obter um identificador para um diretório. Um identificador de diretório pode ser passado para algumas funções em vez de um identificador de arquivo. Para obter mais informações, consulte Identificadores de diretório.

FILE_FLAG_NO_BUFFERING
0x20000000
O sistema abre um arquivo sem cache do sistema. Esse sinalizador não afeta o cache de disco rígido. Quando combinado com FILE_FLAG_OVERLAPPED, o sinalizador fornece desempenho máximo assíncrono, pois a E/S não depende das operações síncronas do gerenciador de memória. No entanto, algumas operações de E/S levam mais tempo, porque os dados não estão sendo mantidos no cache. Além disso, os metadados do arquivo ainda podem ser armazenados em cache. Para liberar os metadados para o disco, use a função FlushFileBuffers.

Um aplicativo deve atender a determinados requisitos ao trabalhar com arquivos abertos com FILE_FLAG_NO_BUFFERING:

  • O acesso ao arquivo deve começar em deslocamentos de bytes dentro de um arquivo que são múltiplos inteiros do tamanho do setor de volume.
  • O acesso ao arquivo deve ser para números de bytes que são múltiplos inteiros do tamanho do setor de volume. Por exemplo, se o tamanho do setor for de 512 bytes, um aplicativo poderá solicitar leituras e gravações de 512, 1024, 1536 ou 2048 bytes, mas não de 335, 981 ou 7171 bytes.
  • Os endereços de buffer para operações de leitura e gravação devem ser alinhados ao setor, o que significa alinhado em endereços na memória que são múltiplos inteiros do tamanho do setor de volume. Dependendo do disco, esse requisito pode não ser imposto.
Uma maneira de alinhar buffers em múltiplos inteiros do tamanho do setor de volume é usar VirtualAlloc para alocar os buffers. Ele aloca memória alinhada em endereços que são múltiplos inteiros do tamanho da página de memória do sistema operacional. Como os tamanhos da página de memória e do setor de volume são potências de 2, essa memória também é alinhada em endereços que são múltiplos inteiros de um tamanho de setor de volume. As páginas de memória têm tamanho de 4 a 8 KB; os setores são 512 bytes (discos rígidos) ou CD (2048 bytes) e, portanto, os setores de volume nunca podem ser maiores que as páginas de memória.

Um aplicativo pode determinar um tamanho de setor de volume chamando a função GetDiskFreeSpace .

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Os dados do arquivo são solicitados, mas devem continuar localizados no armazenamento remoto. Ele não deve ser transportado de volta para o armazenamento local. Esse sinalizador é usado por sistemas de armazenamento remoto.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
Quando esse sinalizador é usado, o processamento normal de ponto de nova análise não ocorre e OpenFileById tenta abrir o ponto de nova análise. Quando um arquivo é aberto, um identificador de arquivo é retornado, independentemente de o filtro que controla ou não o ponto de nova análise estar operacional. Esse sinalizador não pode ser usado com o sinalizador CREATE_ALWAYS . Se o arquivo não for um ponto de nova análise, esse sinalizador será ignorado.
FILE_FLAG_OVERLAPPED
0x40000000
O arquivo está sendo aberto ou criado para E/S assíncrona. Quando a operação for concluída, o evento especificado para a chamada na estrutura OVERLAPPED será definido como o estado sinalizado. Operações que levam um período significativo de tempo para processar ERROR_IO_PENDING de retorno.

Se esse sinalizador for especificado, o arquivo poderá ser usado para operações simultâneas de leitura e gravação. O sistema não mantém o ponteiro do arquivo, portanto, você deve passar a posição do arquivo para as funções de leitura e gravação na estrutura OVERLAPPED ou atualizar o ponteiro do arquivo.

Se esse sinalizador não for especificado, as operações de E/S serão serializadas, mesmo que as chamadas para as funções de leitura e gravação especifiquem uma estrutura OVERLAPPED .

FILE_FLAG_RANDOM_ACCESS
0x10000000
Um arquivo é acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivo.
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
Um arquivo é acessado sequencialmente do princípio ao fim. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. Se um aplicativo mover o ponteiro do arquivo para acesso aleatório, o cache ideal poderá não ocorrer. No entanto, a operação correta ainda é garantida.

Especificar esse sinalizador pode aumentar o desempenho de aplicativos que leem arquivos grandes usando acesso sequencial. Os ganhos de desempenho podem ser ainda mais perceptíveis para aplicativos que leem arquivos grandes principalmente sequencialmente, mas ocasionalmente ignoram pequenos intervalos de bytes.

FILE_FLAG_WRITE_THROUGH
0x80000000
O sistema grava em qualquer cache intermediário e vai diretamente para o disco.

Se FILE_FLAG_NO_BUFFERING também não for especificado, para que o cache do sistema esteja em vigor, os dados serão gravados no cache do sistema, mas serão liberados para o disco sem demora.

Se FILE_FLAG_NO_BUFFERING também for especificado, para que o cache do sistema não esteja em vigor, os dados serão imediatamente liberados para o disco sem passar pelo cache do sistema. O sistema operacional também solicita um write-through do cache de disco rígido para mídia persistente. No entanto, nem todo hardware dá suporte a essa funcionalidade de gravação.

Valor retornado

Se a função tiver êxito, o valor de retorno será um identificador aberto para um arquivo especificado.

Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Use a função CloseHandle para fechar um identificador de objeto que OpenFileById retorna.

Se você chamar OpenFileById em um arquivo que está pendente de exclusão como resultado de uma chamada anterior para DeleteFile, a função falhará. O sistema operacional atrasa a exclusão de arquivos até que todos os identificadores do arquivo sejam fechados. GetLastError retorna ERROR_ACCESS_DENIED.

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 Não
TFO (Failover transparente) do SMB 3.0 Não
SMB 3.0 com compartilhamentos de arquivos de expansão (SO) Não
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim

Requisitos

   
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winbase.h (incluir Windows.h)
Biblioteca Kernel32.lib; FileExtd.lib no Windows Server 2003 e Windows XP
DLL Kernel32.dll
Redistribuível SDK do Windows no Windows Server 2003 e Windows XP.

Confira também

ACCESS_MASK

CloseHandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

Funções de gerenciamento de arquivos

GetFileInformationByHandleEx

GetOverlappedResult

OVERLAPPED

OpenFile

ReadFile

WriteFile