SetFilePointer, fonction (fileapi.h)
Déplace le pointeur du fichier spécifié.
Cette fonction stocke le pointeur de fichier dans deux valeurs LONG . Pour utiliser des pointeurs de fichier supérieurs à une valeur LONG unique, il est plus facile d’utiliser la fonction SetFilePointerEx .
Syntaxe
DWORD SetFilePointer(
[in] HANDLE hFile,
[in] LONG lDistanceToMove,
[in, out, optional] PLONG lpDistanceToMoveHigh,
[in] DWORD dwMoveMethod
);
Paramètres
[in] hFile
Descripteur du fichier.
Le handle de fichier doit être créé avec le droit d’accès GENERIC_READ ou GENERIC_WRITE . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.
[in] lDistanceToMove
Ordre inférieur 32 bits d’une valeur signée qui spécifie le nombre d’octets à déplacer le pointeur de fichier.
Si lpDistanceToMoveHigh n’a pas la valeur NULL, lpDistanceToMoveHigh et lDistanceToMove forment une seule valeur signée 64 bits qui spécifie la distance à déplacer.
Si lpDistanceToMoveHigh a la valeur NULL, lDistanceToMove est une valeur signée 32 bits. Une valeur positive pour lDistanceToMove déplace le pointeur de fichier vers l’avant dans le fichier, et une valeur négative déplace le pointeur de fichier vers l’arrière.
[in, out, optional] lpDistanceToMoveHigh
Pointeur vers les 32 bits d’ordre supérieur de la distance 64 bits signée à déplacer.
Si vous n’avez pas besoin des 32 bits d’ordre élevé, ce pointeur doit avoir la valeur NULL.
S’il n’est pas NULL, ce paramètre reçoit également l’ordre DWORD élevé de la nouvelle valeur du pointeur de fichier. Pour plus d’informations, consultez la section Remarques de cette rubrique.
[in] dwMoveMethod
Point de départ du déplacement du pointeur de fichier.
Ce paramètre peut prendre les valeurs suivantes.
Valeur retournée
Si la fonction réussit et que lpDistanceToMoveHigh a la valeur NULL, la valeur de retour est la valeur DWORD d’ordre inférieur du nouveau pointeur de fichier. Note Si la fonction retourne une valeur autre que INVALID_SET_FILE_POINTER, l’appel à SetFilePointer a réussi. Vous n’avez pas besoin d’appeler GetLastError.
Si la fonction réussit et que lpDistanceToMoveHigh n’a pas la valeur NULL, la valeur de retour est la valeur DWORD d’ordre inférieur du nouveau pointeur de fichier et lpDistanceToMoveHigh contient l’ordre élevé DWORD du nouveau pointeur de fichier.
Si la fonction échoue, la valeur de retour est INVALID_SET_FILE_POINTER. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Si un nouveau pointeur de fichier est une valeur négative, la fonction échoue, le pointeur de fichier n’est pas déplacé et le code retourné par GetLastError est ERROR_NEGATIVE_SEEK.
Si lpDistanceToMoveHigh a la valeur NULL et que la nouvelle position de fichier ne correspond pas à une valeur 32 bits, la fonction échoue et retourne INVALID_SET_FILE_POINTER.
Remarques
Le pointeur de fichier identifié par la valeur du paramètre hFile n’est pas utilisé pour les opérations de lecture et d’écriture qui se chevauchent.
Le paramètre hFile doit faire référence à un fichier stocké sur un appareil de recherche ; par exemple, un volume de disque. L’appel de la fonction SetFilePointer avec un handle à un appareil sans recherche, tel qu’un canal ou un périphérique de communication, n’est pas pris en charge, même si la fonction SetFilePointer peut ne pas renvoyer d’erreur. Dans ce cas, le comportement de la fonction SetFilePointer n’est pas défini.
Pour spécifier le décalage pour les opérations qui se chevauchent
- Utilisez les membres Offset et OffsetHigh de la structure OVERLAPPED .
Pour déterminer le type de fichier pour hFile
- Utilisez la fonction GetFileType .
Soyez prudent lorsque vous définissez un pointeur de fichier dans une application multithread. Vous devez synchroniser l’accès aux ressources partagées. Par exemple, une application avec des threads qui partagent un handle de fichier, mettent à jour le pointeur de fichier et lisent à partir du fichier doit protéger cette séquence à l’aide d’un objet de section critique ou d’un objet mutex. Pour plus d’informations, consultez Critical Section Objects et Mutex Objects.
Si le handle hFile est ouvert avec l’indicateur FILE_FLAG_NO_BUFFERING défini, une application peut déplacer le pointeur de fichier uniquement vers des positions alignées sur le secteur. Une position alignée sur un secteur est une position qui est un nombre entier multiple de la taille du secteur de volume. Une application peut obtenir une taille de secteur de volume en appelant la fonction GetDiskFreeSpace .
Si une application appelle SetFilePointer avec la distance pour déplacer des valeurs qui entraînent une position non alignée sur le secteur et un handle ouvert avec FILE_FLAG_NO_BUFFERING, la fonction échoue et GetLastError retourne ERROR_INVALID_PARAMETER.
Ce n’est pas une erreur que de définir un pointeur de fichier vers une position au-delà de la fin du fichier. La taille du fichier n’augmente pas tant que vous n’appelez pas la fonction SetEndOfFile, WriteFile ou WriteFileEx . Une opération d’écriture augmente la taille du fichier à la position du pointeur de fichier plus la taille de la mémoire tampon écrite, ce qui entraîne l’initialisation zéro des octets intermédiaires.
Si la valeur de retour est INVALID_SET_FILE_POINTER et si lpDistanceToMoveHigh n’a pas la valeur NULL, une application doit appeler GetLastError pour déterminer si la fonction a réussi ou échoué. L’exemple de code suivant vous montre ce scénario.
// 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
Bien que le paramètre lpDistanceToMoveHigh soit utilisé pour manipuler des fichiers volumineux, la valeur du paramètre doit être définie lors du déplacement de fichiers de toute taille. S’il est défini sur NULL, lDistanceToMove a une valeur maximale de 2^31 à 2, ou 2 gigaoctets moins 2, car toutes les valeurs de pointeur de fichier sont des valeurs signées. Par conséquent, s’il y a même une faible probabilité que le fichier augmente à cette taille, il est préférable de traiter le fichier comme un fichier volumineux et de travailler avec des pointeurs de fichier 64 bits. Avec la compression de fichiers sur le système de fichiers NTFS et les fichiers épars, il est possible d’avoir des fichiers volumineux même si le volume sous-jacent n’est pas très grand.
Si lpDistanceToMoveHigh n’a pas la valeur NULL, lpDistanceToMoveHigh et lDistanceToMove forment une seule valeur signée 64 bits. Le paramètre lDistanceToMove est traité comme les 32 bits d’ordre inférieur de la valeur, et lpDistanceToMoveHigh comme les 32 bits d’ordre élevé, ce qui signifie que lpDistanceToMoveHigh est une extension de signe de lDistanceToMove.
Pour déplacer le pointeur de fichier de zéro à 2 gigaoctets, lpDistanceToMoveHigh doit avoir la valeur NULL ou une extension de signe de lDistanceToMove. Pour déplacer le pointeur de plus de 2 gigaoctets, utilisez lpDistanceToMoveHigh et lDistanceToMove en tant que quantité unique de 64 bits. Par exemple, pour passer de 2 gigaoctets à 4 gigaoctets, définissez le contenu de lpDistanceToMoveHigh sur zéro, ou sur –1 pour une extension de signe négatif de lDistanceToMove.
Pour utiliser des pointeurs de fichier 64 bits, vous pouvez déclarer un LONG, le traiter comme la moitié supérieure du pointeur de fichier 64 bits et passer son adresse dans lpDistanceToMoveHigh. Cela signifie que vous devez traiter deux variables différentes comme une unité logique, ce qui peut entraîner une erreur. Il est préférable d’utiliser la structure LARGE_INTEGER pour créer une valeur 64 bits et passer les deux valeurs 32 bits à l’aide des éléments appropriés de l’union.
En outre, il est préférable d’utiliser une fonction pour masquer l’interface à SetFilePointer. L’exemple de code suivant vous montre ce scénario.
__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;
}
Vous pouvez utiliser SetFilePointer pour déterminer la longueur d’un fichier. Pour ce faire, utilisez FILE_END pour dwMoveMethod et recherchez l’emplacement zéro. Le décalage de fichier retourné est la longueur du fichier. Toutefois, cette pratique peut avoir des effets secondaires involontaires, par exemple, l’échec de l’enregistrement du pointeur de fichier actuel afin que le programme puisse revenir à cet emplacement. Il est préférable d’utiliser GetFileSize à la place.
Vous pouvez également utiliser la fonction SetFilePointer pour interroger la position actuelle du pointeur de fichier. Pour ce faire, spécifiez une méthode de déplacement de FILE_CURRENT et une distance de zéro.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
| Technologie | Prise en charge |
|---|---|
| Protocole Server Message Block (SMB) 3.0 | Oui |
| Basculement transparent SMB 3.0 (TFO) | Oui |
| SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) | Oui |
| Système de fichiers du volume partagé de cluster (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Exemples
Pour obtenir un exemple de code d’ajout de fichiers, consultez Ajout d’un fichier à un autre fichier.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |