WSASetServiceA-Funktion (winsock2.h)

Artikel
11/20/2024

Die WSASetService Funktion registriert oder entfernt aus der Registrierung eine Dienstinstanz innerhalb eines oder mehrerer Namespaces.

Syntax

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

Parameter

[in] lpqsRegInfo

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

[in] essoperation

Ein Wert, der den angeforderten Vorgang bestimmt. Dieser Parameter kann einer der Werte aus dem WSAESETSERVICEOP-Enumerationstyp 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. Bei beständigen Datenspeichern bedeutet dies, dass die Adressinformationen aktualisiert werden.
RNRSERVICE_DEREGISTER	Entfernen Sie den Dienst aus der Registrierung. Für SAP bedeutet dies, dass das Senden der regelmäßigen Übertragung beendet wird. Dies ist ein NOP für den DNS-Namespace. Bei beständigen Datenspeichern bedeutet dies das Löschen von Adressinformationen.
RNRSERVICE_DELETE	Löschen Sie den Dienst aus dynamischen Namen und beständigen Leerzeichen. Für Dienste, die durch mehrere CSADDR_INFO Strukturen dargestellt werden (mit dem SERVICE_MULTIPLE Flag), wird nur die angegebene Adresse gelöscht, und dies muss exakt mit der entsprechenden CSADDR_INFO Struktur übereinstimmen, die beim Registrieren des Diensts angegeben wurde.

[in] dwControlFlags

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

Flagge	Bedeutung
SERVICE_MULTIPLE	Steuert den Umfang des Vorgangs. Wenn dieses Kennzeichen nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Ein Register oder entfernen aus der Registrierung ungültig alle vorhandenen Adressen, bevor der angegebene Adresssatz hinzugefügt wird. Bei Festlegung 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 löscht nur die angegebene Gruppe von Adressen.

Flagge

Bedeutung

SERVICE_MULTIPLE

Steuert den Umfang des Vorgangs. Wenn dieses Kennzeichen nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Ein Register oder entfernen aus der Registrierung ungültig alle vorhandenen Adressen, bevor der angegebene Adresssatz hinzugefügt wird. Bei Festlegung 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 löscht nur die angegebene Gruppe von Adressen.

Rückgabewert

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

Fehlercode	Bedeutung
WSAEACCES	Die Aufrufenroutine 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 aufrufen.
WSA_NOT_ENOUGH_MEMORY	Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.

Bemerkungen

Die WSASetService--Funktion kann verwendet werden, um einen bestimmten Namespaceanbieter, alle Mit einem bestimmten Namespace verknüpften Anbieter oder alle Anbieter in allen Namespaces zu beeinflussen.

Die verfügbaren Werte für essOperation und dwControlFlags zum Steuern des Vorgangs der WSASetService Funktion kombinieren, wie in der folgenden Tabelle dargestellt.

Operation	Flaggen	Der Dienst ist bereits vorhanden.	Der Dienst ist nicht vorhanden.
RNRSERVICE_REGISTER	Nichts	Überschreibt das Objekt. Verwendet nur angegebene Adressen. Das Objekt ist REGISTRIERT.	Erstellt ein neues Objekt. Verwendet nur angegebene Adressen. Objekt ist REGISTRIERT.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Aktualisiert das Objekt. Fügt dem vorhandenen Satz neue Adressen hinzu. Das Objekt ist REGISTRIERT.	Erstellt ein neues Objekt. Verwendet alle angegebenen Adressen. Objekt ist REGISTRIERT.
RNRSERVICE_DEREGISTER	Nichts	Entfernt alle Adressen, entfernt jedoch 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 Adressen, die angegeben sind. Markiert das Objekt nur als DEREGISTERED, wenn keine Adressen vorhanden sind. Entfernt das Objekt nicht aus dem Namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Nichts	Entfernt das Objekt aus dem Namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Entfernt nur Adressen, die angegeben sind. Entfernt nur das Objekt aus dem Namespace, wenn keine Adressen verbleiben.	WSASERVICE_NOT_FOUND

Veröffentlichungsdienste in Verzeichnissen, z. B. Active Directory-Dienste, sind 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_MULTIPLEfestgelegt ist, kann eine Anwendung ihre Adressen unabhängig voneinander verwalten. Dies ist nützlich, wenn die Anwendung ihre Protokolle einzeln verwalten möchte oder wenn sich der Dienst auf mehreren Computern befindet. Wenn ein Dienst z. B. mehrere Protokolle verwendet, wird möglicherweise festgestellt, dass ein Überwachungssocket abgebrochen wird, die anderen Sockets aber weiterhin betriebsbereit bleiben. In diesem Fall konnte der Dienst die abgebrochene Adresse aus der Registrierung entfernen, ohne dass sich dies auf die anderen Adressen auswirkt.

Wenn der dwControlFlags Parameter auf SERVICE_MULTIPLEfestgelegt ist, darf eine Anwendung keine veralteten Adressen im Objekt verbleiben lassen. Dies kann passieren, wenn die Anwendung abgebrochen wird, ohne eine DEREGISTER-Anforderung auszugeben. 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 Wahrscheinlichkeit, dass die WSAQUERYSET- Daten in lpqsRegInfo- möglicherweise keine Ergebnisse enthalten, nachdem diese Funktion zurückgegeben wurde. Dies liegt daran, dass die ANSI-Version dieser Methode, WSASetServiceA-, die ANSI-Daten in WSAQUERYSET- intern in Unicode konvertiert, die Ergebnisse jedoch nicht in ANSI konvertiert. Dies betrifft in erster Linie Transporte, die ein "Dienstdatensatzhandle" zurückgeben, das zum eindeutigen Identifizieren eines Datensatzes verwendet wird. Um dieses Problem zu umgehen, sollten Anwendungen Unicode-Zeichenfolgendaten in WSAQUERYSET- beim Aufrufen dieser Funktion verwenden.

Diensteigenschaften

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

WSAQUERYSET-Mitglied	Beschreibung der Diensteigenschaft
dwSize-	Muss auf "sizeof" festgelegt werden (WSAQUERYSET). Dies ist ein Versionsverwaltungsmechanismus.
dwOutputFlags	Nicht zutreffend und ignoriert.
lpszServiceInstanceName	Referenzierte Zeichenfolge enthält den Namen der Dienstinstanz.
lpServiceClassId-	Die GUID, die dieser Dienstklasse entspricht.
lpVersion-	(Optional) Versionsnummer der Dienstinstanz.
lpszComment	(Optional) Eine optionale Kommentarzeichenfolge.
dwNameSpace-	Siehe folgende Tabelle.
lpNSProviderId-	Siehe folgende 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 von lpcsaBufferverwiesen wird.
lpcsaBuffer	Ein Zeiger auf ein Array von CSADDR_INFO Strukturen, die die Adresse(n) enthalten, auf die der Dienst lauscht.
lpBlob	(Optional) Dies ist ein Zeiger auf eine anbieterspezifische Entität.

Wie in der folgenden Abbildung dargestellt, bestimmen die Kombination der dwNameSpace und lpNSProviderId Member, dass Namespaceanbieter von dieser Funktion betroffen sind.

dwNameSpace-	lpNSProviderId-	Wirkungsbereich
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 unter 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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anmerkung

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
mindestens unterstützte Client-	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winsock2.h
Library	Ws2_32.lib
DLL-	Ws2_32.dll