Funzione WSALookupServiceBeginA (winsock2.h)

Articolo
03/04/2024

La funzione WSALookupServiceBegin avvia una query client vincolata dalle informazioni contenute in una struttura WSAQUERYSET . WSALookupServiceBegin restituisce solo un handle, che deve essere usato dalle chiamate successive a WSALookupServiceNext per ottenere i risultati effettivi.

Sintassi

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

Parametri

[in] lpqsRestrictions

Puntatore ai criteri di ricerca. Per informazioni dettagliate, vedere la sezione Note.

[in] dwControlFlags

Set di flag che controlla la profondità della ricerca.

I valori supportati per il parametro dwControlFlags sono definiti nel file di intestazione Winsock2.h e possono essere una combinazione delle opzioni seguenti.

Contrassegno	Significato
LUP_DEEP 0x0001	Esegue query approfondite anziché solo il primo livello.
LUP_CONTAINERS 0x0002	Restituisce solo contenitori.
LUP_NOCONTAINERS 0x0004	Non restituire contenitori.
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 WSALookupServiceNext e ogni alias restituito avrà il flag RESULT_IS_ALIAS impostato.
LUP_RETURN_QUERY_STRING 0x0800	Recupera la stringa di query utilizzata per la richiesta.
LUP_RETURN_ALL 0x0FF0	Set di flag che recupera tutti i valori LUP_RETURN_*.
LUP_FLUSHPREVIOUS 0x1000	Usato come valore per il parametro dwControlFlags in WSALookupServiceNext. L'impostazione di questo flag indica al provider di eliminare l'ultimo set di risultati, troppo grande per il buffer specificato, e passare al set di risultati successivo.
LUP_FLUSHCACHE 0x2000	Se il provider ha memorizzato nella cache le informazioni, ignora la cache ed esegue una query sullo spazio dei nomi stesso.
LUP_RES_SERVICE 0x8000	Indica se la risposta prime si trova nella parte remota o locale della struttura CSADDR_INFO . L'altra parte deve essere utilizzabile in entrambi i casi.

[out] lphLookup

Handle da usare quando si chiama WSALookupServiceNext per iniziare a recuperare il set di risultati.

Valore restituito

Il valore restituito è zero se l'operazione ha avuto esito positivo. In caso contrario, viene restituito il valore SOCKET_ERROR e è possibile recuperare un numero di errore specifico chiamando WSAGetLastError.

Codice di errore	Significato
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire l'operazione.
WSAEINVAL	Uno o più parametri mancanti o non validi per questo provider.
WSANO_DATA	Il nome è stato trovato nel database, ma non sono stati individuati dati corrispondenti alle restrizioni indicate.
WSANOTINITIALISED	Il WS2_32.DLL non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets.
WSASERVICE_NOT_FOUND	Non è noto alcun servizio di questo tipo. Impossibile trovare il servizio nello spazio dei nomi specificato. Questo errore viene restituito per una richiesta di individuazione del servizio Bluetooth se non sono stati trovati dispositivi Bluetooth remoti.

Commenti

Il parametro lpqsRestrictions punta a un buffer contenente una struttura WSAQUERYSET . Come minimo, il membro dwSize di WSAQUERYSET deve essere impostato sulla lunghezza del buffer prima di chiamare la funzione WSALookupServiceBegin . Le applicazioni possono limitare la query specificando altri membri in WSAQUERYSET.

Nella maggior parte dei casi, le applicazioni interessate solo a un particolare protocollo di trasporto devono vincolare la query in base alla famiglia di indirizzi e al protocollo usando i membri dwNumberOfProtocols e lpafpProtocols di WSAQUERYSET anziché specificando lo spazio dei nomi nel membro dwNameSpace .

Le informazioni sui protocolli di trasporto di rete supportati possono essere recuperate usando la funzione EnumProtocols, WSAEnumProtocols, WSCEnumProtocols o WSCEnumProtocols32 .

È anche possibile vincolare la query a un singolo spazio dei nomi. Ad esempio, una query che vuole solo i risultati da DNS (non i risultati del file host locale e di altri servizi di denominazione) imposterà il membro dwNameSpace su NS_DNS. Ad esempio, un'individuazione del dispositivo Bluetooth imposta il membro dwNameSpace su NS_BTH.

Le applicazioni possono anche limitare la query a un provider di spazi dei nomi specifico specificando un puntatore al GUID per il provider nel membro lpNSProviderId .

Le informazioni sui provider di spazi dei nomi nel computer locale possono essere recuperate tramite la funzione WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 o WSCEnumNameSpaceProvidersEx32 .

Se LUP_CONTAINERS viene specificato in una chiamata, è consigliabile evitare altri valori di restrizione. Se sono specificati, spetta al provider di servizi dei nomi decidere se può supportare questa restrizione sui contenitori. In caso contrario, verrà restituito un errore.

Alcuni provider di servizi dei nomi possono avere altri mezzi per trovare i contenitori. Ad esempio, i contenitori possono essere tutti di un tipo noto o di un set di tipi noti e pertanto è possibile crearne una restrizione per la ricerca. Indipendentemente da ciò che altro significa che il provider di servizi di nome ha per individuare contenitori, LUP_CONTAINERS e LUP_NOCONTAINERS prendere 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 semplicemente restituire WSANO_DATA.

Il metodo preferito per ottenere i contenitori all'interno di un altro contenitore è la chiamata:

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

Questa chiamata viene seguita dal numero necessario di chiamate WSALookupServiceNext . 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 WSALookupServiceBegin usano i contenitori restituiti da una chiamata precedente.

Come accennato in precedenza, una struttura WSAQUERYSET viene usata come parametro di input per WSALookupBegin per qualificare la query. La tabella seguente indica come viene usato WSAQUERYSET per costruire una query. Quando un parametro è contrassegnato come (facoltativo) è possibile specificare un puntatore NULL , che indica che il parametro non verrà usato come criteri di ricerca. Per altre informazioni, vedere la sezione Strutture dati correlate alle query .

Membro WSAQUERYSET	Interpretazione delle query
dwSize	Deve essere 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 di 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 deve essere inferiore al valore specificato.
lpszComment	Ignorato per le query.
dwNameSpace Vedere la nota importante che segue.	Identificatore di un singolo spazio dei nomi in cui limitare 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 solo la query a questo provider.
lpszContext	(Facoltativo) Specifica il punto iniziale della query in uno spazio dei nomi gerarchico.
dwNumberOfProtocols	Le dimensioni della matrice di vincoli del protocollo possono essere zero.
lpafpProtocols	(Facoltativo) Fa riferimento a una matrice di struttura AFPROTOCOLS . Verranno restituiti solo i servizi che usano questi protocolli.
lpszQueryString	(Facoltativo) Alcuni spazi dei nomi (ad esempio whois++) supportano query sql arricchite come quelle 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) Si tratta di un puntatore a un'entità specifica del provider.

Importante Nella maggior parte dei casi, le applicazioni interessate solo a un particolare protocollo di trasporto devono limitare la query in base alla famiglia di indirizzi e al protocollo anziché allo spazio dei nomi. Ciò consente a un'applicazione che deve individuare un servizio TCP/IP, ad esempio, di avere la query elaborata da tutti gli spazi dei nomi disponibili, ad esempio il file host locale, IL DNS e il servizio NIS.

Windows Phone 8: la funzione WSALookupServiceBeginW è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: la funzione WSALookupServiceBeginW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Nota

L'intestazione winsock2.h definisce WSALookupServiceBegin come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll