SetFilePointer

9/8/2008

Essa função move o ponteiro arquivo de um aberto arquivo. Uma versão RAPI dessa função existe chamado CeSetFilePointer (RAPI).

Syntax

DWORD SetFilePointer( 
  HANDLE hFile, 
  LONG lDistanceToMove, 
  PLONG lpDistanceToMoveHigh, 
  DWORD dwMoveMethod
); 

Parameters

• hFile
  [no] Identificador para o arquivo cujo ponteiro arquivo é a ser movido. O identificador de arquivo deve ter sido criado com acessar GENERIC_READ ou GENERIC_WRITE para o arquivo.

• lDistanceToMove
  Baixo-ordem 32 bits de um valor assinado que especifica o número de bytes para mover o ponteiro arquivo. Um valor positivo para esse parâmetro ** move o ponteiro arquivo ENC no arquivo, e um valor negativo move o ponteiro arquivo com versões anteriores. Não é possível usar um valor negativo para mover voltar passado além início de um arquivo.

  Se a pasta lpDistanceToMoveHigh ** parâmetro não está definido para NULL, lpDistanceToMoveHigh ** e ** Este parâmetro ** forma uma única 64-bit valor assinado que especifica a distância para mover.

• lpDistanceToMoveHigh
  Ponteiro para o alto-ordem 32 bits do assinado distância para mover.

  Se você não precisa de alta - ordem 32 bits, esse ponteiro deve ser definido como NULL.

  Quando não definido para NULL, este parâmetro também recebe o alto-ordem DWORD do novo valor do ponteiro de arquivo.

• dwMoveMethod
  [no] Iniciando apontar para mover o ponteiro arquivo. A seguinte tabela mostra os valores possíveis.

  Valor	Descrição
  FILE_BEGIN	Indica que a raiz é zero ou início do arquivo.
  FILE_CURRENT	Indica que a raiz é o atual valor do ponteiro de arquivo.
  FILE_END	Indica que a raiz é o atual fim - do - arquivo posição.

Return Value

O novo ponteiro arquivo indica sucesso. Um valor de 0xFFFFFFFF indica falha. Para informações de erro estendidas get, chamar GetLastError. No entanto, como 0xFFFFFFFF é um válido valor para o novo ponteiro arquivo, você deve verificar GetLastError Para determinar se um erro ocorreu. Se um erro ocorreu, GetLastError Retorna um valor Other Than NO_ERROR.

Se o novo ponteiro arquivo poderia ser um valor negativo, o função falhar, o ponteiro arquivo não é movido e a codificar retornado por GetLastError é ERROR_NEGATIVE_SEEK.

Remarks

Não é possível usar essa função com um identificador para um dispositivo nonseeking, such as um dispositivo de comunicação.

Você pode usar esta função para consulta o atual arquivo ponteiro posição. Para fazer isso, especificar um método mover do FILE_CURRENT e a uma distância de zero.

Tome cuidado quando configuração o ponteiro arquivo em um aplicativo com vários segmentos. De exemplo, um aplicativo cujo compartilhar segmentos um identificador de arquivo, atualização ponteiro de arquivo e ler a partir de arquivo devem proteger essa seqüência usando um crítico objeto seção ou objeto mutex. Para obter mais informações sobre esses objetos, consulte Processes and Threads.

Não é um erro para definir o ponteiro arquivo para uma posição além do fim do arquivo. O tamanho do arquivo não aumenta até você chamar o SetEndOfFile ou a função WriteFile. Um operação de gravação aumenta o tamanho do arquivo para a posição ponteiro arquivo juntamente com o tamanho da reserva gravada, deixando os bytes intermediárias não inicializado.

Se o valor de retorno é 0xFFFFFFFF, chamar GetLastError Para determinar se a função Êxito ou falha. O seguinte exemplo de código mostra como fazer isso:

// Try to move the hFile file pointer some distance.
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN);
if (dwPtr == 0xFFFFFFFF) // Test for failure.
{
   // Obtain the error code.
   dwError = GetLastError();
   // Resolve the failure.
} // End of error handler.

Requirements

Header	winbase.h
Library	coredll.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

File I/O Functions
GetFileSize
ReadFile
SetEndOfFile
WriteFile