Функция SetFilePointerEx перемещает указатель позиции в файле открытого файла.
Синтаксис
BOOL SetFilePointerEx( HANDLE hFile, // дескриптор файла LARGE_INTEGER liDistanceToMove, // байты, перемещающие указатель PLARGE_INTEGER lpNewFilePointer, // новый указатель позиции DWORD dwMoveMethod // точка отсчета ); |
Параметры
hFile
[in] Дескриптор файла, указатель позиции в котором должен переместиться. Дескриптор файла, должен быть создан с правом доступа GENERIC_READ или GENERIC_WRITE. Для получения дополнительной информации, см. статью Защита файла и права доступа.liDistanceToMove
[in] Число байтов, на которое переместиться указатель позиции в файле. Положительное значение перемещает указатель в файле вперед, а отрицательное значение перемещает указатель в файле назад.lpNewFilePointer
[out] Указатель на переменную, которая получает новый указатель позиции в файле. Если этот параметр - ПУСТО (NULL), новый указатель в файле не возвращается.dwMoveMethod
[in] Точка отсчета перемещения указателя позиции в файле. Этим параметром может быть одно из нижеперечисленных значений.| Значение | Предназначение |
|---|---|
| FILE_BEGIN | Точка отсчета равняется нулю или это начало файла. Если этот флажок установлен, то параметр liDistanceToMove интерпретируется как значение без знака. |
| FILE_CURRENT | Точка отсчета - текущее значение указателя позиции в файле. |
| FILE_END | Точка отсчета - текущая позиция метки конца файла. |
Возвращаемые значения
Если функция завершается успешно, возвращаемое значение - не нуль.
Если функция завершается ошибкой, величина возвращаемого значения - нуль. Чтобы получить дополнительные данные об ошибке, вызовите GetLastError.
Замечания
Указатель позиции в файле, возвращенный этой функцией не используется для асинхронных операций чтения и записи. Чтобы определить смещение для асинхронных операций, используйте члены Offset и OffsetHigh структуры OVERLAPPED.
Вы не можете использовать функцию SetFilePointerEx с дескриптором не способного к поиску устройства, такого как канал или коммуникационное устройство. Чтобы выяснить тип файла для hFile, используйте функцию GetFileType.
Проявляйте осмотрительность при установке указателя позиции в файле в многопоточном приложении. Вы должны синхронизировать доступ к совместно используемым ресурсам. Например, прикладная программа, потоки которой совместно используют дескриптор файла, модернизирует указатель позиции в файле и, читая из него, должна защищать эту последовательность байтов, используя объект критической секции или объект типа мьютекс. Для получения дополнительной информации об этих объектах, см. статьи Объекты критической секции и Объекты типа мьютекс.
Если дескриптор файла hFile открывался с установкой флажка FILE_FLAG_NO_BUFFERING, приложение может переместить указатель позиции в файле только в выровненное по границе сектора положение. Выровненное по границам сектора положение (sector-aligned position) - это позиция, которая является целым числом, кратным размеру сектора тома. Приложение может получить размер сектора тома при помощи вызова функция GetDiskFreeSpaceEx. Если приложение вызывает функцию SetFilePointerEx со значениями длины перемещения, которые дают в результате позицию, не выровненную по границе сектора, а дескриптор, который открывался, с флажком FILE_FLAG_NO_BUFFERING, функция завершается ошибкой, а GetLastError возвращает значение ERROR_INVALID_PARAMETER.
|
Обратите внимание! на то, что это - не ошибка установки указателя позиции в файле в положение вне конца файла. Размер файла не увеличиться до тех пор, пока Вы не вызовите функцию SetEndOfFile, WriteFile или WriteFileEx. Операция записи увеличивает размер файла для позиции указателя в файле плюс размер буфера записи, оставляя промежуточные байты неинициализированными. |
Вы можете использовать SetFilePointerEx, чтобы выяснить длину файла. Чтобы сделать это, используйте флажок FILE_END в параметре dwMoveMethod и ищите местоположение нуля. Смещение файла возвращает его длину. Однако, эта практика может иметь непреднамеренные побочные эффекты, типа сбоя, для сохранения текущей позиции указателя в файле так, чтобы программа могла возвратиться этому месту. Проще и безопаснее вместо этого использовать функцию GetFileSizeEx.
Вы можете также использовать функцию SetFilePointerEx, чтобы сделать запрос текущего местоположения указателя позиции в файле. Чтобы сделать это, определите метод перемещения FILE_CURRENT и нулевое расстояние.
Смотри также
Обзор Управление файлами, Функции для файлового ввода-вывода (I/O), GetDiskFreeSpaceEx, GetFileSizeEx, GetFileType, SetEndOfFile, WriteFile, WriteFileEx
|
Размещение и совместимость SetFilePointerEx |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT |
Нет |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Нет |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
Kernel32.lib |
|
| Используемая DLL | - | |
| Заголовочный файл | ||
|
- объявлено в |
Winbase.h |
|
| - включено в |
Windows.h |
|
| Unicode |
Нет |
|
| Замечания по платформе |
Не имеется |
|