Fungsi WSALookupServiceBeginA (winsock2.h)
Fungsi WSALookupServiceBegin memulai kueri klien yang dibatasi oleh informasi yang terkandung dalam struktur WSAQUERYSET . WSALookupServiceBegin hanya mengembalikan handel, yang harus digunakan oleh panggilan berikutnya ke WSALookupServiceNext untuk mendapatkan hasil aktual.
Sintaks
INT WSAAPI WSALookupServiceBeginA(
[in] LPWSAQUERYSETA lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
Parameter
[in] lpqsRestrictions
Penunjuk ke kriteria pencarian. Lihat Keterangan untuk detailnya.
[in] dwControlFlags
Sekumpulan bendera yang mengontrol kedalaman pencarian.
Nilai yang didukung untuk parameter dwControlFlags didefinisikan dalam file header Winsock2.h dan dapat menjadi kombinasi dari opsi berikut.
| Bendera | Makna |
|---|---|
|
Kueri sedalam-dalamnya dibandingkan dengan tingkat pertama saja. |
|
Mengembalikan kontainer saja. |
|
Jangan 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 WSALookupServiceNext, dan setiap alias yang dikembalikan akan memiliki set bendera RESULT_IS_ALIAS. |
|
Mengambil string kueri yang digunakan untuk permintaan. |
|
Sekumpulan bendera yang mengambil semua nilai LUP_RETURN_*. |
|
Digunakan sebagai nilai untuk parameter dwControlFlags di WSALookupServiceNext. Mengatur bendera ini menginstruksikan penyedia untuk membuang tataan hasil terakhir, yang terlalu besar untuk buffer yang ditentukan, dan melanjutkan ke tataan hasil berikutnya. |
|
Jika penyedia telah menyimpan cache informasi, abaikan cache, dan kueri namespace itu sendiri. |
|
Ini menunjukkan apakah respons utama berada di bagian jarak jauh atau lokal dari struktur CSADDR_INFO . Bagian lain harus dapat digunakan dalam kedua kasus. |
[out] lphLookup
Handel yang akan digunakan saat memanggil WSALookupServiceNext untuk mulai mengambil kumpulan hasil.
Nilai kembali
Nilai yang dikembalikan adalah nol jika operasi berhasil. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan nomor kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.
| Kode kesalahan | Makna |
|---|---|
| Memori tidak cukup untuk melakukan operasi. | |
| Satu atau beberapa parameter hilang atau tidak valid untuk penyedia ini. | |
| Nama ditemukan dalam database tetapi tidak ada data yang cocok dengan batasan yang diberikan. | |
| WS2_32.DLL belum diinisialisasi. Aplikasi harus terlebih dahulu memanggil WSAStartup sebelum memanggil fungsi Windows Sockets apa pun. | |
|
Tidak ada layanan seperti itu yang diketahui. Layanan tidak dapat ditemukan di ruang nama yang ditentukan.
Kesalahan ini dikembalikan untuk permintaan penemuan layanan bluetooth jika tidak ada perangkat bluetooth jarak jauh yang ditemukan. |
Keterangan
Parameter lpqsRestrictions menunjuk ke buffer yang berisi struktur WSAQUERYSET . Minimal, anggota dwSizeWSAQUERYSET harus diatur ke panjang buffer sebelum memanggil fungsi WSALookupServiceBegin . Aplikasi dapat membatasi kueri dengan menentukan anggota lain di WSAQUERYSET.
Dalam kebanyakan kasus, aplikasi yang hanya tertarik pada protokol transportasi tertentu harus membatasi kueri mereka berdasarkan keluarga alamat dan protokol menggunakan anggota dwNumberOfProtocols dan lpafpProtocolsdari WSAQUERYSET daripada dengan menspesifikasikan namespace di anggota dwNameSpace .
Informasi tentang protokol transportasi jaringan yang didukung dapat diretreif menggunakan fungsi EnumProtocols, WSAEnumProtocols, WSCEnumProtocols, atau WSCEnumProtocols32 .
Dimungkinkan juga untuk membatasi kueri ke satu namespace layanan. Misalnya, kueri yang hanya menginginkan hasil dari DNS (bukan hasil dari file host lokal dan layanan penamaan lainnya) akan mengatur anggota dwNameSpace ke NS_DNS. Misalnya, penemuan perangkat bluetooth akan mengatur anggota dwNameSpace ke NS_BTH.
Aplikasi juga dapat membatasi kueri ke penyedia namespace tertentu dengan menentukan penunjuk ke GUID untuk penyedia di anggota lpNSProviderId .
Informasi tentang penyedia namespace layanan di komputer lokal dapat diambil menggunakan fungsi WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32, atau WSCEnumNameSpaceProvidersEx32 .
Jika LUP_CONTAINERS ditentukan dalam panggilan, nilai pembatasan lainnya harus dihindari. Jika ada yang ditentukan, terserah penyedia layanan nama untuk memutuskan apakah dapat mendukung pembatasan ini atas kontainer. Jika tidak dapat, itu harus mengembalikan kesalahan.
Beberapa penyedia layanan nama dapat memiliki cara lain untuk menemukan kontainer. Misalnya, kontainer mungkin semuanya dari beberapa jenis terkenal, atau sekumpulan jenis terkenal, dan oleh karena itu pembatasan kueri dapat dibuat untuk menemukannya. Tidak peduli apa artinya penyedia layanan nama memiliki 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, tidak peduli pembatasan kueri, jika LUP_CONTAINERS diberikan, hanya kontainer yang harus dikembalikan. Jika namespace layanan tidak mendukung kontainer, dan LUP_CONTAINERS ditentukan, namespace hanya harus mengembalikan WSANO_DATA.
Metode yang disukai untuk mendapatkan kontainer dalam kontainer lain, adalah panggilan:
dwStatus = WSALookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
Panggilan ini diikuti dengan nomor panggilan WSALookupServiceNext yang diperlukan. 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 WSALookupServiceBegin berikutnya menggunakan kontainer yang dikembalikan dari panggilan sebelumnya.
Seperti disebutkan di atas, struktur WSAQUERYSET digunakan sebagai parameter input ke WSALookupBegin untuk memenuhi syarat kueri. Tabel berikut menunjukkan bagaimana WSAQUERYSET digunakan untuk membuat kueri. Ketika parameter ditandai sebagai (Opsional) penunjuk NULL dapat ditentukan, menunjukkan bahwa parameter tidak akan digunakan sebagai kriteria pencarian. Lihat bagian Struktur Data Terkait Kueri untuk informasi tambahan.
| Anggota WSAQUERYSET | Interpretasi kueri |
|---|---|
| dwSize | Harus diatur ke sizeof(WSAQUERYSET). Ini adalah mekanisme penerapan versi. |
| dwOutputFlags | Diabaikan untuk kueri. |
| lpszServiceInstanceName | (Opsional) String yang dirujuk berisi nama layanan. Semantik untuk wildcard dalam string tidak ditentukan, tetapi dapat didukung oleh penyedia namespace tertentu. |
| lpServiceClassId | (Diperlukan) 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 ditentukan). |
| lpszComment | Diabaikan untuk kueri. |
|
dwNameSpace
Lihat Catatan penting yang mengikuti. |
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 | (Opsional) Menentukan titik awal kueri dalam namespace hierarkis. |
| dwNumberOfProtocols | Ukuran array batasan protokol, bisa nol. |
| lpafpProtocols | (Opsional) Mereferensikan array struktur AFPROTOCOLS . Hanya layanan yang menggunakan protokol ini yang akan dikembalikan. |
| lpszQueryString | (Opsional) Beberapa namespace (seperti whois++) mendukung kueri seperti SQL yang diperkaya yang terkandung dalam string teks sederhana. Parameter ini digunakan untuk menentukan string tersebut. |
| dwNumberOfCsAddrs | Diabaikan untuk kueri. |
| lpcsaBuffer | Diabaikan untuk kueri. |
| lpBlob | (Opsional) Ini adalah penunjuk ke entitas khusus penyedia. |
Windows 8.1 dan Windows Server 2012 R2: Fungsi WSALookupServiceBeginW didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Catatan
Header winsock2.h mendefinisikan WSALookupServiceBegin sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winsock2.h |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.dll |