LPNSPV2SETSERVICEEX funzione di callback (ws2spi.h)

Articolo
03/04/2024

La funzione NSPv2SetServiceEx registra o deregista un nome o un'istanza del servizio all'interno di uno spazio dei nomi di un provider di servizi versione 2 (NSPv2).

Sintassi

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Parametri

[in] hAsyncCall

Handle restituito dalla chiamata precedente a NSPv2LookupServiceBegin usato per le chiamate asincrone.

[in] lpProviderId

Puntatore al GUID del provider di spazi dei nomi specifico in cui è registrato il nome o il servizio.

[in] lpqsRegInfo

Informazioni sulla proprietà da aggiornare al momento della registrazione.

[in] essOperation

Tipo di operazione richiesta.

Questo parametro può essere uno dei valori del tipo di enumerazione WSAESETSERVICEOP definito nel file di intestazione Winsock2.h .

Valore	Significato
RNRSERVICE_REGISTER 0	Registrare il servizio. Per lo spazio dei nomi Service Advertising Protocol (SAP) usato all'interno di un ambiente NetWare, ciò significa inviare una trasmissione periodica. Si tratta di un NOP per lo spazio dei nomi DNS (Domain Name System). Per gli archivi dati persistenti, ciò significa aggiornare le informazioni sull'indirizzo.
RNRSERVICE_DEREGISTER 1	Annullare la registrazione del servizio. Per lo spazio dei nomi SAP, questo significa interrompere l'invio della trasmissione periodica. Si tratta di un NOP per lo spazio dei nomi DNS. Per gli archivi dati persistenti, ciò significa eliminare le informazioni sugli indirizzi.
RNRSERVICE_DELETE 2	Eliminare il servizio da spazi dinamici e nome permanente. Per i servizi rappresentati da più strutture di CSADDR_INFO (usando il flag di SERVICE_MULTIPLE), solo l'indirizzo fornito verrà eliminato e questo deve corrispondere esattamente alla struttura CSADDR_INFO corrispondente fornita quando il servizio è stato registrato.

[in] dwControlFlags

Set di flag che controllano l'operazione richiesta.

I valori possibili per questo parametro sono definiti nel file di intestazione Winsock2.h .

Valore	Significato
SERVICE_MULTIPLE 0x00000001	Controllare l'ambito dell'operazione. Quando questo valore viene impostato, l'azione viene eseguita solo nel set di indirizzi specificato. Un'operazione di registrazione non invalida gli indirizzi esistenti e un'operazione di deregister invalida solo il set specificato di indirizzi. Quando questo valore è assente, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o deregister invalida tutti gli indirizzi esistenti prima di aggiungere il set di indirizzi specificato.

Valore

Significato

SERVICE_MULTIPLE

0x00000001

Controllare l'ambito dell'operazione.

Quando questo valore viene impostato, l'azione viene eseguita solo nel set di indirizzi specificato. Un'operazione di registrazione non invalida gli indirizzi esistenti e un'operazione di deregister invalida solo il set specificato di indirizzi.

Quando questo valore è assente, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o deregister invalida tutti gli indirizzi esistenti prima di aggiungere il set di indirizzi specificato.

[in] lpvClientSessionArg

Puntatore alla sessione client.

Valore restituito

La funzione deve restituire NO_ERROR (zero) se la routine ha esito positivo. Deve restituire SOCKET_ERROR (ovvero 1) se la routine ha esito negativo e deve impostare il codice di errore appropriato usando WSASetLastError.

Codice di errore	Significato
WSA_NOT_ENOUGH_MEMORY	Non è disponibile memoria sufficiente per eseguire questa operazione.
WSAEACCES	La routine chiamante non dispone di privilegi sufficienti per installare il servizio.
WSAEINVAL	Uno o più parametri non sono validi o mancanti per questo provider.
WSAEOPNOTSUPP	L'operazione non è supportata. Questo errore viene restituito se il provider di spazi dei nomi non implementa questa funzione. Questo errore può essere restituito anche se il dwControlCode specificato è un comando non riconosciuto.
WSASERVICE_NOT_FOUND	Il servizio è sconosciuto. Impossibile trovare il servizio nello spazio dei nomi specificato.

Commenti

La funzione NSPv2SetServiceEx viene usata come parte dell'architettura del provider di servizi dello spazio dei nomi versione-2 (NSPv2) disponibile in Windows Vista e versioni successive.

In Windows Vista e Windows Server 2008 la funzione NSPv2SetServiceEx può essere usata solo per le operazioni sui provider di spazi dei nomi NS_EMAIL.

La funzione NSPv2Startup viene chiamata ogni volta che un nuovo processo client inizia usando il provider di spazi dei nomi. I provider possono usare l'argomento sessione client a cui punta il parametro ppvClientSessionArg per archiviare informazioni su questa sessione. Questo argomento della sessione client può essere passato alla funzione NSPv2SetServiceEx nel parametro lpvClientSessionArg .

La funzione NSPv2SetServiceEx è facoltativa, dipendente dai requisiti del provider NSPv2. Se la funzione NSPv2SetServiceEx non è implementata, il puntatore alla funzione NSPv2 può essere a una funzione stub che restituisce sempre NO_ERROR.

