LPNSPV2SETSERVICEEX fungsi panggilan balik (ws2spi.h)

Artikel
08/28/2023

Fungsi NSPv2SetServiceEx mendaftarkan atau membatalkan pendaftaran nama atau instans layanan dalam namespace penyedia layanan namespace penyedia versi-2 (NSPv2).

Sintaks

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Parameter

[in] hAsyncCall

Handel yang dikembalikan dari panggilan sebelumnya ke NSPv2LookupServiceBegin yang digunakan untuk panggilan asinkron.

[in] lpProviderId

Penunjuk ke GUID penyedia namespace tertentu tempat nama atau layanan terdaftar.

[in] lpqsRegInfo

Informasi properti yang akan diperbarui saat pendaftaran.

[in] essOperation

Jenis operasi yang diminta.

Parameter ini dapat menjadi salah satu nilai dari jenis enumerasi WSAESETSERVICEOP yang ditentukan dalam file header Winsock2.h .

Nilai	Makna
RNRSERVICE_REGISTER 0	Daftarkan layanan. Untuk namespace Service Advertising Protocol (SAP) yang digunakan dalam lingkungan NetWare, ini berarti mengirim siaran berkala. Ini adalah NOP untuk namespace Domain Name System (DNS). Untuk penyimpanan data persisten, ini berarti memperbarui informasi alamat.
RNRSERVICE_DEREGISTER 1	Batalkan pendaftaran layanan. Untuk namespace layanan SAP, ini berarti berhenti mengirim siaran berkala. Ini adalah NOP untuk namespace DNS. Untuk penyimpanan data persisten, ini berarti menghapus informasi alamat.
RNRSERVICE_DELETE 2	Hapus layanan dari nama dinamis dan ruang persisten. Untuk layanan yang diwakili oleh beberapa struktur CSADDR_INFO (menggunakan bendera SERVICE_MULTIPLE), hanya alamat yang disediakan yang akan dihapus, dan ini harus cocok dengan struktur CSADDR_INFO yang sesuai yang disediakan ketika layanan terdaftar.

[in] dwControlFlags

Sekumpulan bendera yang mengontrol operasi yang diminta.

Nilai yang mungkin untuk parameter ini ditentukan dalam file header Winsock2.h .

Nilai	Makna
SERVICE_MULTIPLE 0x00000001	Mengontrol cakupan operasi. Ketika nilai ini diatur, tindakan hanya dilakukan pada set alamat yang diberikan. Operasi register tidak membatalkan alamat yang ada dan operasi pembatalan pendaftaran hanya membatalkan set alamat yang diberikan. Ketika nilai ini tidak ada, alamat layanan dikelola sebagai grup. Register atau deregister membatalkan semua alamat yang ada sebelum menambahkan set alamat yang diberikan.

Nilai

Makna

SERVICE_MULTIPLE

0x00000001

Mengontrol cakupan operasi.

Ketika nilai ini diatur, tindakan hanya dilakukan pada set alamat yang diberikan. Operasi register tidak membatalkan alamat yang ada dan operasi pembatalan pendaftaran hanya membatalkan set alamat yang diberikan.

Ketika nilai ini tidak ada, alamat layanan dikelola sebagai grup. Register atau deregister membatalkan semua alamat yang ada sebelum menambahkan set alamat yang diberikan.

[in] lpvClientSessionArg

Penunjuk ke sesi klien.

Nilai kembali

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
WSA_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk melakukan operasi ini.
WSAEACCES	Rutinitas panggilan tidak memiliki hak istimewa yang memadai untuk menginstal layanan.
WSAEINVAL	Satu atau beberapa parameter tidak valid, atau hilang, untuk penyedia ini.
WSAEOPNOTSUPP	Operasi ini tidak didukung. Kesalahan ini dikembalikan jika penyedia namespace tidak mengimplementasikan fungsi ini. Kesalahan ini juga dapat dikembalikan jika dwControlCode yang ditentukan adalah perintah yang tidak dikenali.
WSASERVICE_NOT_FOUND	Layanan tidak diketahui. Layanan tidak dapat ditemukan di namespace yang ditentukan.

Keterangan

Fungsi NSPv2SetServiceEx 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 NSPv2SetServiceEx hanya dapat digunakan untuk operasi pada penyedia namespace NS_EMAIL.

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. Argumen sesi klien ini dapat diteruskan ke fungsi NSPv2SetServiceEx dalam parameter lpvClientSessionArg .

Fungsi NSPv2SetServiceEx bersifat opsional, tergantung pada persyaratan penyedia NSPv2. Jika fungsi NSPv2SetServiceEx tidak diimplementasikan, maka penunjuk fungsi NSPv2 dapat ke fungsi stub yang selalu mengembalikan NO_ERROR.

