Fungsi WSASetServiceA (winsock2.h)

Artikel
03/13/2024

Fungsi WSASetService mendaftarkan atau menghapus dari registri instans layanan dalam satu atau beberapa namespace layanan.

Sintaks

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parameter

[in] lpqsRegInfo

Penunjuk ke informasi layanan untuk pendaftaran atau deregistrasi.

[in] essoperation

Nilai yang menentukan 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	Daftarkan layanan. Untuk SAP, ini berarti mengirimkan siaran berkala. Ini adalah NOP untuk namespace DNS. Untuk penyimpanan data persisten, ini berarti memperbarui informasi alamat.
RNRSERVICE_DEREGISTER	Hapus layanan dari registri. Untuk SAP, ini berarti berhenti mengirim siaran berkala. Ini adalah NOP untuk namespace DNS. Untuk penyimpanan data persisten, ini berarti menghapus informasi alamat.
RNRSERVICE_DELETE	Hapus layanan dari nama dinamis dan ruang persisten. Untuk layanan yang diwakili oleh beberapa struktur CSADDR_INFO (menggunakan bendera SERVICE_MULTIPLE), hanya alamat yang ditentukan yang akan dihapus, dan ini harus sama persis dengan struktur CSADDR_INFO yang sesuai yang ditentukan ketika layanan terdaftar.

[in] dwControlFlags

Nilai bendera penginstalan layanan yang lebih mengontrol operasi yang dilakukan dari fungsi WSASetService . Nilai yang mungkin untuk parameter ini didefinisikan dalam file header Winsock2.h .

Bendera	Makna
SERVICE_MULTIPLE	Mengontrol cakupan operasi. Ketika bendera ini tidak diatur, alamat layanan dikelola sebagai grup. Register atau penghapusan dari registri membatalkan semua alamat yang ada sebelum menambahkan set alamat yang diberikan. Ketika diatur, tindakan hanya dilakukan pada set alamat yang diberikan. Register tidak membatalkan alamat yang ada dan penghapusan dari registri hanya membatalkan set alamat yang diberikan.

Bendera

Makna

SERVICE_MULTIPLE

Mengontrol cakupan operasi. Ketika bendera ini tidak diatur, alamat layanan dikelola sebagai grup. Register atau penghapusan dari registri membatalkan semua alamat yang ada sebelum menambahkan set alamat yang diberikan. Ketika diatur, tindakan hanya dilakukan pada set alamat yang diberikan. Register tidak membatalkan alamat yang ada dan penghapusan dari registri hanya membatalkan set alamat yang diberikan.

Mengembalikan nilai

Nilai yang dikembalikan untuk WSASetService adalah nol jika operasi berhasil. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan nomor kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan	Makna
WSAEACCES	Rutinitas panggilan tidak memiliki hak istimewa yang memadai untuk menginstal Layanan.
WSAEINVAL	Satu atau beberapa parameter yang diperlukan tidak valid atau hilang.
WSANOTINITIALISED	Ws2_32.dll belum diinisialisasi. Aplikasi harus terlebih dahulu memanggil WSAStartup sebelum memanggil fungsi Windows Sockets apa pun.
WSA_NOT_ENOUGH_MEMORY	Memori tidak cukup untuk melakukan operasi.

Keterangan

Fungsi WSASetService dapat digunakan untuk memengaruhi penyedia namespace tertentu, semua penyedia yang terkait dengan namespace layanan tertentu, atau semua penyedia di semua namespace layanan.

Nilai yang tersedia untuk essOperation dan dwControlFlags digabungkan untuk mengontrol pengoperasian fungsi WSASetService seperti yang ditunjukkan dalam tabel berikut.

Operasi	Bendera	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 dihapus dari registri.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Updates objek . Hanya menghapus alamat yang ditentukan. Hanya menandai objek sebagai DEREGISTERED jika tidak ada alamat. Tidak menghapus objek dari namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Tidak ada	Menghapus objek dari namespace.	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

