Funzione di callback LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

Articolo
08/28/2023

La funzione NSPLookupServiceBegin avvia una query client di un provider di servizi dei nomi vincolata dalle informazioni contenute in una struttura WSAQUERYSET .

NSPLookupServiceBegin restituisce solo un handle, che deve essere usato dalle chiamate successive a NSPLookupServiceNext per ottenere i risultati effettivi. Poiché questa operazione non può essere annullata, deve essere implementata per l'esecuzione rapida. Anche se è accettabile avviare una query di rete, questa funzione non deve richiedere una risposta per restituire correttamente.

Sintassi

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Parametri

[in] lpProviderId

Puntatore all'identificatore del provider del servizio dei nomi su cui eseguire la query.

[in] lpqsRestrictions

Puntatore ai criteri di ricerca. Vedere la sezione Osservazioni.

[in] lpServiceClassInfo

Puntatore alla struttura WSASERVICECLASSINFO che contiene informazioni sullo schema per il servizio.

[in] dwControlFlags

Valore che controlla la profondità della ricerca.

Valore	Significato
LUP_DEEP 0x0001	Esegue una query verso il basso nella gerarchia di un provider anziché solo nel primo livello.
LUP_CONTAINERS 0x0002	Restituisce solo contenitori.
LUP_NOCONTAINERS 0x0004	Non restituisce alcun contenitore.
LUP_NEAREST 0x0008	Se possibile, restituisce i risultati nell'ordine di distanza. La misura della distanza è specifica del provider.
LUP_RETURN_NAME 0x0010	Recupera il nome come lpszServiceInstanceName.
LUP_RETURN_TYPE 0x0020	Recupera il tipo come lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Recupera la versione come lpVersion.
LUP_RETURN_COMMENT 0x0080	Recupera il commento come lpszComment.
LUP_RETURN_ADDR 0x0100	Recupera gli indirizzi come lpcsaBuffer.
LUP_RETURN_BLOB 0x0200	Recupera i dati privati come lpBlob.
LUP_RETURN_ALIASES 0x0400	Tutte le informazioni sugli alias disponibili devono essere restituite nelle chiamate successive a NSPLookupServiceNext e ogni alias restituito avrà il flag RESULT_IS_ALIAS impostato.
LUP_RETURN_QUERY_STRING 0x0800	Recupera la stringa di query come lpszQueryString.
LUP_RETURN_ALL 0x0ff0	Recupera informazioni che includono il nome, il tipo, la versione, il commento, l'indirizzo, il BLOB, gli alias e la stringa di query.
LUP_FLUSHCACHE 0x1000	Se il provider contiene informazioni memorizzate nella cache, ignorare la cache ed eseguire query sullo spazio dei nomi stesso.
LUP_FLUSHPREVIOUS 0x2000	Usato come valore per il parametro dwControlFlags in NSPLookupServiceNext. 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.
LUP_NON_AUTHORITATIVE 0x4000	Indica che il provider dello spazio dei nomi deve includere risultati non autorevoli per i nomi.
LUP_RES_RESERVICE 0x8000	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.
LUP_SECURE 0x8000	Indica che il provider dello spazio dei nomi deve usare una query sicura. Questa opzione si applica solo alle richieste di query dei nomi.
LUP_RETURN_PREFERRED_NAMES 0x10000	Indica che il provider dello spazio dei nomi deve restituire solo nomi preferiti.
LUP_ADDRCONFIG 0x100000	Indica che il provider dello spazio dei nomi deve restituire la configurazione dell'indirizzo.
LUP_DUAL_ADDR 0x200000	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).

[out] lphLookup

Puntatore all'handle da usare nelle chiamate successive a NSPLookupServiceNext 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 (-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	Memoria insufficiente per eseguire questa operazione.
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 dello spazio dei nomi non implementa questa funzione.
WSANO_DATA	Il nome è stato trovato nel database, ma non dispone dei dati associati corretti per cui vengono risolti.
WSASERVICE_NOT_FOUND	Il servizio è sconosciuto. Impossibile trovare il servizio nello spazio dei nomi specificato.

Commenti

Se LUP_CONTAINERS viene specificato in una chiamata, evitare tutti gli altri valori di restrizione. Se vengono forniti, il provider di servizi dei nomi deve decidere se può supportare questa restrizione sui contenitori. In caso contrario, dovrebbe restituire un errore.

Alcuni provider di servizi dei nomi possono avere altri mezzi per trovare i contenitori. Ad esempio, i contenitori possono essere di un tipo noto o di un set di tipi noti e pertanto è possibile creare una restrizione delle query per trovarli. Indipendentemente da ciò che altro significa che il provider di servizi dei nomi ha per individuare i contenitori, LUP_CONTAINERS e LUP_NOCONTAINERS hanno la precedenza. Pertanto, se viene specificata una restrizione di query che include i contenitori, specificando LUP_NOCONTAINERS si 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 = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

