Fungsi FindFirstFileExA (fileapi.h)

Artikel
03/14/2023

Mencari direktori untuk file atau subdirektori dengan nama dan atribut yang cocok dengan yang ditentukan.

Untuk versi paling dasar dari fungsi ini, lihat FindFirstFile.

Untuk melakukan operasi ini sebagai operasi yang ditransaksikan, gunakan fungsi FindFirstFileTransacted .

Sintaks

HANDLE FindFirstFileExA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

Parameter

[in] lpFileName

Direktori atau jalur, dan nama file. Nama file dapat menyertakan karakter kartubebas, misalnya, tanda bintang (*) atau tanda tanya (?).

Parameter ini tidak boleh NULL, string yang tidak valid (misalnya, string kosong atau string yang tidak memiliki karakter null yang mengakhiri), atau berakhir dengan garis miring terbalik berikutnya (\).

Jika string berakhir dengan kartubebas, titik, atau nama direktori, pengguna harus memiliki akses ke akar dan semua subdirektori di jalur.

Secara default, namanya terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Tip

Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa menambahkan sebelumnya "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" di Penamaan File, Jalur, dan Namespace untuk detailnya.

[in] fInfoLevelId

Tingkat informasi data yang dikembalikan.

Parameter ini adalah salah satu nilai enumerasi FINDEX_INFO_LEVELS .

[out] lpFindFileData

Penunjuk ke buffer yang menerima data file.

Jenis penunjuk ditentukan oleh tingkat informasi yang ditentukan dalam parameter fInfoLevelId .

[in] fSearchOp

Jenis pemfilteran untuk dilakukan yang berbeda dari pencocokan kartubebas.

Parameter ini adalah salah satu nilai enumerasi FINDEX_SEARCH_OPS .

lpSearchFilter

Penunjuk ke kriteria pencarian jika fSearchOp yang ditentukan memerlukan informasi pencarian terstruktur.

Saat ini, tidak ada nilai fSearchOp yang didukung yang memerlukan informasi pencarian yang diperluas. Oleh karena itu, pointer ini harus NULL.

[in] dwAdditionalFlags

Menentukan bendera tambahan yang mengontrol pencarian.

Nilai	Makna
FIND_FIRST_EX_CASE_SENSITIVE 1	Pencarian peka huruf besar/kecil.
FIND_FIRST_EX_LARGE_FETCH 2	Menggunakan buffer yang lebih besar untuk kueri direktori, yang dapat meningkatkan performa operasi temukan. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung sampai Windows Server 2008 R2 dan Windows 7.
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	Membatasi hasil ke file yang secara fisik berada di disk. Bendera ini hanya relevan ketika filter virtualisasi file ada.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel pencarian yang digunakan dalam panggilan berikutnya ke FindNextFile atau FindClose, dan parameter lpFindFileData berisi informasi tentang file atau direktori pertama yang ditemukan.

Jika fungsi gagal atau gagal menemukan file dari string pencarian dalam parameter lpFileName , nilai yang dikembalikan INVALID_HANDLE_VALUE dan konten lpFindFileData tidak ditentukan. Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .

Keterangan

Fungsi FindFirstFileEx membuka handel pencarian dan mengembalikan informasi tentang file pertama yang ditemukan sistem file dengan nama yang cocok dengan pola yang ditentukan. Ini mungkin atau mungkin bukan file atau direktori pertama yang muncul dalam aplikasi daftar direktori (seperti perintah dir) ketika diberi pola string nama file yang sama. Ini karena FindFirstFileEx tidak melakukan pengurutan hasil pencarian. Untuk informasi tambahan, lihat FindNextFile.

Daftar berikut mengidentifikasi beberapa karakteristik pencarian lainnya:

Pencarian dilakukan secara ketat pada nama file, bukan pada atribut apa pun seperti tanggal atau jenis file.
Pencarian mencakup nama file yang panjang dan pendek.
Upaya untuk membuka pencarian dengan garis miring terbalik berikutnya selalu gagal.
Meneruskan string, NULL, atau string kosong yang tidak valid untuk parameter lpFileName bukanlah penggunaan fungsi ini yang valid. Hasil dalam hal ini tidak ditentukan.

