Compartilhar via


Função ReOpenFile (winbase.h)

Reabre o objeto do sistema de arquivos especificado com diferentes direitos de acesso, modo de compartilhamento e sinalizadores.

Sintaxe

HANDLE ReOpenFile(
  [in] HANDLE hOriginalFile,
  [in] DWORD  dwDesiredAccess,
  [in] DWORD  dwShareMode,
  [in] DWORD  dwFlagsAndAttributes
);

Parâmetros

[in] hOriginalFile

Um identificador para o objeto a ser reaberto. O objeto deve ter sido criado pela função CreateFile .

[in] dwDesiredAccess

O acesso necessário ao objeto . Para obter uma lista de valores, consulte Segurança de Arquivos 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 anterior cujo identificador ainda está aberto.

Se esse parâmetro for zero (0), o aplicativo poderá consultar atributos de dispositivo sem acessar o dispositivo. Isso será útil se um aplicativo quiser determinar o tamanho de uma unidade de disquete e os formatos aos quais ele dá suporte sem a necessidade de um disquete na unidade.

[in] dwShareMode

O modo de compartilhamento do objeto . Não é possível solicitar um modo de compartilhamento que entre em conflito com o modo de acesso especificado em uma solicitação aberta anterior cujo identificador ainda está aberto.

Se esse parâmetro for zero (0) e CreateFile for bem-sucedido, o objeto não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador seja fechado.

Para permitir que outros processos compartilhem o objeto enquanto o processo o tem aberto, use uma combinação de um ou mais dos valores a seguir para especificar o tipo de acesso que eles podem solicitar quando abrirem o objeto. Essas opções de compartilhamento permanecem em vigor até que você feche o identificador do objeto.

Valor Significado
FILE_SHARE_DELETE
0x00000004
Habilita operações abertas subsequentes no 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 o objeto já tiver sido aberto com acesso de exclusão, o modo de compartilhamento deverá incluir esse sinalizador.

FILE_SHARE_READ
0x00000001
Permite que as operações abertas subsequentes no objeto solicitem acesso de leitura. Caso contrário, outros processos não poderão abrir o objeto se solicitarem acesso de leitura.

Se o objeto já tiver sido aberto com acesso de leitura, o modo de compartilhamento deverá incluir esse sinalizador.

FILE_SHARE_WRITE
0x00000002
Habilita operações abertas subsequentes no 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 o objeto já tiver sido aberto com acesso de gravação, o modo de compartilhamento deverá incluir esse sinalizador.

[in] dwFlagsAndAttributes

Os sinalizadores de arquivo. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Indica que o arquivo está sendo aberto ou criado 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, desde que tenha os privilégios SE_BACKUP_NAME e SE_RESTORE_NAME . Para obter mais informações, consulte Alterando privilégios em um token.

Você também pode definir esse sinalizador para obter um identificador para um diretório. Quando indicado, um identificador de diretório pode ser passado para algumas funções no lugar de um identificador de arquivo.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
Indica que o sistema operacional deve excluir o arquivo imediatamente depois que todos os seus identificadores tiverem sido fechados, não apenas o identificador especificado, mas também quaisquer outros identificadores abertos ou duplicados.

As solicitações abertas subsequentes para o arquivo falham, a menos que FILE_SHARE_DELETE seja usado.

FILE_FLAG_NO_BUFFERING
0x20000000
Instrui o sistema a abrir o arquivo sem buffer ou cache intermediário. 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, pois os dados não estão sendo mantidos no cache.

