Fungsi WSALookupServiceNextA (winsock2.h)
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 |
|---|---|
|
Kueri mendalam dibandingkan dengan tingkat pertama saja. |
|
Mengembalikan kontainer saja. |
|
Jangan kembalikan 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 bendera RESULT_IS_ALIAS ditetapkan. |
|
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. |
[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 |
|---|---|
| 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. | |
| 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. | |
| Buffer lpqsResults terlalu kecil untuk berisi set WSAQUERYSET . | |
| Satu atau beberapa parameter yang diperlukan tidak valid atau hilang. | |
| Handel Pencarian yang ditentukan tidak valid. | |
| WS2_32.DLL belum diinisialisasi. Aplikasi harus terlebih dahulu memanggil WSAStartup sebelum memanggil fungsi Windows Sockets apa pun. | |
| Nama ditemukan dalam database, tetapi tidak ada data yang cocok dengan batasan yang diberikan. | |
| 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 |