LPNSPV2LOOKUPSERVICEBEGIN funzione di callback (ws2spi.h)
La funzione NSPv2LookupServiceBegin avvia una query client di un provider di servizi dello spazio dei nomi versione 2 vincolata dalle informazioni contenute in una struttura WSAQUERYSET2 .
Sintassi
LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;
INT Lpnspv2lookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSET2W lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPVOID lpvClientSessionArg,
[out] LPHANDLE lphLookup
)
{...}
Parametri
[in] lpProviderId
Puntatore all'identificatore per il provider di servizi dello spazio dei nomi su cui eseguire una query.
[in] lpqsRestrictions
Puntatore ai criteri di ricerca. Vedere la sezione Osservazioni.
[in] dwControlFlags
Set di flag che influiscono sulla ricerca. Questo parametro può essere una combinazione dei valori seguenti definiti nel file di intestazione Winsock2.h .
| Valore | Significato |
|---|---|
|
Esegue una query verso il basso nella gerarchia di un provider anziché solo nel primo livello. |
|
Restituisce solo contenitori. |
|
Non restituisce alcun contenitore. |
|
Se possibile, restituisce i risultati nell'ordine di distanza. La misura della distanza è specifica del provider. |
|
Recupera il nome come **lpszServiceInstanceName**. |
|
Recupera il tipo come **lpServiceClassId**. |
|
Recupera la versione come **lpVersion**. |
|
Recupera il commento come **lpszComment**. |
|
Recupera gli indirizzi come **lpcsaBuffer**. |
|
Recupera i dati privati come **lpBlob**. |
|
Tutte le informazioni sugli alias disponibili devono essere restituite nelle chiamate successive a NSPv2LookupServiceNextEx e ogni alias restituito avrà il flag **RESULT_IS_ALIAS** impostato. |
|
Recupera la stringa di query come **lpszQueryString**. |
|
Recupera informazioni che includono il nome, il tipo, la versione, il commento, l'indirizzo, il BLOB, gli alias e la stringa di query. |
|
Se il provider contiene informazioni memorizzate nella cache, ignorare la cache ed eseguire query sullo spazio dei nomi stesso. |
|
Usato come valore per il parametro dwControlFlags in NSPv2LookupServiceNextEx. L'impostazione di questo flag indica al provider di eliminare l'ultimo set di risultati, troppo grande per il buffer fornito, e passare al set di risultati successivo. |
|
Indica che il provider dello spazio dei nomi deve includere risultati non autorevoli per i nomi. |
|
Indica se la risposta prime si trova nella parte remota o locale della struttura di CSADDR_INFO . L'altra parte deve essere utilizzabile in entrambi i casi. Questa opzione si applica solo alle richieste di istanza del servizio. |
|
Indica che il provider dello spazio dei nomi deve usare una query sicura. Questa opzione si applica solo alle richieste di query dei nomi. |
|
Indica che il provider dello spazio dei nomi deve restituire solo nomi preferiti. |
|
Indica che il provider dello spazio dei nomi deve restituire la configurazione dell'indirizzo. |
|
Indica che il provider dello spazio dei nomi deve restituire gli indirizzi duali. Questa opzione si applica solo ai socket in modalità doppia (indirizzi mappati IPv6 e IPv4). |
|
Indica che il provider dello spazio dei nomi deve disabilitare la codifica automatica dei nomi di dominio internazionali.
Questo valore è supportato in Windows 8 e Windows Server 2012 |
[out] lpvClientSessionArg
Puntatore alla sessione client.
[out] lphLookup
Puntatore all'handle da usare nelle chiamate successive a NSPv2LookupServiceNextEx per recuperare il set di risultati.
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 |
|---|---|
| Uno o più parametri non sono validi o mancanti per questo provider. | |
| Il nome è stato trovato nel database, ma non dispone dei dati associati corretti per cui vengono risolti. | |
| Il servizio è sconosciuto. Impossibile trovare il servizio nello spazio dei nomi specificato. | |
| Non è disponibile memoria sufficiente per eseguire questa operazione. |
Commenti
La funzione NSPv2LookupServiceBegin 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 NSPv2LookupServiceBegin può essere usata solo per le operazioni sui provider di spazi dei nomi NS_EMAIL.
La funzione NSPv2LookupServiceBegin restituisce solo un handle, che deve essere usato dalle chiamate successive a NSPv2LookupServiceNextEx per ottenere i risultati effettivi. Poiché questa operazione non può essere annullata, deve essere implementata rapidamente. Sebbene sia accettabile avviare una query di rete, questa funzione non deve richiedere una risposta per restituire correttamente.
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. Se viene specificato un valore per l'argomento sessione client nella chiamata alla funzione NSPv2Startup , lo stesso argomento sessione client viene passato al parametro lpvClientSessionArg alla funzione NSPv2LookupServiceBegin .
Se LUP_CONTAINERS viene specificato in una chiamata, evitare tutti gli altri valori di restrizione. Se sono disponibili, il provider di servizi di nome deve decidere se può supportare questa restrizione sui contenitori. In caso contrario, deve restituire un errore.
Alcuni provider di servizi di nome possono avere altri mezzi per trovare contenitori. Ad esempio, i contenitori possono essere di un tipo noto o di un set di tipi noti e pertanto è possibile creare una restrizione di query per trovarli. Indipendentemente da ciò che altro significa che il provider di servizi di nome ha per l'individuazione di contenitori, LUP_CONTAINERS e LUP_NOCONTAINERS hanno la precedenza. Pertanto, se viene specificata una restrizione di query che include contenitori, specificando LUP_NOCONTAINERS impedirà la restituzione degli elementi del contenitore. Analogamente, indipendentemente dalla restrizione della query, se viene specificata LUP_CONTAINERS , devono essere restituiti solo i contenitori. Se uno spazio dei nomi non supporta i contenitori e viene specificato LUP_CONTAINERS , deve restituire WSANO_DATA.
Il metodo preferito per ottenere i contenitori all'interno di un altro contenitore è la chiamata:
dwStatus = NSPv2LookupServiceBegin(
lpProviderId,
lpqsRestrictions,
LUP_CONTAINERS,
lpClientSession,
lphLookup);
seguito dal numero necessario di chiamate NSPv2LookupServiceNextEx . In questo modo tutti i contenitori verranno restituiti immediatamente all'interno del contesto iniziale; ovvero, non è una query profonda. In questo modo, è possibile eseguire il mapping della struttura dello spazio degli indirizzi eseguendo l'enumerazione del contenuto dei contenitori selezionati. Gli usi successivi di NSPv2LookupServiceBegin usano i contenitori restituiti da una chiamata precedente.
Creazione di query di maschera
La struttura WSAQUERYSET2 viene usata come parametro di input per NSPv2LookupServiceBegin per qualificare la query. La tabella seguente elenca i nomi dei membri **WSAQUERYSET2** e descrive come viene usato **WSAQUERYSET2** per costruire una query. I membri etichettati come facoltativi e dipendenti dai requisiti del provider NSPv2 possono essere forniti come puntatore **NULL** quando inutilizzati come criteri di ricerca dal provider dello spazio dei nomi. Per altre informazioni, vedere Strutture di dati correlate alle query.| WSAQUERYSET2 nome membro | Interpretazione delle query |
|---|---|
| **dwSize** | Verrà impostato su sizeof(WSAQUERYSET2). Si tratta di un meccanismo di controllo delle versioni. |
| **lpszServiceInstanceName** | Stringa contenente il nome del servizio. La semantica per il carattere jolly all'interno della stringa non è definita, ma può essere supportata da determinati provider di spazi dei nomi. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2. |
| **lpVersion** | Il numero di versione desiderato che fornisce la semantica di confronto delle versioni, ovvero la versione deve corrispondere esattamente o la versione deve essere inferiore al valore specificato. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2. |
| **lpszComment** | Questo membro viene ignorato per le query. |
| **dwNameSpace** | Identificatore di un singolo spazio dei nomi in cui limitare la ricerca o **NS_ALL** per includere tutti gli spazi dei nomi. |
| **lpNSProviderId** | GUID di un provider di spazi dei nomi specifico che limita solo la query a questo provider. 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. |
| **lpafpProtocols** | Matrice di strutture AFPROTOCOLS . Verranno restituiti solo i servizi che usano questi protocolli. È consentito che il valore **AF_UNSPEC** venga visualizzato come valore familiare del protocollo, firmando un carattere jolly. I provider di spazi dei nomi possono fornire informazioni su qualsiasi servizio che usa il protocollo corrispondente, indipendentemente dalla famiglia di indirizzi. 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** | Questo membro viene ignorato per le query. |
| **lpcsaBuffer** | Questo membro viene ignorato per le query. |
| **dwOutputFlags** | Questo membro viene ignorato per le query. |
| **lpBlob** | Puntatore a un'entità specifica del provider. Questo membro è facoltativo, dipendente dai requisiti del provider di servizi NSPv2. |
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 |