WSASetServiceW-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSASetService-Funktion registriert oder entfernt einen Dienst instance in einem oder mehreren Namespaces aus der Registrierung.

Syntax

INT WSAAPI WSASetServiceW(
  [in] LPWSAQUERYSETW   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parameter

[in] lpqsRegInfo

Ein Zeiger auf die Dienstinformationen für die Registrierung oder Aufhebung der Registrierung.

[in] essoperation

Ein Wert, der den angeforderten Vorgang bestimmt. Dieser Parameter kann einer der Werte des WSAESETSERVICEOP-Enumerationstyps sein, der in der Winsock2.h-Headerdatei definiert ist.

Wert	Bedeutung
RNRSERVICE_REGISTER	Registrieren Sie den Dienst. Für SAP bedeutet dies, dass eine regelmäßige Übertragung gesendet wird. Dies ist ein NOP für den DNS-Namespace. Für persistente Datenspeicher bedeutet dies, dass die Adressinformationen aktualisiert werden.
RNRSERVICE_DEREGISTER	Entfernen Sie den Dienst aus der Registrierung. Für SAP bedeutet dies, dass die regelmäßige Übertragung nicht mehr gesendet wird. Dies ist ein NOP für den DNS-Namespace. Für persistente Datenspeicher bedeutet dies das Löschen von Adressinformationen.
RNRSERVICE_DELETE	Löschen Sie den Dienst aus dynamischen Namen und persistenten Leerzeichen. Für Dienste, die durch mehrere CSADDR_INFO-Strukturen dargestellt werden (unter Verwendung des SERVICE_MULTIPLE-Flags), wird nur die angegebene Adresse gelöscht, und dies muss genau mit der entsprechenden CSADDR_INFO-Struktur übereinstimmen, die bei der Registrierung des Diensts angegeben wurde.

[in] dwControlFlags

Dienstinstallationsflagswert, der den Vorgang der WSASetService-Funktion weiter steuert. Die möglichen Werte für diesen Parameter werden in der Headerdatei Winsock2.h definiert.

Flag	Bedeutung
SERVICE_MULTIPLE	Steuert den Umfang des Vorgangs. Wenn dieses Flag nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Durch ein Registrieren oder Entfernen aus der Registrierung werden alle vorhandenen Adressen ungültig, bevor der angegebene Adresssatz hinzugefügt wird. Wenn festgelegt, wird die Aktion nur für den angegebenen Adresssatz ausgeführt. Bei einem Register werden vorhandene Adressen nicht ungültig, und ein Entfernen aus der Registrierung ungültig macht nur den angegebenen Adresssatz ungültig.

Flag

Bedeutung

SERVICE_MULTIPLE

Steuert den Umfang des Vorgangs. Wenn dieses Flag nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Durch ein Registrieren oder Entfernen aus der Registrierung werden alle vorhandenen Adressen ungültig, bevor der angegebene Adresssatz hinzugefügt wird. Wenn festgelegt, wird die Aktion nur für den angegebenen Adresssatz ausgeführt. Bei einem Register werden vorhandene Adressen nicht ungültig, und ein Entfernen aus der Registrierung ungültig macht nur den angegebenen Adresssatz ungültig.

Rückgabewert

Der Rückgabewert für WSASetService ist 0, wenn der Vorgang erfolgreich war. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAEACCES	Die aufrufende Routine verfügt nicht über ausreichende Berechtigungen, um den Dienst zu installieren.
WSAEINVAL	Mindestens ein erforderlicher Parameter war ungültig oder fehlte.
WSANOTINITIALISIERT	Die Ws2_32.dll wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup aufrufen, bevor sie Windows Sockets-Funktionen aufruft.
WSA_NOT_ENOUGH_MEMORY	Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.

Hinweise

Die WSASetService-Funktion kann verwendet werden, um einen bestimmten Namespaceanbieter, alle Anbieter, die einem bestimmten Namespace zugeordnet sind, oder alle Anbieter für alle Namespaces zu beeinflussen.

Die verfügbaren Werte für essOperation und dwControlFlags werden kombiniert, um den Betrieb der WSASetService-Funktion zu steuern, wie in der folgenden Tabelle gezeigt.

Vorgang	Flags	Der Dienst ist bereits vorhanden	Dienst ist nicht vorhanden
RNRSERVICE_REGISTER	Keine	Überschreibt das Objekt. Verwendet nur angegebene Adressen. Das Objekt ist REGISTERED.	Erstellt ein neues Objekt. Verwendet nur angegebene Adressen. Das Objekt ist REGISTRIERT.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Aktualisiert das Objekt. Fügt dem vorhandenen Satz neue Adressen hinzu. Das Objekt ist REGISTERED.	Erstellt ein neues Objekt. Verwendet alle angegebenen Adressen. Das Objekt ist REGISTRIERT.
RNRSERVICE_DEREGISTER	Keine	Entfernt alle Adressen, aber nicht das Objekt aus dem Namespace. Das Objekt wird aus der Registrierung entfernt.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Aktualisiert das Objekt. Entfernt nur die angegebenen Adressen. Markiert das Objekt nur dann als DEREGISTERED, wenn keine Adressen vorhanden sind. Entfernt das Objekt nicht aus dem Namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Keine	Entfernt das -Objekt aus dem Namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Entfernt nur die angegebenen Adressen. Entfernt das Objekt nur aus dem Namespace, wenn keine Adressen vorhanden sind.	WSASERVICE_NOT_FOUND

Die Veröffentlichung von Diensten in Verzeichnissen, z. B. Active Directory-Dienste, wird basierend auf Zugriffssteuerungslisten (Access Control Lists, ACLs) eingeschränkt. Weitere Informationen finden Sie unter Sicherheitsprobleme für die Dienstveröffentlichung.

Wenn der dwControlFlags-Parameter auf SERVICE_MULTIPLE festgelegt ist, kann eine Anwendung ihre Adressen unabhängig verwalten. Dies ist nützlich, wenn die Anwendung ihre Protokolle einzeln verwalten möchte oder wenn sich der Dienst auf mehreren Computern befindet. Wenn instance ein Dienst mehr als ein Protokoll verwendet, stellt er möglicherweise fest, dass ein Lauschocket abbricht, die anderen Sockets jedoch betriebsbereit bleiben. In diesem Fall könnte der Dienst die abgebrochene Adresse aus der Registrierung entfernen, ohne dass sich dies auf die anderen Adressen auswirkt.

Wenn der dwControlFlags-Parameter auf SERVICE_MULTIPLE festgelegt ist, darf eine Anwendung nicht zulassen, dass veraltete Adressen im Objekt verbleiben. Dies kann passieren, wenn die Anwendung abgebrochen wird, ohne eine DEREGISTER-Anforderung auszustellen. Wenn ein Dienst registriert wird, sollte er seine Adressen speichern. Beim nächsten Aufruf sollte der Dienst diese alten veralteten Adressen explizit aus der Registrierung entfernen, bevor neue Adressen registriert werden.

Hinweis Wenn ANSI-Zeichenfolgen verwendet werden, besteht die Möglichkeit, dass die WSAQUERYSET-Daten in lpqsRegInfo nach der Rückgabe dieser Funktion keine Ergebnisse enthalten. Dies liegt daran, dass die ANSI-Version dieser Methode, WSASetServiceA, die ANSI-Daten in WSAQUERYSET intern in Unicode konvertiert, aber die Ergebnisse nicht wieder in ANSI konvertiert. Dies wirkt sich in erster Linie auf Transporte aus, die ein "Dienstdatensatzhandle" zurückgeben, das zum eindeutigen Identifizieren eines Datensatzes verwendet wird. Um dieses Problem zu umgehen, sollten Anwendungen beim Aufrufen dieser Funktion Unicode-Zeichenfolgendaten in WSAQUERYSET verwenden.

Diensteigenschaften

In der folgenden Tabelle wird beschrieben, wie Diensteigenschaftendaten in einer WSAQUERYSET-Struktur dargestellt werden. Felder mit der Bezeichnung (Optional) können einen NULL-Zeiger enthalten.

WSAQUERYSET-Member	Beschreibung der Diensteigenschaft
dwSize	Muss auf sizeof (WSAQUERYSET) festgelegt werden. Dies ist ein Versionsverwaltungsmechanismus.
dwOutputFlags	Nicht zutreffend und ignoriert.
lpszServiceInstanceName	Die referenzierte Zeichenfolge enthält den Namen des Diensts instance.
lpServiceClassId	Die GUID, die dieser Dienstklasse entspricht.
lpVersion	(Optional) Stellt service instance Versionsnummer bereit.
lpszComment	(Optional) Eine optionale Kommentarzeichenfolge.
dwNameSpace	Weitere Informationen finden Sie in der folgenden Tabelle.
lpNSProviderId	Weitere Informationen finden Sie in der folgenden Tabelle.
lpszContext	(Optional) Gibt den Ausgangspunkt der Abfrage in einem hierarchischen Namespace an.
dwNumberOfProtocols	Ignoriert.
lpafpProtocols	Ignoriert.
lpszQueryString	Ignoriert.
dwNumberOfCsAddrs	Die Anzahl der Elemente im Array von CSADDR_INFO Strukturen, auf die lpcsaBuffer verweist.
lpcsaBuffer	Ein Zeiger auf ein Array von CSADDR_INFO Strukturen, die die Adressen enthalten, an denen der Dienst lauscht.
lpBlob	(Optional) Dies ist ein Zeiger auf eine anbieterspezifische Entität.

Wie im Folgenden dargestellt, bestimmt die Kombination der Member dwNameSpace und lpNSProviderId , dass Namespaceanbieter von dieser Funktion betroffen sind.

dwNameSpace	lpNSProviderId	Umfang der Auswirkungen
Wird ignoriert.	Ungleich NULL	Der angegebene Namensraumanbieter.
Ein gültiger Name: Leerzeichenbezeichner	Null	Alle Namensraumanbieter, die den angegebenen Namespace unterstützen.
NS_ALL	Null	Alle Namensraumanbieter.

Windows Phone 8: Die WSASetServiceW-Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Die WSASetServiceW-Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Hinweis

Der winsock2.h-Header definiert WSASetService als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll