Fungsi panggilan balik LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

Artikel
08/28/2023

Fungsi NSPLookupServiceBegin memulai kueri klien penyedia layanan nama yang dibatasi oleh informasi yang terkandung dalam struktur WSAQUERYSET .

NSPLookupServiceBegin hanya mengembalikan handel, yang harus digunakan oleh panggilan berikutnya ke NSPLookupServiceNext untuk mendapatkan hasil aktual. Karena operasi ini tidak dapat dibatalkan, operasi harus diimplementasikan untuk dijalankan dengan cepat. Meskipun dapat diterima untuk memulai kueri jaringan, fungsi ini seharusnya tidak memerlukan respons untuk berhasil dikembalikan.

Sintaks

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Parameter

[in] lpProviderId

Penunjuk ke pengidentifikasi penyedia layanan nama untuk dikueri.

[in] lpqsRestrictions

Penunjuk ke kriteria pencarian. Lihat Keterangan.

[in] lpServiceClassInfo

Penunjuk ke struktur WSASERVICECLASSINFO yang berisi informasi skema untuk layanan.

[in] dwControlFlags

Nilai yang mengontrol kedalaman pencarian.

Nilai	Makna
LUP_DEEP 0x0001	Mengkueri hierarki penyedia dibandingkan dengan tingkat pertama saja.
LUP_CONTAINERS 0x0002	Mengembalikan kontainer saja.
LUP_NOCONTAINERS 0x0004	Tidak mengembalikan kontainer.
LUP_NEAREST 0x0008	Jika memungkinkan, mengembalikan hasil dalam urutan jarak. Ukuran jarak adalah spesifik penyedia.
LUP_RETURN_NAME 0x0010	Mengambil nama sebagai lpszServiceInstanceName.
LUP_RETURN_TYPE 0x0020	Mengambil jenis sebagai lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Mengambil versi sebagai lpVersion.
LUP_RETURN_COMMENT 0x0080	Mengambil komentar sebagai lpszComment.
LUP_RETURN_ADDR 0x0100	Mengambil alamat sebagai lpcsaBuffer.
LUP_RETURN_BLOB 0x0200	Mengambil data privat sebagai lpBlob.
LUP_RETURN_ALIASES 0x0400	Setiap informasi alias yang tersedia akan dikembalikan dalam panggilan berturut-turut ke NSPLookupServiceNext, dan setiap alias yang dikembalikan akan memiliki set bendera RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Mengambil string kueri sebagai lpszQueryString.
LUP_RETURN_ALL 0x0ff0	Mengambil informasi termasuk nama, jenis, versi, komentar, alamat, blob, alias, dan string kueri.
LUP_FLUSHCACHE 0x1000	Jika penyedia memiliki informasi cache, abaikan cache dan kueri namespace itu sendiri.
LUP_FLUSHPREVIOUS 0x2000	Digunakan sebagai nilai untuk parameter dwControlFlags di NSPLookupServiceNext. Mengatur bendera ini menginstruksikan penyedia untuk membuang tataan hasil terakhir, yang terlalu besar untuk buffer yang disediakan, dan melanjutkan ke tataan hasil berikutnya.
LUP_NON_AUTHORITATIVE 0x4000	Menunjukkan bahwa penyedia namespace harus menyertakan hasil non-otoritatif untuk nama.
LUP_RES_RESERVICE 0x8000	Menunjukkan apakah respons utama berada di bagian jarak jauh atau lokal dari struktur CSADDR_INFO . Bagian lain harus dapat digunakan dalam kedua kasus. Opsi ini hanya berlaku untuk permintaan instans layanan.
LUP_SECURE 0x8000	Menunjukkan bahwa penyedia namespace harus menggunakan kueri aman. Opsi ini hanya berlaku untuk permintaan kueri nama.
LUP_RETURN_PREFERRED_NAMES 0x10000	Menunjukkan bahwa penyedia namespace harus mengembalikan hanya nama pilihan.
LUP_ADDRCONFIG 0x100000	Menunjukkan bahwa penyedia namespace harus mengembalikan konfigurasi alamat.
LUP_DUAL_ADDR 0x200000	Menunjukkan bahwa penyedia namespace harus mengembalikan alamat ganda. Opsi ini hanya berlaku untuk soket mode ganda (alamat yang dipetakan IPv6 dan IPv4).

[out] lphLookup

Penunjuk ke handel yang akan digunakan dalam panggilan berikutnya ke NSPLookupServiceNext untuk mengambil kumpulan hasil.

Mengembalikan nilai

Fungsi harus mengembalikan NO_ERROR (nol) jika rutinitas berhasil. Ini harus mengembalikan SOCKET_ERROR (–1) jika rutinitas gagal dan harus mengatur kode kesalahan yang sesuai menggunakan WSASetLastError.

Kode kesalahan	Makna
WSA_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk melakukan operasi ini.
WSAEINVAL	Satu atau beberapa parameter tidak valid, atau hilang, untuk penyedia ini.
WSAEOPNOTSUPP	Operasi tidak didukung. Kesalahan ini dikembalikan jika penyedia namespace tidak menerapkan fungsi ini.
WSANO_DATA	Nama ditemukan dalam database, tetapi tidak memiliki data terkait yang benar yang diselesaikan.
WSASERVICE_NOT_FOUND	Layanan tidak diketahui. Layanan tidak dapat ditemukan di namespace yang ditentukan.

Keterangan

Jika LUP_CONTAINERS ditentukan dalam panggilan, hindari semua nilai pembatasan lainnya. Jika ada yang disediakan, penyedia layanan nama harus memutuskan apakah dapat mendukung pembatasan ini atas kontainer. Jika tidak, itu harus mengembalikan kesalahan.

Beberapa penyedia layanan nama mungkin memiliki cara lain untuk menemukan kontainer. Misalnya, kontainer semuanya dapat berupa beberapa jenis terkenal, atau sekumpulan jenis terkenal, dan oleh karena itu pembatasan kueri dapat dibuat untuk menemukannya. Apa pun artinya penyedia layanan nama untuk menemukan kontainer, LUP_CONTAINERS , dan LUP_NOCONTAINERS diutamakan. Oleh karena itu, jika pembatasan kueri diberikan yang menyertakan kontainer, menentukan LUP_NOCONTAINERS akan mencegah item kontainer dikembalikan. Demikian pula, apa pun pembatasan kueri, jika LUP_CONTAINERS diberikan, hanya kontainer yang harus dikembalikan. Jika namespace tidak mendukung kontainer dan LUP_CONTAINERS ditentukan, namespace harus mengembalikan WSANO_DATA.

Metode yang disukai untuk mendapatkan kontainer dalam kontainer lain, adalah panggilan:

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

diikuti dengan nomor panggilan NSPLookupServiceNext yang disyaratkan. Ini akan mengembalikan semua kontainer yang terkandung segera dalam konteks awal; artinya, ini bukan kueri mendalam. Dengan ini, seseorang dapat memetakan struktur ruang alamat dengan menjalankan hierarki, mungkin menghitung konten kontainer yang dipilih. Penggunaan NSPLookupServiceBegin berikutnya menggunakan kontainer yang dikembalikan dari panggilan sebelumnya.

Kueri Formulir

Seperti disebutkan, struktur WSAQUERYSET digunakan sebagai parameter input ke NSPLookupServiceBegin untuk memenuhi syarat kueri. Tabel berikut mencantumkan nama anggota WSAQUERYSET dan menjelaskan bagaimana WSAQUERYSET digunakan untuk membuat kueri. Ketika anggota ditandai sebagai (Opsional) penunjuk null dapat disediakan, menunjukkan bahwa parameter tidak akan digunakan sebagai kriteria pencarian. Untuk informasi selengkapnya, lihat Struktur Data Terkait Kueri.

Nama anggota WSAQUERYSET	Interpretasi kueri
dwSize	Akan diatur ke sizeof(WSAQUERYSET). Ini adalah mekanisme penerapan versi.
dwOutputFlags	Diabaikan untuk kueri.
lpszServiceInstanceName	Pilihan. String yang dirujuk berisi nama layanan. Semantik untuk wildcard dalam string tidak ditentukan, tetapi dapat didukung oleh penyedia namespace tertentu.
lpServiceClassId	Wajib diisi. GUID yang sesuai dengan kelas layanan.
lpVersion	Opsional. Referensi nomor versi yang diinginkan dan menyediakan semantik perbandingan versi (yaitu, versi harus sama persis, atau versi tidak boleh kurang dari nilai yang disediakan).
lpszComment	Diabaikan untuk kueri.
dwNameSpace	Pengidentifikasi namespace layanan tunggal untuk membatasi pencarian, atau NS_ALL untuk menyertakan semua namespace layanan.
lpNSProviderId	Opsional. Mereferensikan GUID penyedia namespace tertentu dan membatasi kueri hanya untuk penyedia ini.
lpszContext	Pilihan. Menentukan titik awal kueri dalam namespace hierarkis.
dwNumberOfProtocols	Ukuran, dalam byte, dari jumlah entri dalam array batasan protokol, bisa nol.
lpafpProtocols	Opsional. Referensi ke array struktur AFPROTOCOLS . Hanya layanan yang menggunakan protokol ini yang akan dikembalikan. Diperbolehkan agar nilai AF_UNSPEC muncul sebagai nilai keluarga protokol, menandakan kartubebas. Penyedia namespace layanan dapat memberikan informasi tentang layanan apa pun yang menggunakan protokol yang sesuai, terlepas dari keluarga alamat.
lpszQueryString	Pilihan. Beberapa namespace (seperti whois++) mendukung kueri kaya seperti SQL yang terkandung dalam string teks sederhana. Parameter ini digunakan untuk menentukan string tersebut.
dwNumberOfCsAddrs	Diabaikan untuk kueri.
lpcsaBuffer	Diabaikan untuk kueri.
lpBlob	Pilihan. Penunjuk ke entitas khusus penyedia.

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	ws2spi.h

Lihat juga

Nama anggota WSAQUERYSET	Interpretasi kueri
dwSize	Akan diatur ke sizeof(WSAQUERYSET). Ini adalah mekanisme penerapan versi.
dwOutputFlags	Diabaikan untuk kueri.
lpszServiceInstanceName	Pilihan. String yang dirujuk berisi nama layanan. Semantik untuk wildcard dalam string tidak ditentukan, tetapi dapat didukung oleh penyedia namespace tertentu.
lpServiceClassId	Wajib diisi. GUID yang sesuai dengan kelas layanan.
lpVersion	Opsional. Referensi nomor versi yang diinginkan dan menyediakan semantik perbandingan versi (yaitu, versi harus sama persis, atau versi tidak boleh kurang dari nilai yang disediakan).
lpszComment	Diabaikan untuk kueri.
dwNameSpace	Pengidentifikasi namespace layanan tunggal untuk membatasi pencarian, atau NS_ALL untuk menyertakan semua namespace layanan.
lpNSProviderId	Opsional. Mereferensikan GUID penyedia namespace tertentu dan membatasi kueri hanya untuk penyedia ini.
lpszContext	Pilihan. Menentukan titik awal kueri dalam namespace hierarkis.
dwNumberOfProtocols	Ukuran, dalam byte, dari jumlah entri dalam array batasan protokol, bisa nol.
lpafpProtocols	Opsional. Referensi ke array struktur AFPROTOCOLS . Hanya layanan yang menggunakan protokol ini yang akan dikembalikan. Diperbolehkan agar nilai AF_UNSPEC muncul sebagai nilai keluarga protokol, menandakan kartubebas. Penyedia namespace layanan dapat memberikan informasi tentang layanan apa pun yang menggunakan protokol yang sesuai, terlepas dari keluarga alamat.
lpszQueryString	Pilihan. Beberapa namespace (seperti whois++) mendukung kueri kaya seperti SQL yang terkandung dalam string teks sederhana. Parameter ini digunakan untuk menentukan string tersebut.
dwNumberOfCsAddrs	Diabaikan untuk kueri.
lpcsaBuffer	Diabaikan untuk kueri.
lpBlob	Pilihan. Penunjuk ke entitas khusus penyedia.