Fungsi WSALookupServiceNextA (winsock2.h)

Artikel
08/27/2023

Fungsi WSALookupServiceNext dipanggil setelah mendapatkan handel dari panggilan sebelumnya ke WSALookupServiceBegin untuk mengambil informasi layanan yang diminta.

Penyedia akan meneruskan kembali struktur WSAQUERYSET di buffer lpqsResults . Klien harus terus memanggil fungsi ini sampai mengembalikan WSA_E_NO_MORE, menunjukkan bahwa semua WSAQUERYSET telah dikembalikan.

Sintaks

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA lpqsResults
);

Parameter

[in] hLookup

Handel yang dikembalikan dari panggilan sebelumnya ke WSALookupServiceBegin.

[in] dwControlFlags

Sekumpulan bendera yang mengontrol operasi. Nilai yang diteruskan dalam parameter dwControlFlags ke fungsi WSALookupServiceBegin menentukan kriteria yang mungkin. Nilai apa pun yang diteruskan dalam parameter dwControlFlags ke fungsi WSALookupServiceNext selanjutnya membatasi kriteria untuk pencarian layanan.

Saat ini, LUP_FLUSHPREVIOUS didefinisikan sebagai sarana untuk mengatasi tataan hasil yang terlalu besar. Jika aplikasi tidak (atau tidak dapat) menyediakan buffer yang cukup besar, mengatur LUP_FLUSHPREVIOUS menginstruksikan penyedia untuk membuang tataan hasil terakhir—yang terlalu besar—dan melanjutkan ke set berikutnya untuk panggilan ini.

Nilai yang didukung untuk parameter dwControlFlags didefinisikan dalam file header Winsock2.h dan dapat menjadi kombinasi dari opsi berikut.

Bendera	Makna
LUP_DEEP 0x0001	Kueri mendalam dibandingkan dengan tingkat pertama saja.
LUP_CONTAINERS 0x0002	Mengembalikan kontainer saja.
LUP_NOCONTAINERS 0x0004	Jangan kembalikan 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 WSALookupServiceNext, dan setiap alias yang dikembalikan akan memiliki bendera RESULT_IS_ALIAS ditetapkan.
LUP_RETURN_QUERY_STRING 0x0800	Mengambil string kueri yang digunakan untuk permintaan.
LUP_RETURN_ALL 0x0FF0	Sekumpulan bendera yang mengambil semua nilai LUP_RETURN_*.
LUP_FLUSHPREVIOUS 0x1000	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.
LUP_FLUSHCACHE 0x2000	Jika penyedia telah menyimpan cache informasi, abaikan cache, dan kueri namespace itu sendiri.
LUP_RES_SERVICE 0x8000	Ini menunjukkan apakah respons utama berada di bagian jarak jauh atau lokal dari struktur CSADDR_INFO . Bagian lain harus dapat digunakan dalam kedua kasus.

[in, out] lpdwBufferLength

Pada input, jumlah byte yang terkandung dalam buffer yang diarahkan oleh lpqsResults. Pada output, jika fungsi gagal dan kesalahannya adalah WSAEFAULT, maka berisi jumlah minimum byte yang akan diteruskan agar lpqsResults mengambil rekaman.

[out] lpqsResults

Penunjuk ke blok memori, yang akan berisi satu hasil yang diatur dalam struktur WSAQUERYSET saat dikembalikan.

Mengembalikan nilai

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
WSA_E_CANCELLED	Panggilan ke WSALookupServiceEnd dilakukan saat panggilan ini masih diproses. Panggilan telah dibatalkan. Data dalam buffer lpqsResults tidak terdefinisi. Di Windows Sockets versi 2, kode kesalahan yang bertentangan ditentukan untuk WSAECANCELLED (10103) dan WSA_E_CANCELLED (10111). Kode kesalahan WSAECANCELLED akan dihapus dalam versi mendatang dan hanya WSA_E_CANCELLED yang akan tetap ada. Namun, untuk Windows Sockets versi 2, aplikasi harus memeriksa WSAECANCELLED dan WSA_E_CANCELLED untuk kompatibilitas seluas mungkin dengan penyedia namespace yang menggunakan salah satu.
WSA_E_NO_MORE	Tidak ada lagi data yang tersedia. Di Windows Sockets versi 2, kode kesalahan yang bertentangan ditentukan untuk WSAENOMORE (10102) dan WSA_E_NO_MORE (10110). Kode kesalahan WSAENOMORE akan dihapus dalam versi mendatang dan hanya WSA_E_NO_MORE yang akan tetap ada. Namun, untuk Windows Sockets versi 2, aplikasi harus memeriksa WSAENOMORE dan WSA_E_NO_MORE untuk kompatibilitas seluas mungkin dengan penyedia ruang nama yang menggunakan salah satu.
WSAEFAULT	Buffer lpqsResults terlalu kecil untuk berisi set WSAQUERYSET .
WSAEINVAL	Satu atau beberapa parameter yang diperlukan tidak valid atau hilang.
WSA_INVALID_HANDLE	Handel Pencarian yang ditentukan tidak valid.
WSANOTINITIALISED	WS2_32.DLL belum diinisialisasi. Aplikasi harus terlebih dahulu memanggil WSAStartup sebelum memanggil fungsi Windows Sockets apa pun.
WSANO_DATA	Nama ditemukan dalam database, tetapi tidak ada data yang cocok dengan batasan yang diberikan.
WSA_NOT_ENOUGH_MEMORY	Memori tidak cukup untuk melakukan operasi.

