Função SetFilePointerEx (fileapi.h)
Move o ponteiro do arquivo especificado.
Sintaxe
BOOL SetFilePointerEx(
[in] HANDLE hFile,
[in] LARGE_INTEGER liDistanceToMove,
[out, optional] PLARGE_INTEGER lpNewFilePointer,
[in] DWORD dwMoveMethod
);
Parâmetros
[in] hFile
Um manipulador para o arquivo. O identificador de arquivo deve ter sido criado com o direito de acesso GENERIC_READ ou GENERIC_WRITE . Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.
[in] liDistanceToMove
O número de bytes para mover o ponteiro do arquivo. Um valor positivo move o ponteiro para frente no arquivo e um valor negativo move o ponteiro do arquivo para trás.
[out, optional] lpNewFilePointer
Um ponteiro para uma variável para receber o novo ponteiro de arquivo. Se esse parâmetro for NULL, o novo ponteiro de arquivo não será retornado.
[in] dwMoveMethod
O ponto de partida para a movimentação do ponteiro do arquivo. Esse parâmetro pode usar um dos valores a seguir.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
O ponteiro de arquivo retornado por essa função não é usado para operações de leitura e gravação sobrepostas. Para especificar o deslocamento para operações sobrepostas, use os membros Offset e OffsetHigh da estrutura OVERLAPPED .
Você não pode usar a função SetFilePointerEx com um identificador para um dispositivo que não está em contato, como um pipe ou um dispositivo de comunicação. Para determinar o tipo de arquivo para hFile, use a função GetFileType .
Tenha cuidado ao definir o ponteiro do arquivo em um aplicativo multithreaded. Você deve sincronizar o acesso aos recursos compartilhados. Por exemplo, um aplicativo cujos threads compartilham um identificador de arquivo, atualizar o ponteiro do arquivo e ler do arquivo deve proteger essa sequência usando um objeto de seção crítico ou um objeto mutex. Para obter mais informações sobre esses objetos, consulte Objetos de Seção Crítica e Objetos Mutex.
Se o identificador hFile tiver sido aberto com o sinalizador FILE_FLAG_NO_BUFFERING definido, um aplicativo poderá mover o ponteiro do arquivo apenas para posições alinhadas ao setor. Uma posição alinhada ao setor é uma posição que é um número inteiro múltiplo do tamanho do setor do volume. Um aplicativo pode obter o tamanho do setor de um volume chamando a função GetDiskFreeSpace . Se um aplicativo chamar SetFilePointerEx com valores de distância para movimentação que resultam em uma posição que não esteja alinhada ao setor e um identificador aberto com FILE_FLAG_NO_BUFFERING, a função falhará e GetLastError retornará ERROR_INVALID_PARAMETER. Para obter informações adicionais, consulte Buffer de arquivos.
Observe que não é um erro definir o ponteiro do arquivo para uma posição além do final do arquivo. O tamanho do arquivo não aumenta até que você chame a função SetEndOfFile, WriteFile ou WriteFileEx . Uma operação de gravação aumenta o tamanho do arquivo para a posição do ponteiro do arquivo mais o tamanho do buffer gravado, o que resulta na inicialização de zero dos bytes intermediários.
Você pode usar SetFilePointerEx para determinar o comprimento de um arquivo. Para fazer isso, use FILE_END para dwMoveMethod e procure o local zero. O deslocamento de arquivo retornado é o comprimento do arquivo. No entanto, essa prática pode ter efeitos colaterais não intencionais, como falha ao salvar o ponteiro do arquivo atual para que o programa possa retornar a esse local. É mais simples e seguro usar a função GetFileSizeEx .
Você também pode usar SetFilePointerEx para consultar a posição atual do ponteiro do arquivo. Para fazer isso, especifique um método de movimentação de FILE_CURRENT e uma distância de zero.
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 XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | fileapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |