LPNSPV2LOOKUPSERVICEBEGIN fungsi panggilan balik (ws2spi.h)
Fungsi NSPv2LookupServiceBegin memulai kueri klien penyedia layanan namespace versi-2 yang dibatasi oleh informasi yang terkandung dalam struktur WSAQUERYSET2 .
Sintaks
LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;
INT Lpnspv2lookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSET2W lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPVOID lpvClientSessionArg,
[out] LPHANDLE lphLookup
)
{...}
Parameter
[in] lpProviderId
Penunjuk ke pengidentifikasi untuk penyedia layanan namespace layanan untuk dikueri.
[in] lpqsRestrictions
Penunjuk ke kriteria pencarian. Lihat Keterangan.
[in] dwControlFlags
Sekumpulan bendera yang memengaruhi pencarian. Parameter ini dapat menjadi kombinasi dari nilai berikut yang ditentukan dalam file header Winsock2.h .
| Nilai | Makna |
|---|---|
|
Mengkueri hierarki penyedia dibandingkan dengan tingkat pertama saja. |
|
Mengembalikan kontainer saja. |
|
Tidak mengembalikan kontainer. |
|
Jika memungkinkan, mengembalikan hasil dalam urutan jarak. Ukuran jarak adalah spesifik penyedia. |
|
Mengambil nama sebagai **lpszServiceInstanceName**. |
|
Mengambil jenis sebagai **lpServiceClassId**. |
|
Mengambil versi sebagai **lpVersion**. |
|
Mengambil komentar sebagai **lpszComment**. |
|
Mengambil alamat sebagai **lpcsaBuffer**. |
|
Mengambil data privat sebagai **lpBlob**. |
|
Setiap informasi alias yang tersedia akan dikembalikan dalam panggilan berturut-turut ke NSPv2LookupServiceNextEx, dan setiap alias yang dikembalikan akan memiliki set bendera **RESULT_IS_ALIAS**. |
|
Mengambil string kueri sebagai **lpszQueryString**. |
|
Mengambil informasi termasuk nama, jenis, versi, komentar, alamat, blob, alias, dan string kueri. |
|
Jika penyedia memiliki informasi cache, abaikan cache dan kueri namespace itu sendiri. |
|
Digunakan sebagai nilai untuk parameter dwControlFlags di NSPv2LookupServiceNextEx. Mengatur bendera ini menginstruksikan penyedia untuk membuang tataan hasil terakhir, yang terlalu besar untuk buffer yang disediakan, dan melanjutkan ke tataan hasil berikutnya. |
|
Menunjukkan bahwa penyedia namespace harus menyertakan hasil non-otoritatif untuk nama. |
|
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. |
|
Menunjukkan bahwa penyedia namespace harus menggunakan kueri yang aman. Opsi ini hanya berlaku untuk permintaan kueri nama. |
|
Menunjukkan bahwa penyedia namespace harus mengembalikan nama pilihan saja. |
|
Menunjukkan bahwa penyedia namespace harus mengembalikan konfigurasi alamat. |
|
Menunjukkan bahwa penyedia namespace harus mengembalikan alamat ganda. Opsi ini hanya berlaku untuk soket mode ganda (alamat yang dipetakan IPv6 dan IPv4). |
|
Menunjukkan bahwa penyedia namespace harus menonaktifkan pengodean Nama Domain Internasional otomatis.
Nilai ini didukung pada Windows 8 dan Windows Server 2012 |
[out] lpvClientSessionArg
Penunjuk ke sesi klien.
[out] lphLookup
Penunjuk ke handel yang akan digunakan dalam panggilan berikutnya ke NSPv2LookupServiceNextEx untuk mengambil kumpulan hasil.
Mengembalikan nilai
Fungsi harus mengembalikan NO_ERROR (nol) jika rutinitas berhasil. Ini harus mengembalikan SOCKET_ERROR (yaitu, 1) jika rutinitas gagal dan harus mengatur kode kesalahan yang sesuai menggunakan WSASetLastError.
| Kode kesalahan | Makna |
|---|---|
| Satu atau beberapa parameter tidak valid, atau hilang, untuk penyedia ini. | |
| Nama ditemukan dalam database, tetapi tidak memiliki data terkait yang benar yang diselesaikan. | |
| Layanan ini tidak diketahui. Layanan tidak dapat ditemukan di namespace yang ditentukan. | |
| Tidak tersedia cukup memori untuk melakukan operasi ini. |
Keterangan
Fungsi NSPv2LookupServiceBegin digunakan sebagai bagian dari arsitektur penyedia layanan namespace versi-2 (NSPv2) yang tersedia di Windows Vista dan yang lebih baru.
Pada Windows Vista dan Windows Server 2008, fungsi NSPv2LookupServiceBegin hanya dapat digunakan untuk operasi pada penyedia namespace layanan NS_EMAIL.
Fungsi NSPv2LookupServiceBegin hanya mengembalikan handel, yang harus digunakan oleh panggilan berikutnya ke NSPv2LookupServiceNextEx 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.
Fungsi NSPv2Startup dipanggil setiap kali proses klien baru dimulai menggunakan penyedia namespace layanan. Penyedia dapat menggunakan argumen sesi klien yang diarahkan oleh parameter ppvClientSessionArg untuk menyimpan informasi tentang sesi ini. Jika nilai ditentukan untuk argumen sesi klien dalam panggilan ke fungsi NSPv2Startup , argumen sesi klien yang sama ini diteruskan dalam parameter lpvClientSessionArg ke fungsi NSPv2LookupServiceBegin .
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. Tidak peduli apa artinya lain penyedia layanan nama memiliki untuk menemukan kontainer, LUP_CONTAINERS dan LUP_NOCONTAINERS diutamakan. Oleh karena itu, jika pembatasan kueri diberikan yang mencakup kontainer, menentukan LUP_NOCONTAINERS akan mencegah item kontainer dikembalikan. Demikian pula, apa pun batasan 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 = NSPv2LookupServiceBegin(
lpProviderId,
lpqsRestrictions,
LUP_CONTAINERS,
lpClientSession,
lphLookup);
diikuti oleh nomor panggilan NSPv2LookupServiceNextEx 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 NSPv2LookupServiceBegin berikutnya menggunakan kontainer yang dikembalikan dari panggilan sebelumnya.
Membentuk Kueri
Struktur WSAQUERYSET2 digunakan sebagai parameter input untuk NSPv2LookupServiceBegin untuk memenuhi syarat kueri. Tabel berikut mencantumkan **WSAQUERYSET2** nama anggota dan menjelaskan bagaimana **WSAQUERYSET2** digunakan untuk membuat kueri. Anggota berlabel opsional dan bergantung pada persyaratan penyedia NSPv2 dapat disediakan sebagai penunjuk **NULL** ketika tidak digunakan sebagai kriteria pencarian oleh penyedia namespace layanan. Untuk informasi selengkapnya, lihat Struktur Data Terkait Kueri.| nama anggota WSAQUERYSET2 | Interpretasi kueri |
|---|---|
| **dwSize** | Akan diatur ke sizeof(WSAQUERYSET2). Ini adalah mekanisme penerapan versi. |
| **lpszServiceInstanceName** | String yang berisi nama layanan. Semantik untuk kartubebas dalam string tidak ditentukan, tetapi dapat didukung oleh penyedia namespace layanan tertentu. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **lpVersion** | Nomor versi yang diinginkan yang menyediakan semantik perbandingan versi (yaitu, versi harus sama persis, atau versi tidak boleh kurang dari nilai yang disediakan). Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **lpszComment** | Anggota ini diabaikan untuk kueri. |
| **dwNameSpace** | Pengidentifikasi namespace layanan tunggal untuk membatasi pencarian, atau **NS_ALL** untuk menyertakan semua namespace layanan. |
| **lpNSProviderId** | GUID penyedia namespace layanan tertentu yang membatasi kueri hanya untuk penyedia ini. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **lpszContext** | Titik awal kueri dalam namespace hierarkis. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **dwNumberOfProtocols** | Ukuran, dalam byte, dari jumlah entri dalam array batasan protokol. Anggota ini bisa nol. |
| **lpafpProtocols** | 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 dapat memberikan informasi tentang layanan apa pun yang menggunakan protokol yang sesuai, terlepas dari keluarga alamat. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **lpszQueryString** | Beberapa namespace (seperti whois++) mendukung kueri kaya seperti SQL yang terkandung dalam string teks sederhana. Parameter ini digunakan untuk menentukan string tersebut. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
| **dwNumberOfCsAddrs** | Anggota ini diabaikan untuk kueri. |
| **lpcsaBuffer** | Anggota ini diabaikan untuk kueri. |
| **dwOutputFlags** | Anggota ini diabaikan untuk kueri. |
| **lpBlob** | Penunjuk ke entitas khusus penyedia. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2. |
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | ws2spi.h |