Keterangan

Parameter dwControlFlags yang ditentukan dalam fungsi ini dan yang ditentukan pada saat WSALookupServiceBegin diperlakukan sebagai pembatasan untuk tujuan kombinasi. Pembatasan digabungkan antara yang ada di waktu WSALookupServiceBegin dan yang ada di waktu WSALookupServiceNext . Oleh karena itu, bendera di WSALookupServiceNext tidak pernah dapat meningkatkan jumlah data yang dikembalikan melebihi apa yang diminta di WSALookupServiceBegin, meskipun bukan kesalahan untuk menentukan lebih banyak atau lebih sedikit bendera. Bendera yang ditentukan pada WSALookupServiceNext tertentu hanya berlaku untuk panggilan tersebut.

dwControlFlags LUP_FLUSHPREVIOUS dan LUP_RES_SERVICE adalah pengecualian untuk aturan pembatasan gabungan (karena merupakan bendera perilaku alih-alih bendera pembatasan). Jika salah satu bendera ini digunakan di WSALookupServiceNext , bendera tersebut memiliki efek yang ditentukan terlepas dari pengaturan bendera yang sama di WSALookupServiceBegin.

Misalnya, jika LUP_RETURN_VERSION ditentukan di WSALookupServiceBegin penyedia layanan mengambil rekaman termasuk versi. Jika LUP_RETURN_VERSION TIDAK ditentukan di WSALookupServiceNext, informasi yang dikembalikan tidak menyertakan versi, meskipun tersedia. Tidak ada kesalahan yang dihasilkan.

Juga misalnya, jika LUP_RETURN_BLOB TIDAK ditentukan di WSALookupServiceBegin tetapi ditentukan di WSALookupServiceNext, informasi yang dikembalikan tidak menyertakan data privat. Tidak ada kesalahan yang dihasilkan.

Jika fungsi WSALookupServiceNext gagal dengan kesalahan WSAEFAULT, ini menunjukkan bahwa buffer yang ditunjukkan oleh parameter lpqsResults terlalu kecil untuk berisi hasil kueri. Buffer baru untuk WSAQUERYSET harus disediakan dengan ukuran yang ditentukan oleh nilai yang diarahkan oleh parameter lpdwBufferLength . Buffer baru untuk WSAQUERYSET ini harus memiliki beberapa anggota WSAQUERYSET yang ditentukan sebelum memanggil fungsi WSALookupServiceNext lagi. Minimal, anggota dwSizeWSAQUERYSET harus diatur ke ukuran buffer baru.

Hasil Kueri

Tabel berikut ini menjelaskan bagaimana hasil kueri diwakili dalam struktur WSAQUERYSET .

Anggota WSAQUERYSET	Interpretasi hasil
dwSize	Akan diatur ke sizeof( WSAQUERYSET). Ini digunakan sebagai mekanisme penerapan versi.
dwOutputFlags	bendera RESULT_IS_ALIAS menunjukkan ini adalah hasil alias.
lpszServiceInstanceName	String yang dirujuk berisi nama layanan.
lpServiceClassId	GUID yang sesuai dengan kelas layanan.
lpVersion	Mereferensikan nomor versi instans layanan tertentu.
lpszComment	String komentar opsional yang ditentukan oleh instans layanan.
dwNameSpace	Namespace tempat instans layanan ditemukan.
lpNSProviderId	Mengidentifikasi penyedia namespace khusus yang menyediakan hasil kueri ini.
lpszContext	Menentukan titik konteks dalam namespace hierarkis tempat layanan berada.
dwNumberOfProtocols	Tidak ditentukan untuk hasil.
lpafpProtocols	Tidak terdefinisi untuk hasil, semua informasi protokol yang diperlukan ada dalam struktur CSADDR_INFO .
lpszQueryString	Ketika dwControlFlags menyertakan LUP_RETURN_QUERY_STRING, parameter ini mengembalikan sisa lpszServiceInstanceName yang ditentukan dalam kueri asli. Misalnya, di namespace layanan yang mengidentifikasi layanan dengan nama hierarkis yang menentukan nama host dan jalur file dalam host tersebut, alamat yang dikembalikan mungkin merupakan alamat host dan sisanya yang tidak dipisahkan mungkin merupakan jalur file. Jika lpszServiceInstanceName sepenuhnya diurai dan LUP_RETURN_QUERY_STRING digunakan, parameter ini NULL atau menunjuk ke string panjang nol.
dwNumberOfCsAddrs	Menunjukkan jumlah elemen dalam array struktur CSADDR_INFO .
lpcsaBuffer	Penunjuk ke array struktur CSADDR_INFO , dengan satu alamat transportasi lengkap yang terkandung dalam setiap elemen.
lpBlob	(Opsional) Ini adalah penunjuk ke entitas khusus penyedia.

Windows Phone 8: Fungsi WSALookupServiceNextW didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi WSALookupServiceNextW didukung untuk aplikasi Windows Store pada Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Catatan

Header winsock2.h mendefinisikan WSALookupServiceNext 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


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