Funzione SetFilePointerEx (fileapi.h)

Sposta il puntatore del file del file specificato.

Sintassi

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

Parametri

[in] hFile

Handle per il file. L'handle di file deve essere stato creato con il GENERIC_READ o GENERIC_WRITE diritto di accesso. Per altre informazioni, vedere Sicurezza file e diritti di accesso.

[in] liDistanceToMove

Numero di byte per spostare il puntatore del file. Un valore positivo sposta il puntatore in avanti nel file e un valore negativo sposta il puntatore di file indietro.

[out, optional] lpNewFilePointer

Puntatore a una variabile per ricevere il nuovo puntatore al file. Se questo parametro è NULL, il nuovo puntatore al file non viene restituito.

[in] dwMoveMethod

Punto di partenza per lo spostamento del puntatore del file. Questo parametro può avere uno dei valori seguenti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il puntatore al file restituito da questa funzione non viene usato per operazioni di lettura e scrittura sovrapposte. Per specificare l'offset per le operazioni sovrapposte, usare i membri Offset e OffsetHigh della struttura OVERLAPPED.

Non è possibile usare la funzione SetFilePointerEx con un handle per un dispositivo non visualizzante, ad esempio una pipe o un dispositivo di comunicazione. Per determinare il tipo di file per hFile, usare la funzione GetFileType .

Prestare attenzione quando si imposta il puntatore file in un'applicazione multithreading. È necessario sincronizzare l'accesso alle risorse condivise. Ad esempio, un'applicazione i cui thread condividono un handle di file, aggiorna il puntatore al file e legge dal file deve proteggere questa sequenza usando un oggetto sezione critico o un oggetto mutex. Per altre informazioni su questi oggetti, vedere Oggetti della sezione critica e Oggetti Mutex.

Se l'handle hFile è stato aperto con il set di flag FILE_FLAG_NO_BUFFERING , un'applicazione può spostare il puntatore del file solo alle posizioni allineate al settore. Una posizione allineata al settore è una posizione che rappresenta un numero intero di dimensioni del settore del volume. Un'applicazione può ottenere le dimensioni del settore di un volume chiamando la funzione GetDiskFreeSpace . Se un'applicazione chiama SetFilePointerEx con valori da distanza a spostamento che comportano una posizione non allineata al settore e un handle aperto con FILE_FLAG_NO_BUFFERING, la funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER. Per altre informazioni, vedere Buffering file.

Si noti che non è un errore per impostare il puntatore del file su una posizione oltre la fine del file. Le dimensioni del file non aumentano finché non si chiama la funzione SetEndOfFile, WriteFile o WriteFileEx. Un'operazione di scrittura aumenta le dimensioni del file nella posizione del puntatore del file più le dimensioni del buffer scritto, che comporta l'inizializzazione zero dei byte di intervento.

È possibile usare SetFilePointerEx per determinare la lunghezza di un file. A tale scopo, usare FILE_END per dwMoveMethod e cercare la posizione zero. L'offset del file restituito è la lunghezza del file. Tuttavia, questa pratica può avere effetti collaterali imprevisti, ad esempio l'errore di salvare il puntatore del file corrente in modo che il programma possa tornare a tale posizione. È invece più semplice e sicuro usare la funzione GetFileSizeEx .

È anche possibile usare SetFilePointerEx per eseguire query sulla posizione del puntatore al file corrente. A tale scopo, specificare un metodo di spostamento di FILE_CURRENT e una distanza pari a zero.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Requisiti

Vedere anche

Funzioni di gestione file

Getdiskfreespaceex

GetFileSizeEx

GetFileType

SetEndOfFile

WriteFile

WriteFileEx