SetFilePointerEx, fonction (fileapi.h)

Article
01/30/2024

Déplace le pointeur du fichier spécifié.

Syntaxe

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

Paramètres

[in] hFile

Descripteur du fichier. Le handle de fichier doit avoir été 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] liDistanceToMove

Nombre d’octets pour déplacer le pointeur de fichier. Une valeur positive déplace le pointeur vers l’avant dans le fichier et une valeur négative déplace le pointeur vers l’arrière.

[out, optional] lpNewFilePointer

Pointeur vers une variable pour recevoir le nouveau pointeur de fichier. Si ce paramètre a la valeur NULL, le nouveau pointeur de fichier n’est pas retourné.

[in] dwMoveMethod

Point de départ du déplacement du pointeur de fichier. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
FILE_BEGIN 0	Le point de départ est zéro ou le début du fichier. Si cet indicateur est spécifié, le paramètre liDistanceToMove est interprété comme une valeur non signée.
FILE_CURRENT 1	Le point de départ est la valeur actuelle du pointeur de fichier.
FILE_END 2	Le point de départ est la position de fin du fichier actuelle.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Le pointeur de fichier retourné par cette fonction n’est pas utilisé pour les opérations de lecture et d’écriture qui se chevauchent. Pour spécifier le décalage pour les opérations qui se chevauchent, utilisez les membres Offset et OffsetHigh de la structure OVERLAPPED .

Vous ne pouvez pas utiliser la fonction SetFilePointerEx avec un handle pour un appareil non actif tel qu’un canal ou un périphérique de communication. Pour déterminer le type de fichier pour hFile, utilisez la fonction GetFileType .

Soyez prudent lorsque vous définissez le pointeur de fichier dans une application multithread. Vous devez synchroniser l’accès aux ressources partagées. Par exemple, une application dont les threads 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 sur ces objets, consultez Critical Section Objects et Mutex Objects.

Si le handle hFile a été 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 un secteur. Une position alignée sur un secteur est une position qui est un multiple entier de la taille du secteur du volume. Une application peut obtenir la taille de secteur d’un volume en appelant la fonction GetDiskFreeSpace . Si une application appelle SetFilePointerEx avec des valeurs de distance à déplacer qui entraînent une position qui n’est pas alignée sur le secteur et un handle qui a été ouvert avec FILE_FLAG_NO_BUFFERING, la fonction échoue et GetLastError retourne ERROR_INVALID_PARAMETER. Pour plus d’informations, consultez Mise en mémoire tampon des fichiers.

Notez qu’il n’est pas nécessaire de définir le pointeur de fichier à 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.

Vous pouvez utiliser SetFilePointerEx 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, tels que l’échec de l’enregistrement du pointeur de fichier actuel afin que le programme puisse revenir à cet emplacement. Il est plus simple et plus sûr d’utiliser la fonction GetFileSizeEx à la place.

Vous pouvez également utiliser SetFilePointerEx 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

Configuration requise


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