Funzione WSALookupServiceNextA (winsock2.h)

Articolo
11/20/2024

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 di 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 il 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 controllano l'operazione. I valori passati nel parametro dwControlFlags alla funzione WSALookupServiceBegin . 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 far fronte a 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.

Bandiera	Significato
LUP_DEEP 0x0001	Esegue query approfondite anziché solo il primo livello.
LUP_CONTAINERS 0x0002	Restituisce solo i 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	Le informazioni sugli alias disponibili devono essere restituite nelle chiamate successive a WSALookupServiceNexte 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 e esegue 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 caso di 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 il lpqsResults per recuperare il record.

[out] lpqsResults

Puntatore a un blocco di memoria, che conterrà un set di risultati in una struttura WSAQUERYSET restituita.

Valore restituito

Il valore restituito è zero se l'operazione ha avuto esito positivo. In caso contrario, viene restituito il valore SOCKET_ERROR e un numero di errore specifico può essere recuperato 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 di 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 ottenere la massima compatibilità 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 vengono 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 la compatibilità più ampia possibile con provider di spazi dei nomi che usano uno dei due.
WSAEFAULT	Il buffer di lpqsResults era troppo piccolo per contenere un set di 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 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.

Osservazioni

Il parametro dwControlFlags specificato in questa funzione e quelli specificati al momento di WSALookupServiceBegin vengono considerati come restrizioni per la combinazione. Le restrizioni vengono combinate tra quelle in WSALookupServiceBegin ora e quelle in WSALookupServiceNext ora. 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.

I dwControlFlags LUP_FLUSHPREVIOUS e LUP_RES_SERVICE sono eccezioni alla regola delle restrizioni combinate (perché sono flag di comportamento anziché flag di restrizione). Se uno di questi flag viene usato in WSALookupServiceNext hanno 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 che includono 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 di WSAEFAULT, indica che il buffer a cui punta il lpqsResults parametro era troppo piccolo per contenere i risultati della query. È necessario fornire un nuovo buffer per un WSAQUERYSET con una dimensione specificata dal valore a cui punta il parametro lpdwBufferLength. Questo nuovo buffer per il WSAQUERYSET di deve avere alcuni dei membri del WSAQUERYSET specificato prima di chiamare di nuovo la funzione WSALookupServiceNext. Come minimo, il dwSize membro del WSAQUERYSET deve essere impostato sulla nuova dimensione del buffer.

risultati della query

Nella tabella seguente viene descritto il modo in cui i risultati della query vengono rappresentati nella struttura di 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 di spazi 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 del protocollo necessarie si trovano nelle strutture CSADDR_INFO.
lpszQueryString	Quando dwControlFlags include LUP_RETURN_QUERY_STRING, questo parametro restituisce il resto non analizzato del 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 il lpszServiceInstanceName viene analizzato completamente e LUP_RETURN_QUERY_STRING viene usato, questo parametro viene 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 di WSALookupServiceNextW è supportata per le app di Windows Phone Store 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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	Finestre
intestazione	winsock2.h
libreria	Ws2_32.lib
dll	Ws2_32.dll