Funzione WSALookupServiceNextA (winsock2.h)

La funzione WSALookupServiceNext viene chiamata dopo aver ottenuto un handle da una chiamata precedente a WSALookupServiceBegin per recuperare le informazioni sul servizio richieste.

Il provider passerà di nuovo una struttura WSAQUERYSET nel buffer lpqsResults . Il client deve continuare a chiamare questa funzione fino a quando non restituisce WSA_E_NO_MORE, a indicare che è stato restituito tutto WSAQUERYSET .

Sintassi

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA lpqsResults
);

Parametri

[in] hLookup

Handle restituito dalla chiamata precedente a WSALookupServiceBegin.

[in] dwControlFlags

Set di flag che controlla l'operazione. I valori passati nel parametro dwControlFlags alla funzione WSALookupServiceBegin determinano i possibili criteri. Tutti i valori passati nel parametro dwControlFlags alla funzione WSALookupServiceNext limitano ulteriormente i criteri per la ricerca del servizio.

Attualmente, LUP_FLUSHPREVIOUS è definito come mezzo per gestire un set di risultati troppo grande. Se un'applicazione non fornisce (o non può) fornire un buffer sufficientemente grande, l'impostazione LUP_FLUSHPREVIOUS indica al provider di eliminare l'ultimo set di risultati, troppo grande, e passare al set successivo per questa chiamata.

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

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

[in, out] lpdwBufferLength

In base all'input, il numero di byte contenuti nel buffer a cui punta lpqsResults. Nell'output, se la funzione ha esito negativo e l'errore è WSAEFAULT, contiene il numero minimo di byte da passare per lpqsResults per recuperare il record.

[out] lpqsResults

Puntatore a un blocco di memoria che conterrà un set di risultati in una struttura WSAQUERYSET al momento della restituzione.

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_E_CANCELLED
È stata effettuata una chiamata a WSALookupServiceEnd durante l'elaborazione della chiamata. La chiamata è stata annullata. I dati nel buffer lpqsResults non sono definiti. In Windows Sockets versione 2 i codici di errore in conflitto sono definiti per WSAECANCELLED (10103) e WSA_E_CANCELLED (10111). Il codice di errore WSAECANCELLED verrà rimosso in una versione futura e rimarrà solo WSA_E_CANCELLED. Per Windows Sockets versione 2, tuttavia, le applicazioni devono verificare sia WSAECANCELLED che WSA_E_CANCELLED per garantire la compatibilità più ampia possibile con i provider di spazi dei nomi che usano entrambi.
WSA_E_NO_MORE
Non sono disponibili altri dati. In Windows Sockets versione 2 i codici di errore in conflitto sono definiti per WSAENOMORE (10102) e WSA_E_NO_MORE (10110). Il codice di errore WSAENOMORE verrà rimosso in una versione futura e rimarrà solo WSA_E_NO_MORE. Per Windows Sockets versione 2, tuttavia, le applicazioni devono verificare sia WSAENOMORE che WSA_E_NO_MORE per garantire la compatibilità più ampia possibile con i provider di spazio dei nomi che usano entrambi.
WSAEFAULT
Il buffer lpqsResults era troppo piccolo per contenere un set WSAQUERYSET .
WSAEINVAL
Uno o più parametri obbligatori non sono validi o mancanti.
WSA_INVALID_HANDLE
L'handle di ricerca specificato non è valido.
WSANOTINITIALISED
Il WS2_32.DLL non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets.
WSANO_DATA
Il nome è stato trovato nel database, ma non sono stati individuati dati corrispondenti alle restrizioni indicate.
WSA_NOT_ENOUGH_MEMORY
Memoria insufficiente per eseguire l'operazione.

Commenti

Il parametro dwControlFlags specificato in questa funzione e quelli specificati al momento di WSALookupServiceBegin vengono considerati come restrizioni allo scopo della combinazione. Le restrizioni vengono combinate tra quelle in fase WSALookupServiceBegin e quelle in WSALookupServiceNext . Di conseguenza, i flag in WSALookupServiceNext non possono mai aumentare la quantità di dati restituiti oltre a quanto richiesto in WSALookupServiceBegin, anche se non è un errore specificare più o meno flag. I flag specificati in un determinato WSALookupServiceNext si applicano solo a tale chiamata.

