LPNSPV2LOOKUPSERVICENEXTEX funzione di callback (ws2spi.h)

Articolo
07/16/2024

La funzione NSPv2LookupServiceNextEx viene chiamata dopo aver ottenuto un handle da una chiamata precedente a NSPv2LookupServiceBegin per recuperare le informazioni richieste da un provider di servizi della versione 2 dello spazio dei nomi.

Sintassi

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Parametri

[in] hAsyncCall

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

[in] hLookup

Handle restituito dalla chiamata precedente a NSPv2LookupServiceBegin.

[in] dwControlFlags

Flag utilizzati per controllare l'operazione successiva. Attualmente, solo LUP_FLUSHPREVIOUS è definito come mezzo per gestire un set di risultati troppo grande. Se un'applicazione non può fornire un buffer sufficientemente grande, l'impostazione LUP_FLUSHPREVIOUS indica al provider di rimuovere l'ultimo set di risultati, troppo grande e passare al set successivo per questa chiamata.

[in, out] lpdwBufferLength

Dimensione, in byte, in input, contenuta nel buffer a cui punta lpqsResults. Nell'output, se la funzione ha esito negativo e l'errore è WSAEFAULT, contiene le dimensioni minime, in byte da passare per il lpqsResults per recuperare il record.

[out] lpqsResults

Puntatore a un blocco di memoria che conterrà, in caso di restituzione, un set di risultati in una struttura WSAQUERYSET2.

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_E_CANCELLED	È stata effettuata una chiamata a NSPv2LookupServiceEnd durante l'elaborazione della chiamata. La chiamata è stata annullata. I dati nel buffer di lpqsResults non sono definiti. In Windows Sockets 2 i codici di errore in conflitto sono definiti per WSAECANCELLED (10103) e WSA_E_CANCELLED (10111). Il codice di errore WSAECANCELLED verrà rimosso in una versione futura e rimarrà solo WSA_E_CANCELLED. I provider di spazi dei nomi devono usare il codice di errore WSA_E_CANCELLED per mantenere la compatibilità con la più ampia gamma possibile di applicazioni.
WSA_E_NO_MORE	Non sono disponibili altri dati. In Windows Sockets 2 i codici di errore in conflitto vengono definiti per WSAENOMORE (10102) e WSA_E_NO_MORE (10110). Il codice di errore WSAENOMORE verrà rimosso in una versione futura e rimarrà solo WSA_E_NO_MORE. I provider di spazi dei nomi devono usare il codice di errore WSA_E_NO_MORE per mantenere la compatibilità con la più ampia gamma possibile di applicazioni.
WSAEFAULT	Il buffer di lpqsResults era troppo piccolo per contenere un set di WSAQUERYSET .
WSAEINVAL	Uno o più parametri non sono validi o mancanti per questo provider.
WSA_INVALID_HANDLE	L'handle di ricerca specificato non è valido.
WSANO_DATA	Il nome è stato trovato nel database, ma non sono stati individuati dati corrispondenti alle restrizioni indicate.
WSASERVICE_NOT_FOUND	Il servizio è sconosciuto. Impossibile trovare il servizio nello spazio dei nomi specificato.
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire questa operazione.

Osservazioni

La funzione NSPv2LookupServiceNextEx 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 NSPv2LookupServiceNextEx può essere usata solo per le operazioni sui provider di spazi dei nomi NS_EMAIL.

Il provider passerà una struttura WSAQUERYSET2 nel buffer lpqsResults. Il client deve chiamare la funzione NSPv2LookupServiceNextEx fino a quando non restituisce WSA_E_NOMORE, a indicare che tutte le strutture WSAQUERYSET2 sono state restituite.

I dwControlFlags specificati in questa funzione e quelli specificati al momento di NSPv2LookupServiceBegin vengono gestiti come "restrizioni" allo scopo della combinazione. Le restrizioni vengono combinate tra quelle in tempo NSPv2LookupServiceBegin e quelle in NSPv2LookupServiceNextEx ora. Di conseguenza, i flag in NSPv2LookupServiceNextEx non possono mai aumentare la quantità di dati restituiti oltre a quanto richiesto in NSPv2LookupServiceBegin, anche se non è un errore specificare più o meno flag. I flag specificati in un determinato NSPv2LookupServiceNextEx si applicano solo a tale chiamata.

Il dwControlFlagsLUP_FLUSHPREVIOUS e LUP_RES_SERVICE sono eccezioni alla regola delle restrizioni combinate (perché sono flag di comportamento anziché flag di "restrizione"). Se uno dei flag viene usato in NSPv2LookupServiceNextEx, l'effetto è definito indipendentemente dall'impostazione degli stessi flag in NSPv2LookupServiceBegin.

Ad esempio, se LUP_RETURN_VERSION viene specificato in NSPv2LookupServiceBegin, il provider di servizi recupera i record che includono la versione. Se LUP_RETURN_VERSION non è specificato in NSPv2LookupServiceNextEx, le informazioni restituite non includono la versione, anche se era disponibile. Non viene generato alcun errore.

Ad esempio, se LUP_RETURN_BLOB non è specificato in NSPv2LookupServiceBegin, ma è specificato in NSPv2LookupServiceNextEx, le informazioni restituite non includono i dati privati. Non viene generato alcun errore.

La funzione NSPv2LookupServiceNextEx viene in genere chiamata almeno due volte. La prima volta che si ottiene la dimensione del buffer necessario per ricevere il WSAQUERYSET2 a cui punta il parametro lpqsResults e la seconda volta per ottenere il set di risultati effettivo della query. Nella prima chiamata, il provider NSPv2 deve restituire le dimensioni necessarie per i risultati WSAQUERYSET2.

La struttura WSAQUERYSET2 a cui punta il parametro lpqsResults restituito è utile solo nello stesso contesto di processo, poiché diversi membri della struttura WSAQUERYSET2 contengono puntatori ai dati effettivi restituiti. Se il risultato della query deve essere passato a un altro processo (ad esempio tramite RPC), sarà necessario serializzare e effettuare il marshalling dei dati restituiti nella struttura WSAQUERYSET2 a cui punta il parametro lpqsResults, inclusi i dati a cui puntano i membri nella struttura WSAQUERYSET2. I dati devono essere serializzati in un modulo che può essere passato attraverso i limiti del processo. Solo passando una copia della struttura WSAQUERYSET2 non è sufficiente, poiché verranno passati solo i puntatori ai dati e i dati effettivi non saranno disponibili per altri processi.

risultati della query

La tabella seguente elenca WSAQUERYSET2 e descrive il modo in cui i risultati della query vengono rappresentati nella struttura **WSAQUERYSET2**. Per altre informazioni, vedere Query-Related strutture di dati.

WSAQUERYSET2 nome del membro	Interpretazione dei risultati
dwSize	Dimensione, in byte, della struttura WSAQUERYSET2. Viene usato come meccanismo di controllo delle versioni.
lpszServiceInstanceName	Stringa contenente il nome del servizio.
lpVersion	Fa riferimento al numero di versione dell'istanza del servizio specifica.
lpszComment	Stringa di commento fornita dall'istanza del servizio. Questo membro è facoltativo, a seconda dei requisiti del provider di servizi NSPv2.
dwNameSpace	Identificatore dello spazio dei nomi in cui è stato trovato il nome o l'istanza del servizio.
lpNSProviderId	Provider di spazi dei nomi specifico che ha fornito il risultato della query.
lpszContext	Punto di contesto in uno spazio dei nomi gerarchico in cui si trova il servizio.
dwNumberOfProtocols	Questo membro non è definito per i risultati.
lpafpProtocols	Questo membro non è definito per i risultati. Tutte le informazioni di protocollo necessarie si trovano nelle strutture CSADDR_INFO.
lpszQueryString	Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo membro restituisce il resto non analizzato del lpszServiceInstanceName specificato nella query originale. Ad esempio, in uno spazio dei nomi che identifica i servizi in base a nomi gerarchici che specificano un nome host e un percorso di file all'interno di tale host, l'indirizzo restituito potrebbe essere l'indirizzo host e il resto non analizzato potrebbe essere il percorso del file. Se lpszServiceInstanceName viene analizzato completamente e viene usato LUP_RETURN_QUERY_STRING, questo membro è Null o punta a una stringa di lunghezza zero.
dwNumberOfCsAddrs	Numero di elementi nella matrice di strutture CSADDR_INFO.
lpcsaBuffer	Puntatore a una matrice di strutture CSADDR_INFO, con un indirizzo di trasporto completo contenuto all'interno di ogni elemento.
dwOutputFlags	Il flag RESULT_IS_ALIAS indica che si tratta di un risultato alias.
lpBlob	Puntatore a un'entità specifica del provider. Questo membro è facoltativo, a seconda dei requisiti del provider di servizi NSPv2.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	ws2spi.h

Vedere anche

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASetLastError

WSAQUERYSET2 nome del membro	Interpretazione dei risultati
dwSize	Dimensione, in byte, della struttura WSAQUERYSET2. Viene usato come meccanismo di controllo delle versioni.
lpszServiceInstanceName	Stringa contenente il nome del servizio.
lpVersion	Fa riferimento al numero di versione dell'istanza del servizio specifica.
lpszComment	Stringa di commento fornita dall'istanza del servizio. Questo membro è facoltativo, a seconda dei requisiti del provider di servizi NSPv2.
dwNameSpace	Identificatore dello spazio dei nomi in cui è stato trovato il nome o l'istanza del servizio.
lpNSProviderId	Provider di spazi dei nomi specifico che ha fornito il risultato della query.
lpszContext	Punto di contesto in uno spazio dei nomi gerarchico in cui si trova il servizio.
dwNumberOfProtocols	Questo membro non è definito per i risultati.
lpafpProtocols	Questo membro non è definito per i risultati. Tutte le informazioni di protocollo necessarie si trovano nelle strutture CSADDR_INFO.
lpszQueryString	Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo membro restituisce il resto non analizzato del lpszServiceInstanceName specificato nella query originale. Ad esempio, in uno spazio dei nomi che identifica i servizi in base a nomi gerarchici che specificano un nome host e un percorso di file all'interno di tale host, l'indirizzo restituito potrebbe essere l'indirizzo host e il resto non analizzato potrebbe essere il percorso del file. Se lpszServiceInstanceName viene analizzato completamente e viene usato LUP_RETURN_QUERY_STRING, questo membro è Null o punta a una stringa di lunghezza zero.
dwNumberOfCsAddrs	Numero di elementi nella matrice di strutture CSADDR_INFO.
lpcsaBuffer	Puntatore a una matrice di strutture CSADDR_INFO, con un indirizzo di trasporto completo contenuto all'interno di ogni elemento.
dwOutputFlags	Il flag RESULT_IS_ALIAS indica che si tratta di un risultato alias.
lpBlob	Puntatore a un'entità specifica del provider. Questo membro è facoltativo, a seconda dei requisiti del provider di servizi NSPv2.

Condividi tramite