c++ Windows API FindFirstFile函数

1.前言

        上文介绍了windows API 获取文件属性 GetFileAttributes()函数；

        Windows  API中还有一个函数FindFirstFile()也能够查询一些文件的属性；

        本文介绍FindFirstFile函数

2.内容

         FindFirstFile():主要用于在文件系统中查找指定目录中的第一个文件或目录，并返回其句柄。通常使用场景是进行文件搜索和管理，效率相对较高。

2.1函数原型

HANDLE FindFirstFile(  
  LPCTSTR lpFileName,              // 指向要搜索的目录或文件名的指针  
  LPWIN32_FIND_DATA lpFindFileData // 指向WIN32_FIND_DATA结构的指针，用于接收找到的文件或目录的信息  
);

 放回值类型：HANDLE

在Windows中，HANDLE是一个指向对象的句柄，表示对象在内核对象表中的唯一标识。
HANDLE的类型实际上是一个指针类型，它可以指向不同类型的对象，包括文件、进程、线程、事件、互斥体等。
在C++中，HANDLE被定义为void*类型，可以通过一些特定的函数进行类型转换。
例如，将HANDLE转换为文件句柄可以使用函数CreateFile()，将HANDLE转换为进程句柄可以使用函数OpenProcess()。

以上为InsCode AI 关于HANDLE介绍的回答，不容易理解。这里我们不用过于关心。

函数参数一：LPCTSTR

 它是一个宏定义，由几个部分组成：

        1.LP表示long pointer  ： 长指针类型

        2.C表示const ： 指针指向的内容为常量

        3.T代表在Win32环境中可能存在的_T宏，用于兼容Unicode和ANSI字符串；（具体不太清楚）

        4.STR表示这个变量是一个字符串

函数参数二：LPWIN32_FIND_DATA

        它是一个指向WIN32_FIND_DATA结构体的指针，我们可以从上面关于LP的解释中得到该结论。

        WIN32_FIND_DATA结构体的成员如下：

typedef struct _WIN32_FIND_DATA {  
    DWORD       dwFileAttributes;       // 文件属性  
    FILETIME    ftCreationTime;         // 文件创建时间  
    FILETIME    ftLastAccessTime;       // 文件最后一次访问时间  
    FILETIME    ftLastWriteTime;        // 文件最后一次修改时间  
    DWORD       nFileSizeHigh;          // 文件大小的高32位  
    DWORD       nFileSizeLow;           // 文件大小的低32位  
    DWORD       dwReserved0;            // 系统保留  
    DWORD       dwReserved1;            // 系统保留  
    TCHAR       cFileName[MAX_PATH];    // 长文件名  
    TCHAR       cAlternateFileName[14]; // 8.3格式文件名  
} WIN32_FIND_DATA, *LPWIN32_FIND_DATA;

        可以看到该结构体包含了文件属性、文件创建时间、文件最后一次访问时间、文件最后一次修改时间、文件大小、长文件名等信息。

函数使用示例

    WIN32_FIND_DATA ffd;
    HANDLE hFind = FindFirstFile("work.h", &ffd); // work.h 是文件地址

    if (hFind == INVALID_HANDLE_VALUE) {  
        std::cerr << "Failed to find the first file." << std::endl;  
        return 1;  
    }  

    // 关闭句柄
    FindClose(hFind);  

1. 首先声明一个WIN32_FIND_DATA结构体变量
2. 将结构体变量的地址传入函数
3. 使用句柄来判断函数执行结果

 函数使用注意事项

• 函数传入WIN32_FIND_DATA结构体变量的地址
• 在使用完FindFirstFile后，应该使用FindClose函数关闭该句柄，以释放与之关联的资源。
• 在处理文件名时，应注意文件名可能包含空格、特殊字符或Unicode字符，因此应适当处理这些情况。
• 如果需要搜索具有特定属性的文件（如隐藏文件、只读文件等），则可能需要结合其他函数或API来实现。