DwControlFlags LUP_FLUSHPREVIOUS e LUP_RES_SERVICE sono eccezioni alla regola di restrizioni combinata (perché sono flag di comportamento anziché flag di restrizione). Se uno di questi flag viene usato in WSALookupServiceNext , ha l'effetto definito indipendentemente dall'impostazione degli stessi flag in WSALookupServiceBegin.

Ad esempio, se LUP_RETURN_VERSION viene specificato in WSALookupServiceBegin , il provider di servizi recupera i record, inclusa la versione. Se LUP_RETURN_VERSION non è specificato in WSALookupServiceNext, le informazioni restituite non includono la versione, anche se era disponibile. Non viene generato alcun errore.

Ad esempio, se LUP_RETURN_BLOB non è specificato in WSALookupServiceBegin ma viene specificato in WSALookupServiceNext, le informazioni restituite non includono i dati privati. Non viene generato alcun errore.

Se la funzione WSALookupServiceNext ha esito negativo con un errore WSAEFAULT, indica che il buffer a cui punta il parametro lpqsResults è troppo piccolo per contenere i risultati della query. Un nuovo buffer per un oggetto WSAQUERYSET deve essere fornito con una dimensione specificata dal valore a cui punta il parametro lpdwBufferLength . Questo nuovo buffer per WSAQUERYSET deve avere alcuni dei membri di WSAQUERYSET specificati prima di chiamare nuovamente la funzione WSALookupServiceNext . Come minimo, il membro dwSize di WSAQUERYSET deve essere impostato sulla nuova dimensione del buffer.

Risultati query

Nella tabella seguente viene descritto il modo in cui i risultati della query vengono rappresentati nella struttura WSAQUERYSET .
Membro WSAQUERYSET Interpretazione dei risultati
dwSize Verrà impostato su sizeof( WSAQUERYSET). Viene usato come meccanismo di controllo delle versioni.
dwOutputFlags RESULT_IS_ALIAS flag indica che si tratta di un risultato alias.
lpszServiceInstanceName La stringa di riferimento contiene il nome del servizio.
lpServiceClassId GUID corrispondente alla classe del servizio.
lpVersion Fa riferimento al numero di versione dell'istanza del servizio specifica.
lpszComment Stringa di commento facoltativa specificata dall'istanza del servizio.
dwNameSpace Spazio dei nomi in cui è stata trovata l'istanza del servizio.
lpNSProviderId Identifica il provider dello spazio dei nomi specifico che ha fornito il risultato della query.
lpszContext Specifica il punto di contesto in uno spazio dei nomi gerarchico in cui si trova il servizio.
dwNumberOfProtocols Non definito per i risultati.
lpafpProtocols Non definito per i risultati, tutte le informazioni necessarie sul protocollo si trovano nelle strutture CSADDR_INFO .
lpszQueryString Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo parametro restituisce il resto non analizzato dell'oggetto lpszServiceInstanceName specificato nella query originale. Ad esempio, in uno spazio dei nomi che identifica i servizi in base a nomi gerarchici che specificano un nome host e un percorso di file all'interno di tale host, l'indirizzo restituito potrebbe essere l'indirizzo host e il resto non analizzato potrebbe essere il percorso del file. Se lpszServiceInstanceName viene analizzato completamente e LUP_RETURN_QUERY_STRING viene usato, questo parametro è NULL o punta a una stringa di lunghezza zero.
dwNumberOfCsAddrs Indica il numero di elementi nella matrice di strutture CSADDR_INFO .
lpcsaBuffer Puntatore a una matrice di strutture CSADDR_INFO , con un indirizzo di trasporto completo contenuto all'interno di ogni elemento.
lpBlob (Facoltativo) Si tratta di un puntatore a un'entità specifica del provider.
 

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

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

Nota

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

Requisiti

   
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 WSALookupServiceNext

WSALookupServiceBegin

WSALookupServiceEnd

WSAQUERYSET

Funzioni Winsock

Informazioni di riferimento su Winsock