WSASetServiceA-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSASetService-Funktion registriert oder entfernt in der Registrierung einen Dienst instance 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 Aufhebung der 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 persistenten Datenspeichern 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. Bei persistenten Datenspeichern 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 Winsock2.h-Headerdatei definiert.

Flag	Bedeutung
SERVICE_MULTIPLE	Steuert den Umfang des Vorgangs. Wenn dieses Flag nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Beim 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 bei einer Entfernung aus der Registrierung werden nur die angegebenen Adressen ungültig.

Flag

Bedeutung

SERVICE_MULTIPLE

Steuert den Umfang des Vorgangs. Wenn dieses Flag nicht festgelegt ist, werden Dienstadressen als Gruppe verwaltet. Beim 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 bei einer Entfernung aus der Registrierung werden nur die angegebenen Adressen ungültig.

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 von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAEACCES	Die Aufrufroutine 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 Windows Sockets-Funktionen aufgerufen werden.
WSA_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen.

Hinweise

Die WSASetService-Funktion kann verwendet werden, um einen bestimmten Namespaceanbieter, alle Anbieter, die einem bestimmten Namespace zugeordnet sind, oder alle Anbieter in allen 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 dargestellt.

Vorgang	Flags	Der Dienst ist bereits vorhanden.	Der 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 der vorhandenen Gruppe 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 ein Dienst mehr als ein Protokoll verwendet, stellt instance möglicherweise fest, dass ein Lauschocket abbricht, aber die anderen Sockets weiterhin betriebsbereit sind. In diesem Fall kann 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 veraltete Adressen nicht im Objekt verbleiben lassen. Dies kann vorkommen, 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 er neue Adressen registriert.

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, die Ergebnisse jedoch nicht zurück in ANSI konvertiert. Dies wirkt sich in erster Linie auf Transporte aus, die ein "Dienstdatensatzhandle" zurückgeben, das zur eindeutigen Identifizierung 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 Dienstnamen instance.
lpServiceClassId	Die GUID, die dieser Dienstklasse entspricht.
lpVersion	(Optional) Stellt den Dienst instance Versionsnummer bereit.
lpszComment	(Optional) Eine optionale Kommentarzeichenfolge.
dwNameSpace	Sehen Sie sich die folgende Tabelle an.
lpNSProviderId	Sehen Sie sich die folgende Tabelle an.
lpszContext	(Optional) Gibt den Startpunkt 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 lpcsaBuffer verwiesen wird.
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 Elemente dwNameSpace und lpNSProviderId , dass Namespaceanbieter von dieser Funktion betroffen sind.

dwNameSpace	lpNSProviderId	Umfang der Auswirkungen
Wird ignoriert.	Ungleich NULL	Der angegebene Name-Space-Anbieter.
Ein gültiger Name- Und 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 nicht codierungsneutralem Code 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