Catatan Dalam kasus yang jarang terjadi atau pada sistem yang sangat dimuat, informasi atribut file pada sistem file NTFS mungkin tidak terkini pada saat fungsi ini dipanggil. Untuk memastikan mendapatkan atribut file sistem file NTFS saat ini, panggil fungsi GetFileInformationByHandle .

Jika sistem file yang mendasar tidak mendukung jenis pemfilteran yang ditentukan, selain pemfilteran direktori, FindFirstFileEx gagal dengan kesalahan ERROR_NOT_SUPPORTED. Aplikasi harus menggunakan jenis FINDEX_SEARCH_OPSFileExSearchNameMatch dan melakukan pemfilterannya sendiri.

Setelah handel pencarian dibuat, gunakan di fungsi FindNextFile untuk mencari file lain yang cocok dengan pola yang sama dengan pemfilteran yang sama yang sedang dilakukan. Ketika handel pencarian tidak diperlukan, handel pencarian harus ditutup dengan menggunakan fungsi FindClose .

Seperti yang dinyatakan sebelumnya, Anda tidak dapat menggunakan garis miring terbalik berikutnya (\) dalam string input lpFileName untuk FindFirstFileEx, oleh karena itu mungkin tidak jelas cara mencari direktori akar. Jika Anda ingin melihat file atau mendapatkan atribut direktori akar, opsi berikut akan berlaku:

Untuk memeriksa file di direktori akar, Anda dapat menggunakan "C:\*" dan menelusuri direktori dengan menggunakan FindNextFile.
Untuk mendapatkan atribut direktori akar, gunakan fungsi GetFileAttributes .

Catatan Menambahkan string "\\?\" tidak mengizinkan akses ke direktori akar.

Pada berbagi jaringan, Anda dapat menggunakan lpFileName dalam bentuk berikut: "\\server\service\*". Namun, Anda tidak dapat menggunakan lpFileName yang menunjuk ke berbagi itu sendiri; misalnya, "\\server\service" tidak valid.

Untuk memeriksa direktori yang bukan direktori akar, gunakan jalur ke direktori tersebut, tanpa garis miring terbelakang. Misalnya, argumen "C:\Windows" mengembalikan informasi tentang direktori "C:\Windows", bukan tentang direktori atau file di "C:\Windows". Untuk memeriksa file dan direktori di "C:\Windows", gunakan lpFileName dari "C:\Windows\*".

Panggilan berikut:

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

Setara dengan panggilan berikut:

FindFirstFile( lpFileName, lpFindData );

Ketahuilah bahwa beberapa utas atau proses lain dapat membuat atau menghapus file dengan nama ini antara waktu Anda mengkueri hasil dan waktu Anda bertindak berdasarkan informasi. Jika ini adalah masalah potensial untuk aplikasi Anda, salah satu solusi yang mungkin adalah menggunakan fungsi CreateFile dengan CREATE_NEW (yang gagal jika file ada) atau OPEN_EXISTING (yang gagal jika file tidak ada).

Jika Anda menulis aplikasi 32-bit untuk mencantumkan semua file dalam direktori dan aplikasi dapat dijalankan pada komputer 64-bit, Anda harus memanggil Wow64DisableWow64FsRedirection sebelum memanggil FindFirstFileEx dan memanggil Wow64RevertWow64FsRedirection setelah panggilan terakhir ke FindNextFile. Untuk informasi selengkapnya, lihat Pengalihan Sistem File.

Jika jalur menunjuk ke tautan simbolis, buffer WIN32_FIND_DATA berisi informasi tentang tautan simbolis, bukan target.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Berbagi File Peluasan Skala (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Contoh

Kode berikut menunjukkan penggunaan minimal FindFirstFileEx. Program ini setara dengan contoh dalam topik FindFirstFile .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Catatan

Header fileapi.h mendefinisikan FindFirstFileEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll