Fungsi SearchPathW (processenv.h)

Artikel
08/25/2023

Mencari file tertentu dalam jalur tertentu.

Sintaks

DWORD SearchPathW(
  [in, optional]  LPCWSTR lpPath,
  [in]            LPCWSTR lpFileName,
  [in, optional]  LPCWSTR lpExtension,
  [in]            DWORD   nBufferLength,
  [out]           LPWSTR  lpBuffer,
  [out, optional] LPWSTR  *lpFilePart
);

Parameter

[in, optional] lpPath

Jalur yang akan dicari untuk file tersebut.

Jika parameter ini NULL, fungsi mencari file yang cocok menggunakan jalur pencarian sistem yang bergantung pada registri. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in] lpFileName

Nama file yang akan dicari.

[in, optional] lpExtension

Ekstensi yang akan ditambahkan ke nama file saat mencari file. Karakter pertama ekstensi nama file harus berupa titik (.). Ekstensi ditambahkan hanya jika nama file yang ditentukan tidak berakhir dengan ekstensi.

Jika ekstensi nama file tidak diperlukan atau jika nama file berisi ekstensi, parameter ini bisa null.

[in] nBufferLength

Ukuran buffer yang menerima jalur dan nama file yang valid (termasuk karakter null yang mengakhiri), dalam TCHAR.

[out] lpBuffer

Penunjuk ke buffer untuk menerima jalur dan nama file file yang ditemukan. String adalah string yang dihentikan null.

[out, optional] lpFilePart

Penunjuk ke variabel untuk menerima alamat (dalam lpBuffer) dari komponen terakhir dari jalur dan nama file yang valid, yang merupakan alamat karakter segera setelah garis miring terbalik akhir (\) di jalur.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah panjangnya, dalam TCHAR, dari string yang disalin ke buffer, tidak termasuk karakter null yang mengakhiri. Jika nilai yang dikembalikan lebih besar dari nBufferLength, nilai yang dikembalikan adalah ukuran buffer yang diperlukan untuk menahan jalur, termasuk karakter null yang mengakhiri.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jika parameter lpPathadalah NULL, SearchPath mencari file yang cocok berdasarkan nilai saat ini dari nilai registri berikut:

\ HKEY_LOCAL_MACHINESISTEM\CurrentControlSet\Kontrol\Manajer\ SesiSafeProcessSearchMode

Ketika nilai registri REG_DWORD ini diatur ke 1, SearchPath terlebih dahulu mencari folder yang ditentukan di jalur sistem, lalu mencari folder kerja saat ini. Ketika nilai registri ini diatur ke 0, komputer pertama-tama mencari folder kerja saat ini, lalu mencari folder yang ditentukan di jalur sistem. Nilai default sistem untuk kunci registri ini adalah 0.

Mode pencarian yang digunakan oleh fungsi SearchPath juga dapat diatur per proses dengan memanggil fungsi SetSearchPathMode .

Fungsi SearchPath tidak disarankan sebagai metode untuk menemukan file .dll jika penggunaan output yang dimaksudkan dalam panggilan ke fungsi LoadLibrary . Ini dapat mengakibatkan menemukan file .dll yang salah karena urutan pencarian fungsi SearchPath berbeda dari urutan pencarian yang digunakan oleh fungsi LoadLibrary . Jika Anda perlu menemukan dan memuat file .dll, gunakan fungsi LoadLibrary .

Tips Dimulai dengan Windows 10, versi 1607, untuk versi unicode fungsi ini (SearchPathW), Anda dapat memilih untuk menghapus batasan MAX_PATH. Lihat bagian "Batasan Panjang Jalur Maksimum" dari Penamaan File, Jalur, dan Namespace untuk detailnya.

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 Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Catatan

Header processenv.h mendefinisikan SearchPath 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

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	processenv.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll