LPNSPV2SETSERVICEEX Rückruffunktion (ws2spi.h)

Artikel
08/28/2023

Die NSPv2SetServiceEx-Funktion registriert oder hebt die Registrierung eines Namens oder diensts instance in einem Namespace eines NSPv2-Anbieters (NSPv2) auf.

Syntax

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

Ein Handle, das vom vorherigen Aufruf von NSPv2LookupServiceBegin zurückgegeben wurde, der für asynchrone Aufrufe verwendet wird.

[in] lpProviderId

Ein Zeiger auf die GUID des spezifischen Namespaceanbieters, in dem der Name oder Dienst registriert ist.

[in] lpqsRegInfo

Die Eigenschafteninformationen, die bei der Registrierung aktualisiert werden sollen.

[in] essOperation

Der Typ des angeforderten Vorgangs.

Dieser Parameter kann einer der Werte aus dem WSAESETSERVICEOP-Enumerationstyp sein, der in der Winsock2.h-Headerdatei definiert ist.

Wert	Bedeutung
RNRSERVICE_REGISTER 0	Registrieren Sie den Dienst. Für den Service Advertising Protocol (SAP)-Namespace, der in einer NetWare-Umgebung verwendet wird, bedeutet dies, dass eine regelmäßige Übertragung gesendet wird. Dies ist ein NOP für den DNS-Namespace (Domain Name System). Für persistente Datenspeicher bedeutet dies, dass die Adressinformationen aktualisiert werden.
RNRSERVICE_DEREGISTER 1	Heben Sie die Registrierung des Diensts auf. Für den SAP-Namespace 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 2	Löschen Sie den Dienst aus dynamischen Namen und persistenten Leerzeichen. Für Dienste, die durch mehrere CSADDR_INFO-Strukturen dargestellt werden (mit dem flag SERVICE_MULTIPLE), wird nur die angegebene Adresse gelöscht, und diese muss genau mit der entsprechenden CSADDR_INFO-Struktur übereinstimmen, die bei der Registrierung des Diensts bereitgestellt wurde.

[in] dwControlFlags

Ein Satz von Flags, der den angeforderten Vorgang steuert.

Die möglichen Werte für diesen Parameter werden in der Winsock2.h-Headerdatei definiert.

Wert	Bedeutung
SERVICE_MULTIPLE 0x00000001	Steuern Sie den Bereich des Vorgangs. Wenn dieser Wert festgelegt ist, wird die Aktion nur für den angegebenen Adresssatz ausgeführt. Bei einem Registrierungsvorgang werden vorhandene Adressen nicht ungültig, und bei einem Vorgang zur Aufhebung der Registrierung wird nur der angegebene Adresssatz ungültig. Wenn dieser Wert nicht vorhanden ist, werden Dienstadressen als Gruppe verwaltet. Durch ein Registrieren oder Aufheben der Registrierung werden alle vorhandenen Adressen ungültig, bevor der angegebene Adresssatz hinzugefügt wird.

Wert

Bedeutung

SERVICE_MULTIPLE

0x00000001

Steuern Sie den Bereich des Vorgangs.

Wenn dieser Wert festgelegt ist, wird die Aktion nur für den angegebenen Adresssatz ausgeführt. Bei einem Registrierungsvorgang werden vorhandene Adressen nicht ungültig, und bei einem Vorgang zur Aufhebung der Registrierung wird nur der angegebene Adresssatz ungültig.

Wenn dieser Wert nicht vorhanden ist, werden Dienstadressen als Gruppe verwaltet. Durch ein Registrieren oder Aufheben der Registrierung werden alle vorhandenen Adressen ungültig, bevor der angegebene Adresssatz hinzugefügt wird.

[in] lpvClientSessionArg

Ein Zeiger auf die Clientsitzung.

Rückgabewert

Die Funktion sollte NO_ERROR (null) zurückgeben, wenn die Routine erfolgreich ist. Es sollte SOCKET_ERROR (d. h. 1) zurückgeben, wenn die Routine fehlschlägt und der entsprechende Fehlercode mithilfe von WSASetLastError festgelegt werden muss.

Fehlercode	Bedeutung
WSA_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um diesen Vorgang auszuführen.
WSAEACCES	Die Aufrufroutine verfügt nicht über ausreichende Berechtigungen zum Installieren des Diensts.
WSAEINVAL	Mindestens ein Parameter war für diesen Anbieter ungültig oder fehlte.
WSAEOPNOTSUPP	Der Vorgang wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der Namespaceanbieter diese Funktion nicht implementiert. Dieser Fehler kann auch zurückgegeben werden, wenn der angegebene dwControlCode ein unbekannter Befehl ist.
WSASERVICE_NOT_FOUND	Der Dienst ist unbekannt. Der Dienst kann nicht im angegebenen Namespace gefunden werden.

Hinweise

Die NSPv2SetServiceEx-Funktion wird als Teil der NSPv2-Architektur (Namespace Service Provider Version-2) verwendet, die unter Windows Vista und höher verfügbar ist.

Unter Windows Vista und Windows Server 2008 kann die NSPv2SetServiceEx-Funktion nur für Vorgänge auf NS_EMAIL Namespaceanbietern verwendet werden.