Layanan penerbitan ke direktori, seperti Layanan Direktori Aktif, dibatasi berdasarkan daftar kontrol akses (ACL). Untuk informasi selengkapnya, lihat Masalah Keamanan untuk Publikasi Layanan.

Ketika parameter dwControlFlags diatur ke SERVICE_MULTIPLE, aplikasi dapat mengelola alamatnya secara independen. Ini berguna ketika aplikasi ingin mengelola protokolnya satu per satu atau ketika layanan berada di lebih dari satu komputer. Misalnya, ketika layanan menggunakan lebih dari satu protokol, mungkin menemukan bahwa satu soket mendengarkan dibatalkan tetapi soket lainnya tetap beroperasi. Dalam hal ini, layanan dapat menghapus alamat yang dibatalkan dari registri tanpa memengaruhi alamat lain.

Ketika parameter dwControlFlags diatur ke SERVICE_MULTIPLE, aplikasi tidak boleh membiarkan alamat kedaluarsa tetap berada di objek . Ini dapat terjadi jika aplikasi membatalkan tanpa mengeluarkan permintaan DEREGISTER. Ketika layanan mendaftar, layanan harus menyimpan alamatnya. Pada pemanggilan berikutnya, layanan harus secara eksplisit menghapus alamat lama kedaluwarsa ini dari registri sebelum mendaftarkan alamat baru.

Catatan Jika string karakter ANSI digunakan, ada kemungkinan bahwa data WSAQUERYSET di lpqsRegInfo mungkin tidak berisi hasil apa pun setelah fungsi ini kembali. Ini karena versi ANSI dari metode ini, WSASetServiceA, mengonversi data ANSI di WSAQUERYSET ke Unicode secara internal, tetapi tidak mengonversi hasilnya kembali ke ANSI. Ini terutama berdampak pada transportasi yang mengembalikan "handel catatan layanan" yang digunakan untuk mengidentifikasi rekaman secara unik. Untuk mengatasi masalah ini, aplikasi harus menggunakan data string Unicode di WSAQUERYSET saat memanggil fungsi ini.

Properti Layanan

Tabel berikut ini menjelaskan bagaimana data properti layanan diwakili dalam struktur WSAQUERYSET . Bidang berlabel sebagai (Opsional) bisa berisi penunjuk null.

Anggota WSAQUERYSET	Deskripsi properti layanan
dwSize	Harus diatur ke sizeof (WSAQUERYSET). Ini adalah mekanisme penerapan versi.
dwOutputFlags	Tidak berlaku dan diabaikan.
lpszServiceInstanceName	String yang dirujuk berisi nama instans layanan.
lpServiceClassId	GUID yang sesuai dengan kelas layanan ini.
lpVersion	(Opsional) Menyediakan nomor versi instans layanan.
lpszComment	(Opsional) String komentar opsional.
dwNameSpace	Lihat tabel berikut ini.
lpNSProviderId	Lihat tabel berikut ini.
lpszContext	(Opsional) Menentukan titik awal kueri dalam namespace hierarkis.
dwNumberOfProtocols	Diabaikan.
lpafpProtocols	Diabaikan.
lpszQueryString	Diabaikan.
dwNumberOfCsAddrs	Jumlah elemen dalam array struktur CSADDR_INFO yang dirujuk oleh lpcsaBuffer.
lpcsaBuffer	Penunjuk ke array struktur CSADDR_INFO yang berisi alamat yang didengarkan layanan.
lpBlob	(Opsional) Ini adalah penunjuk ke entitas khusus penyedia.

Seperti yang diilustrasikan dalam hal berikut, kombinasi anggota dwNameSpace dan lpNSProviderId menentukan bahwa penyedia namespace dipengaruhi oleh fungsi ini.

dwNameSpace	lpNSProviderId	Cakupan dampak
Diabaikan	Non-null	Penyedia ruang nama yang ditentukan.
Nama yang valid- pengidentifikasi spasi	Null	Semua penyedia ruang nama yang mendukung namespace yang ditunjukkan.
NS_ALL	Null	Semua penyedia ruang nama.

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

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

Catatan

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