La tabella seguente elenca la possibile combinazione di valori per i parametri essOperation e dwControlFlags .

essOperation	dwControlFlags	Il servizio esiste già	Il servizio non esiste
RNRSERVICE_REGISTER	Nessuno	Sovrascrive l'oggetto. Usa solo gli indirizzi specificati. L'oggetto è REGISTRATO.	Crea un nuovo oggetto. Usa solo gli indirizzi specificati. L'oggetto è REGISTRATO.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Aggiornamenti oggetto . Aggiunge nuovi indirizzi al set esistente. L'oggetto è REGISTRATO.	Crea un nuovo oggetto. Usa tutti gli indirizzi specificati. L'oggetto è REGISTRATO.
RNRSERVICE_DEREGISTER	Nessuno	Rimuove tutti gli indirizzi, ma non rimuove l'oggetto dallo spazio dei nomi. L'oggetto è DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Aggiornamenti oggetto . Rimuove solo gli indirizzi specificati. Contrassegna solo l'oggetto DEREGISTERED se non sono presenti indirizzi. Non rimuove dallo spazio dei nomi.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Nessuno	Rimuove l'oggetto dallo spazio dei nomi.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Rimuove solo gli indirizzi specificati. Rimuove solo l'oggetto dallo spazio dei nomi se non rimangono indirizzi.	WSASERVICE_NOT_FOUND

Quando il parametro dwControlFlags è impostato su SERVICE_MULTIPLE, questo consente a un'applicazione di gestire in modo indipendente gli indirizzi. Ciò è utile quando l'applicazione deve gestire i protocolli singolarmente o quando il servizio risiede in più computer. Ad esempio, quando un servizio usa più di un protocollo, un socket in ascolto può interrompere, ma gli altri socket rimangono operativi. In questo esempio il servizio potrebbe annullare la registrazione dell'indirizzo interrotto senza influire sugli altri indirizzi.

Quando si usa SERVICE_MULTIPLE, un'applicazione non deve lasciare che gli indirizzi precedenti rimangano nell'oggetto. Ciò può verificarsi se l'applicazione viene interrotta senza inviare una richiesta di RNRSERVICE_DEREGISTER . Quando un servizio viene registrato, deve archiviarne gli indirizzi. Nella chiamata successiva, il servizio deve annullare esplicitamente la registrazione di questi indirizzi precedenti prima di registrare nuovi indirizzi.

Se la funzione NSPv2SetServiceEx non è implementata, le chiamate a tale funzione devono essere intercettate da una funzione stub che restituisce WSAEOPNOTSUPP. Il puntatore alla funzione NSPv2 alla funzione NSPv2SetServiceEx non implementata nella struttura NSPV2_ROUTINE deve puntare alla funzione stub.

Proprietà del servizio

La tabella seguente elenca i nomi dei membri WSAQUERYSET2 e descrive il modo in cui vengono rappresentati i dati delle proprietà del servizio. I membri etichettati come facoltativi e dipendenti dai requisiti del provider NSPv2 possono essere forniti come puntatore **NULL** quando inutilizzato dal provider dello spazio dei nomi.

WSAQUERYSET2 nome membro	Descrizione della proprietà del servizio
dwSize	Impostare su sizeof(WSAQUERYSET2). Si tratta di un meccanismo di controllo delle versioni.
lpszServiceInstanceName	Stringa contenente il nome dell'istanza del servizio.
lpVersion	Numero di versione dell'istanza del servizio. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpszComment	Stringa di commento. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
dwNameSpace	Identificatore dello spazio dei nomi. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpNSProviderId	Identificatore del provider. Si noti che l'identificatore del provider dello spazio dei nomi viene passato anche nel parametro lpProviderId . Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpszContext	Punto iniziale della query in uno spazio dei nomi gerarchico. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
dwNumberOfProtocols	Dimensioni, in byte, del numero di voci nella matrice di vincoli del protocollo. Questo membro può essere zero. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpafpProtocols	Matrice di strutture AFPROTOCOLS . Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpszQueryString	Alcuni spazi dei nomi (ad esempio whois++) supportano query sql avanzate contenute in una semplice stringa di testo. Questo parametro viene usato per specificare tale stringa. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
dwNumberOfCsAddrs	Numero di elementi nella matrice di strutture CSADDR_INFO a cui fa riferimento lpcsaBuffer.
lpcsaBuffer	Puntatore a una matrice di strutture CSADDR_INFO che contengono l'indirizzo o gli indirizzi in ascolto del servizio.
dwOutputFlags	Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2.
lpBlob	Puntatore a un'entità specifica del provider. Questo membro è obbligatorio per lo spazio dei nomi NS_EMAIL. Questo membro è facoltativo, dipendente dai requisiti per altri provider di servizi NSPv2.

**Nota** È accettabile per il membro **iProtocol** della struttura CSADDR_INFO contenere la costante manifesto ** IPROTOCOL_ANY **, che indica un valore jolly. Il provider dello spazio dei nomi deve sostituire un valore accettabile per la famiglia di indirizzi e il tipo di socket specificati.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2spi.h