Condividi tramite


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
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

Vedi anche

Bluetooth e WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32