Tabel berikut mencantumkan kemungkinan kombinasi nilai untuk parameter essOperation dan dwControlFlags .

essOperation	dwControlFlags	Layanan sudah ada	Layanan tidak ada
RNRSERVICE_REGISTER	Tidak ada	Menimpa objek . Hanya menggunakan alamat yang ditentukan. Objek TERDAFTAR.	Membuat objek baru. Hanya menggunakan alamat yang ditentukan. Objek TERDAFTAR.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Updates objek. Menambahkan alamat baru ke set yang sudah ada. Objek TERDAFTAR.	Membuat objek baru. Menggunakan semua alamat yang ditentukan. Objek TERDAFTAR.
RNRSERVICE_DEREGISTER	Tidak ada	Menghapus semua alamat, tetapi tidak menghapus objek dari namespace. Objek TIDAK TERDAFTAR.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Updates objek. Hanya menghapus alamat yang ditentukan. Hanya tandai objek sebagai DEREGISTERED jika tidak ada alamat. Tidak menghapus dari namespace layanan.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Tidak ada	Menghapus objek dari namespace layanan.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Hanya menghapus alamat yang ditentukan. Hanya menghapus objek dari namespace jika tidak ada alamat yang tersisa.	WSASERVICE_NOT_FOUND

Ketika parameter dwControlFlags diatur ke SERVICE_MULTIPLE, ini memungkinkan aplikasi untuk mengelola alamatnya secara independen. Ini berguna ketika aplikasi harus mengelola protokolnya satu per satu atau ketika layanan berada di lebih dari satu komputer. Misalnya, ketika layanan menggunakan lebih dari satu protokol, satu soket mendengarkan dapat dibatalkan, tetapi soket lainnya tetap beroperasi. Dalam contoh ini, layanan dapat membatalkan pendaftaran alamat yang dibatalkan tanpa memengaruhi alamat lain.

Saat menggunakan SERVICE_MULTIPLE, aplikasi tidak boleh membiarkan alamat lama tetap berada di objek . Ini dapat terjadi jika aplikasi dibatalkan tanpa mengeluarkan permintaan RNRSERVICE_DEREGISTER . Ketika layanan mendaftar, layanan harus menyimpan alamatnya. Pada panggilan berikutnya, layanan harus secara eksplisit membatalkan pendaftaran alamat lama ini sebelum mendaftarkan alamat baru.

Jika fungsi NSPv2SetServiceEx tidak diimplementasikan, maka panggilan ke fungsi tersebut harus disadap oleh fungsi stub yang mengembalikan WSAEOPNOTSUPP. Penunjuk fungsi NSPv2 ke fungsi NSPv2SetServiceEx yang tidak tertandingi dalam struktur NSPV2_ROUTINE harus menunjuk ke fungsi stub.

Properti Layanan

Tabel berikut ini mencantumkan WSAQUERYSET2 nama anggota dan menjelaskan bagaimana data properti layanan diwakili. Anggota berlabel opsional dan bergantung pada persyaratan penyedia NSPv2 dapat disediakan sebagai penunjuk **NULL** ketika tidak digunakan oleh penyedia namespace layanan.

nama anggota WSAQUERYSET2	Deskripsi properti layanan
dwSize	Atur ke sizeof(WSAQUERYSET2). Ini adalah mekanisme penerapan versi.
lpszServiceInstanceName	String yang berisi nama instans layanan.
lpVersion	Nomor versi instans layanan. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
lpszComment	String komentar. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
dwNameSpace	Pengidentifikasi namespace. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
lpNSProviderId	Pengidentifikasi penyedia. Perhatikan bahwa pengidentifikasi penyedia namespace juga diteruskan dalam parameter lpProviderId . 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. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
lpafpProtocols	Array struktur AFPROTOCOLS . 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	Jumlah elemen dalam array struktur CSADDR_INFO yang dirujuk oleh lpcsaBuffer.
lpcsaBuffer	Penunjuk ke array struktur CSADDR_INFO yang berisi alamat atau alamat yang didengarkan layanan.
dwOutputFlags	Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
lpBlob	Penunjuk ke entitas khusus penyedia. Anggota ini diperlukan untuk namespace NS_EMAIL. Anggota ini bersifat opsional, tergantung pada persyaratan untuk penyedia layanan NSPv2 lainnya.

**Catatan** Ini dapat diterima bagi anggota **iProtocol** dari struktur CSADDR_INFO untuk berisi konstanta manifes **IPROTOCOL_ANY**, yang menunjukkan nilai kartubebas. Penyedia namespace harus menggantikan nilai yang dapat diterima untuk keluarga alamat dan jenis soket yang diberikan.

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