seguito dal numero necessario di chiamate NSPLookupServiceNext . Verranno restituiti tutti i contenitori contenuti immediatamente all'interno del contesto iniziale; vale a dire, non è una query approfondita. A questo scopo, è possibile eseguire il mapping della struttura dello spazio indirizzi camminando sulla gerarchia, ad esempio enumerando il contenuto dei contenitori selezionati. Gli usi successivi di NSPLookupServiceBegin usano i contenitori restituiti da una chiamata precedente.

Creazione di query

Come accennato, una struttura WSAQUERYSET viene usata come parametro di input per NSPLookupServiceBegin per qualificare la query. Nella tabella seguente sono elencati i nomi dei membri WSAQUERYSET e viene descritto come viene usato WSAQUERYSET per costruire una query. Quando un membro è contrassegnato come (facoltativo) è possibile specificare un puntatore Null, a indicare che il parametro non verrà usato come criteri di ricerca. Per altre informazioni, vedere Strutture di dati correlate alle query.

Nome del membro WSAQUERYSET	Interpretazione delle query
dwSize	Verrà impostato su sizeof(WSAQUERYSET). Si tratta di un meccanismo di controllo delle versioni.
dwOutputFlags	Ignorato per le query.
lpszServiceInstanceName	facoltativo. La stringa di riferimento contiene 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.
lpServiceClassId	Obbligatorio. GUID corrispondente alla classe del servizio.
lpVersion	facoltativo. Riferimenti al numero di versione desiderato e fornisce la semantica di confronto delle versioni, ovvero la versione deve corrispondere esattamente o la versione non deve essere minore del valore fornito.
lpszComment	Ignorato per le query.
dwNameSpace	Identificatore di un singolo spazio dei nomi in cui vincolare la ricerca o NS_ALL per includere tutti gli spazi dei nomi.
lpNSProviderId	facoltativo. Fa riferimento al GUID di un provider di spazi dei nomi specifico e limita la query solo a questo provider.
lpszContext	facoltativo. Specifica il punto iniziale della query in uno spazio dei nomi gerarchico.
dwNumberOfProtocols	Le dimensioni, in byte, del numero di voci nella matrice di vincoli di protocollo, possono essere zero.
lpafpProtocols	facoltativo. Riferimenti a una matrice di strutture AFPROTOCOLS . Verranno restituiti solo i servizi che usano questi protocolli. È consentito che il valore AF_UNSPEC venga visualizzato come valore della famiglia di protocolli, che indica un carattere jolly. I provider di spazi dei nomi possono fornire informazioni su qualsiasi servizio che utilizza il protocollo corrispondente, indipendentemente dalla famiglia di indirizzi.
lpszQueryString	facoltativo. Alcuni spazi dei nomi (ad esempio whois++) supportano query avanzate simili a SQL contenute in una stringa di testo semplice. Questo parametro viene usato per specificare tale stringa.
dwNumberOfCsAddrs	Ignorato per le query.
lpcsaBuffer	Ignorato per le query.
lpBlob	facoltativo. Puntatore a un'entità specifica del provider.

Requisiti


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

Vedi anche

Nome del membro WSAQUERYSET	Interpretazione delle query
dwSize	Verrà impostato su sizeof(WSAQUERYSET). Si tratta di un meccanismo di controllo delle versioni.
dwOutputFlags	Ignorato per le query.
lpszServiceInstanceName	facoltativo. La stringa di riferimento contiene 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.
lpServiceClassId	Obbligatorio. GUID corrispondente alla classe del servizio.
lpVersion	facoltativo. Riferimenti al numero di versione desiderato e fornisce la semantica di confronto delle versioni, ovvero la versione deve corrispondere esattamente o la versione non deve essere minore del valore fornito.
lpszComment	Ignorato per le query.
dwNameSpace	Identificatore di un singolo spazio dei nomi in cui vincolare la ricerca o NS_ALL per includere tutti gli spazi dei nomi.
lpNSProviderId	facoltativo. Fa riferimento al GUID di un provider di spazi dei nomi specifico e limita la query solo a questo provider.
lpszContext	facoltativo. Specifica il punto iniziale della query in uno spazio dei nomi gerarchico.
dwNumberOfProtocols	Le dimensioni, in byte, del numero di voci nella matrice di vincoli di protocollo, possono essere zero.
lpafpProtocols	facoltativo. Riferimenti a una matrice di strutture AFPROTOCOLS . Verranno restituiti solo i servizi che usano questi protocolli. È consentito che il valore AF_UNSPEC venga visualizzato come valore della famiglia di protocolli, che indica un carattere jolly. I provider di spazi dei nomi possono fornire informazioni su qualsiasi servizio che utilizza il protocollo corrispondente, indipendentemente dalla famiglia di indirizzi.
lpszQueryString	facoltativo. Alcuni spazi dei nomi (ad esempio whois++) supportano query avanzate simili a SQL contenute in una stringa di testo semplice. Questo parametro viene usato per specificare tale stringa.
dwNumberOfCsAddrs	Ignorato per le query.
lpcsaBuffer	Ignorato per le query.
lpBlob	facoltativo. Puntatore a un'entità specifica del provider.

Condividi tramite