Um aplicativo deve atender a requisitos específicos ao trabalhar com arquivos abertos com FILE_FLAG_NO_BUFFERING:

  • O acesso ao arquivo deve começar em deslocamentos de bytes dentro do 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 (alinhados 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
Indica que os dados do arquivo são solicitados, mas devem continuar residindo no armazenamento remoto. Ele não deve ser transportado de volta para o armazenamento local. Esse sinalizador destina-se ao uso 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 ReOpenFile 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
Instrui o sistema a inicializar o objeto, de modo que as operações que levam um período significativo de tempo para processar o retorno ERROR_IO_PENDING. Quando a operação é concluída, o evento especificado é definido como o estado sinalizado.

Quando você especifica FILE_FLAG_OVERLAPPED, as funções de leitura e gravação do arquivo devem especificar uma estrutura OVERLAPPED . Ou seja, quando FILE_FLAG_OVERLAPPED é especificado, um aplicativo deve executar leitura e gravação sobrepostas.

Quando FILE_FLAG_OVERLAPPED é especificado, o sistema não mantém o ponteiro do arquivo. A posição do arquivo deve ser passada como parte do parâmetro lpOverlapped (apontando para uma estrutura OVERLAPPED ) para as funções de leitura e gravação do arquivo.

Esse sinalizador também permite que mais de uma operação seja executada simultaneamente com o identificador (uma operação simultânea de leitura e gravação, por exemplo).

FILE_FLAG_POSIX_SEMANTICS
0x01000000
Indica que o arquivo deve ser acessado de acordo com as regras POSIX. Isso inclui permitir vários arquivos com nomes, diferentes apenas no caso, para sistemas de arquivos que dão suporte a essa nomenclatura. Tenha cuidado ao usar essa opção porque os arquivos criados com esse sinalizador podem não estar acessíveis por aplicativos escritos para MS-DOS ou Windows de 16 bits.
FILE_FLAG_RANDOM_ACCESS
0x10000000
Indica que o arquivo é acessado aleatoriamente. O sistema pode usar isso como uma dica para otimizar o cache de arquivo.
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
Indica que o arquivo deve ser acessado sequencialmente do começo ao fim. O sistema pode usar isso como uma dica para otimizar o cache de arquivo. Se um aplicativo move o ponteiro do arquivo para acesso aleatório, poderá não ocorrer cache ideal; no entanto, a operação correta ainda é garantida.

Especificar esse sinalizador pode aumentar o desempenho para 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
Instrui o sistema a gravar em qualquer cache intermediário e ir diretamente para o disco. O sistema ainda pode armazenar em cache operações de gravação, mas não pode liberá-las lentamente.
 

Se o identificador representar o lado do cliente de um pipe nomeado, o parâmetro dwFlags também poderá conter informações de Qualidade de Serviço de Segurança. Para obter mais informações, consulte Níveis de representação. Quando o aplicativo de chamada especifica o sinalizador SECURITY_SQOS_PRESENT , o parâmetro dwFlags pode conter um ou mais dos valores a seguir.

Valor Significado
SECURITY_ANONYMOUS
Represente o cliente no nível de representação anônimo.
SECURITY_CONTEXT_TRACKING
O modo de acompanhamento de segurança é dinâmico. Se esse sinalizador não for especificado, o modo de controle de segurança será estático.
SECURITY_DELEGATION
Represente o cliente no nível de representação delegação.
SECURITY_EFFECTIVE_ONLY
Somente os aspectos habilitados do contexto de segurança do cliente estão disponíveis para o servidor. Se você não especificar esse sinalizador, todos os aspectos do contexto de segurança do cliente estarão disponíveis.

Isso permite que o cliente limite os grupos e privilégios que um servidor pode usar ao representar o cliente.

SECURITY_IDENTIFICATION
Represente o cliente no nível de representação de identificação.
SECURITY_IMPERSONATION
Represente o cliente no nível de representação de representação.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador aberto para o 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

O parâmetro dwFlags não pode conter nenhum dos sinalizadores de atributo de arquivo (FILE_ATTRIBUTE_*). Eles só podem ser especificados quando o arquivo é criado.

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

Requisitos

   
Cliente mínimo com suporte Windows Vista [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

Confira também

CreateFile

Funções de gerenciamento de arquivos