Fungsi FtpFindFirstFileW (wininet.h)

Artikel
03/08/2023

Mencari direktori yang ditentukan dari sesi FTP yang diberikan. Entri file dan direktori dikembalikan ke aplikasi dalam struktur WIN32_FIND_DATA .

Sintaks

HINTERNET FtpFindFirstFileW(
  [in]  HINTERNET          hConnect,
  [in]  LPCWSTR            lpszSearchFile,
  [out] LPWIN32_FIND_DATAW lpFindFileData,
  [in]  DWORD              dwFlags,
  [in]  DWORD_PTR          dwContext
);

Parameter

[in] hConnect

Menangani sesi FTP yang dikembalikan dari InternetConnect.

[in] lpszSearchFile

Penunjuk ke string yang dihentikan null yang menentukan jalur direktori atau nama file yang valid untuk sistem file server FTP. String dapat berisi kartubebas, tetapi tidak ada spasi kosong yang diizinkan. Jika nilai lpszSearchFile adalah NULL atau jika itu adalah string kosong, fungsi menemukan file pertama di direktori saat ini di server.

[out] lpFindFileData

Arahkan ke struktur WIN32_FIND_DATA yang menerima informasi tentang file atau direktori yang ditemukan.

[in] dwFlags

Mengontrol perilaku fungsi ini. Parameter ini bisa menjadi kombinasi dari nilai berikut.

INTERNET_FLAG_HYPERLINK

INTERNET_FLAG_NEED_FILE

INTERNET_FLAG_NO_CACHE_WRITE

INTERNET_FLAG_RELOAD

INTERNET_FLAG_RESYNCHRONIZE

[in] dwContext

Penunjuk ke variabel yang menentukan nilai yang ditentukan aplikasi yang mengaitkan pencarian ini dengan data aplikasi apa pun. Parameter ini hanya digunakan jika aplikasi telah memanggil InternetSetStatusCallback untuk menyiapkan fungsi panggilan balik status.

Mengembalikan nilai

Mengembalikan handel yang valid untuk permintaan jika enumerasi direktori berhasil dimulai, atau mengembalikan NULL sebaliknya. Untuk mendapatkan pesan kesalahan tertentu, panggil GetLastError. Jika GetLastError mengembalikan ERROR_INTERNET_EXTENDED_ERROR, seperti dalam kasus di mana fungsi tidak menemukan file yang cocok, panggil fungsi InternetGetLastResponseInfo untuk mengambil teks kesalahan yang diperluas, seperti yang didokumenkan dalam Menangani Kesalahan.

Keterangan

Untuk FtpFindFirstFile, waktu file yang dikembalikan dalam struktur WIN32_FIND_DATA berada di zona waktu lokal, bukan dalam format waktu universal terkoordinasi (UTC).

FtpFindFirstFile mirip dengan fungsi FindFirstFile . Namun, perhatikan bahwa hanya satu FtpFindFirstFile yang dapat terjadi pada satu waktu dalam sesi FTP tertentu. Oleh karena itu, enumerasi berkorelasi dengan handel sesi FTP. Ini karena protokol FTP hanya memungkinkan enumerasi direktori tunggal per sesi.

Setelah memanggil FtpFindFirstFile dan sampai memanggil InternetCloseHandle, aplikasi tidak dapat memanggil FtpFindFirstFile lagi pada handel sesi FTP yang diberikan. Jika panggilan dilakukan ke FtpFindFirstFile pada handel tersebut, fungsi gagal dengan ERROR_FTP_TRANSFER_IN_PROGRESS. Setelah aplikasi panggilan selesai menggunakan handel HINTERNET yang dikembalikan oleh FtpFindFirstFile, aplikasi harus ditutup menggunakan fungsi InternetCloseHandle .

Setelah memulai enumerasi direktori dengan FtpFindFirstFile, fungsi InternetFindNextFile dapat digunakan untuk melanjutkan enumerasi.

Karena protokol FTP tidak menyediakan cara enumerasi standar, beberapa informasi umum tentang file, seperti tanggal dan waktu pembuatan file, tidak selalu tersedia atau benar. Ketika ini terjadi, FtpFindFirstFile dan InternetFindNextFile mengisi informasi yang tidak tersedia dengan tebakan terbaik berdasarkan informasi yang tersedia. Misalnya, tanggal pembuatan dan akses terakhir sering sama dengan tanggal modifikasi file.

Aplikasi tidak dapat memanggil FtpFindFirstFile antara panggilan ke FtpOpenFile dan InternetCloseHandle.

Seperti semua aspek lain dari Api WinINet, fungsi ini tidak dapat dipanggil dengan aman dari dalam DllMain atau konstruktor dan destruktor objek global.

Catatan WinINet tidak mendukung implementasi server. Selain itu, itu tidak boleh digunakan dari layanan. Untuk implementasi atau layanan server, gunakan Microsoft Windows HTTP Services (WinHTTP).

Catatan

Header wininet.h mendefinisikan FtpFindFirstFile 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 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	wininet.h
Pustaka	Wininet.lib
DLL	Wininet.dll

Lihat juga

Sesi FTP

Fungsi WinINet

Bagikan melalui