LPNSPV2LOOKUPSERVICENEXTEX funzione di callback (ws2spi.h)

Articolo
08/28/2023

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 usati 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 sufficiente, l'impostazione LUP_FLUSHPREVIOUS indica al provider di eliminare l'ultimo set di risultati, che era troppo grande e passare al set successivo per questa chiamata.

[in, out] lpdwBufferLength

Dimensioni, in byte, in input, contenute nel buffer a cui punta lpqsResults. In output, se la funzione ha esito negativo e l'errore è WSAEFAULT, contiene le dimensioni minime, in byte per passare per 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 eseguita una chiamata a NSPv2LookupServiceEnd durante l'elaborazione di questa chiamata. La chiamata è stata annullata. I dati nel buffer 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 l'intervallo più ampio possibile di applicazioni.
WSA_E_NO_MORE	Non sono disponibili altri dati. In Windows Sockets 2 i codici di errore in conflitto sono 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 l'intervallo più ampio possibile di applicazioni.
WSAEFAULT	Il buffer lpqsResults era troppo piccolo per contenere un set 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 nessun dato, corrispondente alle restrizioni indicate, è stato individuato.
WSASERVICE_NOT_FOUND	Il servizio è sconosciuto. Impossibile trovare il servizio nello spazio dei nomi specificato.
WSA_NOT_ENOUGH_MEMORY	Non è disponibile memoria sufficiente per eseguire questa operazione.

Commenti

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 finché non restituisce WSA_E_NOMORE, indicando 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 . Pertanto, i flag in NSPv2LookupServiceNextEx non possono mai aumentare la quantità di dati restituiti oltre quanto richiesto in NSPv2LookupServiceBegin, anche se non è un errore per specificare più o meno flag. I flag specificati in una determinata classe NSPv2LookupServiceNextEx si applicano solo a tale chiamata.

I dwControlFlagsLUP_FLUSHPREVIOUS e LUP_RES_SERVICE sono eccezioni alla regola di restrizione combinata (perché sono flag di comportamento anziché flag di "restrizione"). Se entrambi i flag vengono usati in NSPv2LookupServiceNextEx, hanno l'effetto definito indipendentemente dall'impostazione dello stesso flag in NSPv2LookupServiceBegin.

Ad esempio, se LUP_RETURN_VERSION viene specificato in NSPv2LookupServiceBegin, il provider di servizi recupera i record inclusi 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 viene 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 per ottenere le dimensioni del buffer necessario per ricevere il WSAQUERYSET2 indicato dal parametro lpqsResults e la seconda volta per ottenere il set di risultati della query effettivo. Nella prima chiamata, il provider NSPv2 deve restituire le dimensioni necessarie per i risultati WSAQUERYSET2.

La struttura WSAQUERYSET2 puntata dal parametro lpqsResults restituita è utile solo nel contesto del 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 (usando RPC, ad esempio), sarà necessario serializzare e eseguire il marshalling dei dati restituiti nella strutturaWSAQUERYSET2 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 tra limiti di processo. Solo passando una copia della struttura WSAQUERYSET2 è insufficiente, poiché solo i puntatori ai dati verranno passati e i dati effettivi non saranno disponibili per altri processi.

Risultati query

La tabella seguente elenca WSAQUERYSET2 e descrive il modo in cui i risultati delle query vengono rappresentati nella struttura **WSAQUERYSET2**. Per altre informazioni, vedere Strutture di dati correlate alle query.

WSAQUERYSET2 nome membro	Interpretazione dei risultati
dwSize	Dimensioni, in byte, della struttura WSAQUERYSET2 . Questa operazione viene usata 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, dipendente dai 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 questo 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 sul protocollo necessarie si trovano nelle strutture CSADDR_INFO .
lpszQueryString	Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo membro restituisce il resto non riparato del lpszServiceInstanceName specificato nella query originale. Ad esempio, in uno spazio dei nomi che identifica i servizi in base ai 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 archiviato potrebbe essere il percorso del file. Se lpszServiceInstanceName è completamente analizzato 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 in 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, dipendente dai requisiti del provider di servizi NSPv2.

Requisiti


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

Vedi anche

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

WSAQUERYSET2 nome membro	Interpretazione dei risultati
dwSize	Dimensioni, in byte, della struttura WSAQUERYSET2 . Questa operazione viene usata 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, dipendente dai 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 questo 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 sul protocollo necessarie si trovano nelle strutture CSADDR_INFO .
lpszQueryString	Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo membro restituisce il resto non riparato del lpszServiceInstanceName specificato nella query originale. Ad esempio, in uno spazio dei nomi che identifica i servizi in base ai 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 archiviato potrebbe essere il percorso del file. Se lpszServiceInstanceName è completamente analizzato 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 in 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, dipendente dai requisiti del provider di servizi NSPv2.

Condividi tramite