SetFilePointerEx函数释义以及用法

一、函数介绍

SetFilePointerEx是一个Windows API函数，用于设置文件指针的位置。它可以在文件中移动指针，以便读取或写入文件的不同部分。这个函数通常用于处理大型文件或需要随机访问文件的应用程序中。

使用SetFilePointerEx函数可以将文件指针移动到指定的偏移量处。这个函数可以设置文件指针相对于文件开头、文件结尾或当前指针位置的偏移量。它还可以在文件指针移动时返回新的文件指针位置。

在处理大型文件时，使用SetFilePointerEx函数可以有效地访问文件的不同部分，而无需读取整个文件。此外，当需要随机访问文件时，这个函数也非常有用。

二、函数原型

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

hFile：要移动指针的文件的句柄。
liDistanceToMove：指定指针移动的距离和方向。它是一个LARGE_INTEGER结构体，可以指定相对于文件开头、文件结尾或当前指针位置的偏移量。
lpNewFilePointer：一个指针，指向一个LARGE_INTEGER结构体，用于接收新的文件指针位置。
dwMoveMethod：指定指针移动的方式，可以是FILE_BEGIN、FILE_CURRENT或FILE_END之一，分别表示相对于文件开头、当前指针位置或文件结尾的偏移量。
返回值：TRUE表示成功，FALSE表示失败。

三、示例

HANDLE hFile = CreateFile("example.txt", GENERIC_READ, 0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
if (hFile == INVALID_HANDLE_VALUE)
{
    std::cout << "Failed to open file." << std::endl;
    return 1;
}

LARGE_INTEGER liDistanceToMove;
liDistanceToMove.QuadPart = 10; // 移动指针10个字节

LARGE_INTEGER liNewFilePointer;

// 示例1：从文件开头开始，向前偏移10个字节，同时当前指针会更新为移动后的位置
if (!SetFilePointerEx(hFile, liDistanceToMove, &liNewFilePointer, FILE_BEGIN))
{
    std::cout << "Failed to set file pointer." << std::endl;
    CloseHandle(hFile);
    return 1;
}

// 示例2：从文件当前指针开始，向前偏移10个字节，同时当前指针会更新为移动后的位置
if (!SetFilePointerEx(hFile, liDistanceToMove, &liNewFilePointer, FILE_CURRENT))
{
    std::cout << "Failed to set file pointer." << std::endl;
    CloseHandle(hFile);
    return 1;
}

// 示例3：从文件末尾开始，向后偏移10个字节，同时当前指针会更新为移动后的位置
if (!SetFilePointerEx(hFile, liDistanceToMove, &liNewFilePointer, FILE_END))
{
    std::cout << "Failed to set file pointer." << std::endl;
    CloseHandle(hFile);
    return 1;
}

std::cout << "New file pointer position: " << liNewFilePointer.QuadPart << std::endl;

CloseHandle(hFile);
return 0;

参考文章

[1] uTools中的AI对话
[2] SetFilePointerEx 函数 (fileapi.h)