Funzione WSALookupServiceBeginA (winsock2.h)
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 |
|---|---|
|
Esegue query approfondite anziché solo il primo livello. |
|
Restituisce solo contenitori. |
|
Non restituire contenitori. |
|
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 WSALookupServiceNext e ogni alias restituito avrà il flag RESULT_IS_ALIAS impostato. |
|
Recupera la stringa di query utilizzata per la richiesta. |
|
Set di flag che recupera tutti i valori LUP_RETURN_*. |
|
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. |
|
Se il provider ha memorizzato nella cache le informazioni, ignora la cache ed esegue una query sullo spazio dei nomi stesso. |
|
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 |
|---|---|
| Memoria insufficiente per eseguire l'operazione. | |
| Uno o più parametri mancanti o non validi per questo provider. | |
| Il nome è stato trovato nel database, ma non sono stati individuati dati corrispondenti alle restrizioni indicate. | |
| Il WS2_32.DLL non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets. | |
|
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. |
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 |