Die NSPv2Startup-Funktion wird jedes Mal aufgerufen, wenn ein neuer Clientprozess mit dem Namespaceanbieter beginnt. Anbieter können das Clientsitzungsargument verwenden, auf das der parameter ppvClientSessionArg verweist, um Informationen zu dieser Sitzung zu speichern. Dieses Clientsitzungsargument kann im Parameter lpvClientSessionArg an die NSPv2SetServiceEx-Funktion übergeben werden.

Die NSPv2SetServiceEx-Funktion ist optional, abhängig von den Anforderungen des NSPv2-Anbieters. Wenn die NSPv2SetServiceEx-Funktion nicht implementiert ist, kann der NSPv2-Funktionszeiger auf eine Stubfunktion erfolgen, die immer NO_ERROR zurückgibt.

In der folgenden Tabelle ist die mögliche Kombination von Werten für die Parameter essOperation und dwControlFlags aufgeführt.

essOperation	dwControlFlags	Der Dienst ist bereits vorhanden.	Der Dienst ist nicht vorhanden.
RNRSERVICE_REGISTER	Keine	Überschreibt das -Objekt. Verwendet nur angegebene Adressen. Das Objekt ist REGISTRIERT.	Erstellt ein neues Objekt. Verwendet nur angegebene Adressen. Das Objekt ist REGISTRIERT.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Updates-Objekt. Fügt dem vorhandenen Satz neue Adressen hinzu. Das Objekt ist REGISTRIERT.	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 ist DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Updates-Objekt. Entfernt nur die angegebenen Adressen. Markieren Sie das Objekt nur als DEREGISTERED, wenn keine Adressen vorhanden sind. Entfernt 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

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 muss oder wenn sich der Dienst auf mehreren Computern befindet. Wenn ein Dienst beispielsweise mehr als ein Protokoll verwendet, kann ein Abhörsocket abgebrochen werden, aber die anderen Sockets bleiben betriebsbereit. In diesem Beispiel könnte der Dienst die Registrierung der abgebrochenen Adresse aufheben, ohne dass sich dies auf die anderen Adressen auswirkt.

Bei Verwendung SERVICE_MULTIPLE darf eine Anwendung nicht zulassen, dass alte Adressen im Objekt verbleiben. Dies kann passieren, wenn die Anwendung abgebrochen wird, ohne eine RNRSERVICE_DEREGISTER-Anforderung auszustellen. Wenn ein Dienst registriert wird, sollte er seine Adressen speichern. Beim nächsten Aufruf sollte der Dienst die Registrierung dieser alten Adressen explizit aufheben, bevor er neue Adressen registriert.

Wenn die NSPv2SetServiceEx-Funktion nicht implementiert ist, sollten Aufrufe dieser Funktion von einer Stubfunktion abgefangen werden, die WSAEOPNOTSUPP zurückgibt. Der NSPv2-Funktionszeiger auf die nicht implementierte NSPv2SetServiceEx-Funktion in der NSPV2_ROUTINE Struktur sollte auf die Stubfunktion verweisen.

Diensteigenschaften

In der folgenden Tabelle werden WSAQUERYSET2 Membernamen und die Darstellung von Diensteigenschaftendaten aufgeführt. Mitglieder, die als optional gekennzeichnet sind und von den Anforderungen des NSPv2-Anbieters abhängig sind, können als **NULL**-Zeiger bereitgestellt werden, wenn sie vom Namespaceanbieter nicht verwendet werden.

WSAQUERYSET2 Membername	Beschreibung der Diensteigenschaft
dwSize	Legen Sie auf sizeof(WSAQUERYSET2) fest. Dies ist ein Versionsverwaltungsmechanismus.
lpszServiceInstanceName	Eine Zeichenfolge, die den Dienst instance Namen enthält.
lpVersion	Der Dienst instance Versionsnummer. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszComment	Eine Kommentarzeichenfolge. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNameSpace	Der Namespacebezeichner. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpNSProviderId	Der Anbieterbezeichner. Beachten Sie, dass der Namespaceanbieterbezeichner auch im lpProviderId-Parameter übergeben wird. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszContext	Der Ausgangspunkt der Abfrage in einem hierarchischen Namespace. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNumberOfProtocols	Die Größe der Anzahl der Einträge im Protokolleinschränkungsarray in Bytes. Dieser Member kann 0 sein. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpafpProtocols	Ein Array von AFPROTOCOLS-Strukturen . Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszQueryString	Einige Namespaces (z. B. whois++) unterstützen umfangreiche SQL-ähnliche Abfragen, die in einer einfachen Textzeichenfolge enthalten sind. Dieser Parameter wird verwendet, um diese Zeichenfolge anzugeben. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
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 Adresse oder Adressen enthalten, an denen der Dienst lauscht.
dwOutputFlags	Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpBlob	Ein Zeiger auf eine anbieterspezifische Entität. Dieser Member ist für den NS_EMAIL-Namespace erforderlich. Dieses Mitglied ist optional, abhängig von den Anforderungen für andere NSPv2-Dienstanbieter.

**Hinweis** Es ist akzeptabel, dass das **iProtocol**-Element der CSADDR_INFO-Struktur die Manifestkonstante **IPROTOCOL_ANY** enthält, die einen Feldhalterwert angibt. Der Namespaceanbieter sollte einen akzeptablen Wert für die angegebene Adressfamilie und den angegebenen Sockettyp ersetzen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2spi.h