Funzione SetFilePointer (fileapi.h)
Sposta il puntatore del file del file specificato.
Questa funzione archivia il puntatore file in due valori LONG . Per usare i puntatori ai file più grandi di un singolo valore LONG , è più semplice usare la funzione SetFilePointerEx .
Sintassi
DWORD SetFilePointer(
[in] HANDLE hFile,
[in] LONG lDistanceToMove,
[in, out, optional] PLONG lpDistanceToMoveHigh,
[in] DWORD dwMoveMethod
);
Parametri
[in] hFile
Handle per il file.
L'handle di file deve essere creato con il GENERIC_READ o GENERIC_WRITE diritto di accesso. Per altre informazioni, vedere Sicurezza file e diritti di accesso.
[in] lDistanceToMove
L'ordine basso a 32 bit di un valore firmato che specifica il numero di byte per spostare il puntatore del file.
Se lpDistanceToMoveHigh non è NULL, lpDistanceToMoveHigh e lDistanceToMove formano un valore con segno a 64 bit singolo che specifica la distanza da spostare.
Se lpDistanceToMoveHigh è NULL, lDistanceToMove è un valore firmato a 32 bit. Un valore positivo per lDistanceToMove sposta il puntatore del file in avanti nel file e un valore negativo sposta nuovamente il puntatore del file.
[in, out, optional] lpDistanceToMoveHigh
Puntatore all'ordine elevato di 32 bit della distanza a 64 bit firmata da spostare.
Se non è necessario l'ordine elevato a 32 bit, questo puntatore deve essere impostato su NULL.
Quando non NULL, questo parametro riceve anche l'ordine elevato DWORD del nuovo valore del puntatore file. Per altre informazioni, vedere la sezione Osservazioni in questo argomento.
[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 e lpDistanceToMoveHigh è NULL, il valore restituito è il valore DWORD a basso ordine del nuovo puntatore di file. Nota Se la funzione restituisce un valore diverso da INVALID_SET_FILE_POINTER, la chiamata a SetFilePointer ha avuto esito positivo. Non è necessario chiamare GetLastError.
Se la funzione ha esito positivo e lpDistanceToMoveHigh non è NULL, il valore restituito è il DWORD a basso ordine del nuovo puntatore file e lpDistanceToMoveHigh contiene l'ordine elevato DWORD del nuovo puntatore file.
Se la funzione ha esito negativo, il valore restituito è INVALID_SET_FILE_POINTER. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Se un nuovo puntatore di file è un valore negativo, la funzione ha esito negativo, il puntatore del file non viene spostato e il codice restituito da GetLastError è ERROR_NEGATIVE_SEEK.
Se lpDistanceToMoveHigh è NULL e la nuova posizione del file non rientra in un valore a 32 bit, la funzione ha esito negativo e restituisce INVALID_SET_FILE_POINTER.
Commenti
Il puntatore di file identificato dal valore del parametro hFile non viene usato per operazioni di lettura e scrittura sovrapposte.
Il parametro hFile deve fare riferimento a un file archiviato in un dispositivo di ricerca; ad esempio, un volume del disco. La chiamata alla funzione SetFilePointer con un handle a un dispositivo non di ricerca, ad esempio una pipe o un dispositivo di comunicazione non è supportata, anche se la funzione SetFilePointer potrebbe non restituire un errore. Il comportamento della funzione SetFilePointer in questo caso non è definito.
Per specificare l'offset per le operazioni sovrapposte
- Usare i membri Offset e OffsetHigh della struttura OVERLAPPED.
Per determinare il tipo di file per hFile
- Usare la funzione GetFileType .
Prestare attenzione quando si imposta un puntatore file in un'applicazione multithreading. È necessario sincronizzare l'accesso alle risorse condivise. Ad esempio, un'applicazione con thread che condividono un handle di file, aggiorna il puntatore file e legge dal file deve proteggere questa sequenza usando un oggetto di sezione critico o un oggetto mutex. Per altre informazioni, vedere Oggetti della sezione critica e oggetti Mutex.
Se l'handle hFile viene 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 una dimensione del settore del volume chiamando la funzione GetDiskFreeSpace .
Se un'applicazione chiama SetFilePointer con distanza per spostare i valori 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.
Non è un errore impostare un puntatore 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.
Se il valore restituito è INVALID_SET_FILE_POINTER e se lpDistanceToMoveHigh non è NULL, un'applicazione deve chiamare GetLastError per determinare se la funzione ha avuto esito positivo o negativo. Nell'esempio di codice seguente viene illustrato questo scenario.
// Case One: calling the function with lpDistanceToMoveHigh == NULL
// Try to move hFile file pointer some distance
DWORD dwPtr = SetFilePointer( hFile,
lDistance,
NULL,
FILE_BEGIN );
if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure
{
// Obtain the error code.
DWORD dwError = GetLastError() ;
// Deal with failure
// . . .
} // End of error handler
//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL
// Try to move hFile file pointer a huge distance
DWORD dwPtrLow = SetFilePointer( hFile,
lDistLow,
&lDistHigh,
FILE_BEGIN );
// Test for failure
if ( dwPtrLow == INVALID_SET_FILE_POINTER &&
GetLastError() != NO_ERROR )
{
// Deal with failure
// . . .
} // End of error handler
Anche se il parametro lpDistanceToMoveHigh viene usato per modificare grandi file, il valore del parametro deve essere impostato quando si spostano file di qualsiasi dimensione. Se è impostato su NULL, lDistanceToMove ha un valore massimo di 2^31-2 o 2 gigabyte meno 2, perché tutti i valori del puntatore di file sono firmati. Pertanto, se esiste anche una piccola possibilità per il file di aumentare di tale dimensione, è consigliabile trattare il file come un file enorme e usare i puntatori a file a 64 bit. Con la compressione dei file system NTFS e i file sparse, è possibile avere file di grandi dimensioni anche se il volume sottostante non è molto grande.
Se lpDistanceToMoveHigh non è NULL, lpDistanceToMoveHigh e lDistanceToMove formano un valore con segno a 64 bit singolo. Il parametro lDistanceToMove viene considerato come i 32 bit di basso ordine del valore e lpDistanceToMoveHigh come 32 bit di alto ordine, ovvero lpDistanceToMoveHigh è un'estensione di segno di lDistanceToMoveMove.
Per spostare il puntatore del file da zero a 2 gigabyte, è necessario impostare lpDistanceToMoveHigh su NULL o su un'estensione di segno di lDistanceToMove. Per spostare il puntatore più di 2 gigabyte, usare lpDistanceToMoveHigh e lDistanceToMove come quantità a 64 bit singola. Ad esempio, per spostare l'intervallo da 2 gigabyte a 4 gigabyte impostare il contenuto di lpDistanceToMoveHigh su zero o su -1 per un'estensione di segno negativo di lDistanceToMove.
Per usare i puntatori ai file a 64 bit, è possibile dichiarare long, considerarlo come la metà superiore del puntatore al file a 64 bit e passarne l'indirizzo in lpDistanceToMoveHigh. Ciò significa che è necessario considerare due variabili diverse come un'unità logica, che può causare un errore. È consigliabile usare la struttura LARGE_INTEGER per creare un valore a 64 bit e passare i due valori a 32 bit usando gli elementi appropriati dell'unione.
Inoltre, è consigliabile usare una funzione per nascondere l'interfaccia a SetFilePointer. Nell'esempio di codice seguente viene illustrato questo scenario.
__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
LARGE_INTEGER li;
li.QuadPart = distance;
li.LowPart = SetFilePointer (hf,
li.LowPart,
&li.HighPart,
MoveMethod);
if (li.LowPart == INVALID_SET_FILE_POINTER && GetLastError()
!= NO_ERROR)
{
li.QuadPart = -1;
}
return li.QuadPart;
}
È possibile usare SetFilePointer 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, non è possibile salvare il puntatore del file corrente in modo che il programma possa tornare a tale posizione. È consigliabile usare GetFileSize .
È anche possibile usare la funzione SetFilePointer per eseguire query sulla posizione del puntatore del 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.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso del cluster (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Esempi
Per un esempio di codice relativo all'aggiunta di file, vedere Aggiunta di un file a un altro file.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |