Función SetFilePointerEx (fileapi.h)
Mueve el puntero de archivo del archivo especificado.
Sintaxis
BOOL SetFilePointerEx(
[in] HANDLE hFile,
[in] LARGE_INTEGER liDistanceToMove,
[out, optional] PLARGE_INTEGER lpNewFilePointer,
[in] DWORD dwMoveMethod
);
Parámetros
[in] hFile
Identificador del archivo. El identificador de archivo debe haberse creado con el derecho de acceso GENERIC_READ o GENERIC_WRITE . Para obtener más información, vea Seguridad de archivos y derechos de acceso.
[in] liDistanceToMove
Número de bytes que se van a mover el puntero de archivo. Un valor positivo mueve el puntero hacia delante en el archivo y un valor negativo mueve el puntero de archivo hacia atrás.
[out, optional] lpNewFilePointer
Puntero a una variable para recibir el nuevo puntero de archivo. Si este parámetro es NULL, no se devuelve el nuevo puntero de archivo.
[in] dwMoveMethod
Punto de partida para el movimiento del puntero de archivo. Este parámetro puede ser uno de los valores siguientes.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Comentarios
El puntero de archivo devuelto por esta función no se usa para las operaciones de lectura y escritura superpuestas. Para especificar el desplazamiento para las operaciones superpuestas, use los miembros Offset y OffsetHigh de la estructura SUPERPUESTA .
No se puede usar la función SetFilePointerEx con un identificador para un dispositivo que no esté abierto, como una canalización o un dispositivo de comunicaciones. Para determinar el tipo de archivo para hFile, use la función GetFileType .
Tenga cuidado al establecer el puntero de archivo en una aplicación multiproceso. Debe sincronizar el acceso a los recursos compartidos. Por ejemplo, una aplicación cuyos subprocesos comparten un identificador de archivo, actualiza el puntero de archivo y lee desde el archivo debe proteger esta secuencia mediante un objeto de sección crítico o un objeto de exclusión mutua. Para obtener más información sobre estos objetos, vea Objetos de sección crítica y Objetos de exclusión mutua.
Si el identificador hFile se abrió con el conjunto de marcas de FILE_FLAG_NO_BUFFERING , una aplicación solo puede mover el puntero de archivo a posiciones alineadas con sectores. Una posición alineada con el sector es una posición que es un número entero múltiplo del tamaño del sector del volumen. Una aplicación puede obtener el tamaño del sector de un volumen llamando a la función GetDiskFreeSpace . Si una aplicación llama a SetFilePointerEx con valores de distancia a movimiento que dan como resultado una posición que no está alineada con el sector y un identificador que se abrió con FILE_FLAG_NO_BUFFERING, se produce un error en la función y GetLastError devuelve ERROR_INVALID_PARAMETER. Para obtener más información, consulte Almacenamiento en búfer de archivos.
Tenga en cuenta que no es un error establecer el puntero de archivo en una posición más allá del final del archivo. El tamaño del archivo no aumenta hasta que se llama a la función SetEndOfFile, WriteFile o WriteFileEx . Una operación de escritura aumenta el tamaño del archivo a la posición del puntero de archivo más el tamaño del búfer escrito, lo que da lugar a que los bytes intermedios se inicialicen a cero.
Puede usar SetFilePointerEx para determinar la longitud de un archivo. Para ello, use FILE_END para dwMoveMethod y busque la ubicación cero. El desplazamiento del archivo devuelto es la longitud del archivo. Sin embargo, esta práctica puede tener efectos secundarios no deseados, como el error al guardar el puntero de archivo actual para que el programa pueda volver a esa ubicación. Es más sencillo y seguro usar la función GetFileSizeEx en su lugar.
También puede usar SetFilePointerEx para consultar la posición del puntero de archivo actual. Para ello, especifique un método de movimiento de FILE_CURRENT y una distancia de cero.
En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.
| Tecnología | Compatible |
|---|---|
| Protocolo Bloque de mensajes del servidor (SMB) 3.0 | Sí |
| Conmutación por error transparente (TFO) de SMB 3.0 | Sí |
| SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO) | Sí |
| Sistema de archivos de Volumen compartido de clúster (CsvFS) | Sí |
| Sistema de archivos resistente a errores (ReFS) | Sí |
Requisitos
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | fileapi.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |