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.
[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 |
|---|---|
|
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. |
|
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:
Um aplicativo pode determinar um tamanho de setor de volume chamando a função GetDiskFreeSpace . |
|
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. |
|
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. |
|
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 . |
|
Um arquivo é acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. |
|
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. |
|
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. |