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 |
|---|---|
|
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. |
[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 |
|---|---|
| È 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. | |
| 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. | |
| Il buffer lpqsResults era troppo piccolo per contenere un set WSAQUERYSET . | |
| Uno o più parametri obbligatori non sono validi o mancanti. | |
| L'handle di ricerca specificato non è valido. | |
| Il WS2_32.DLL non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets. | |
| Il nome è stato trovato nel database, ma non sono stati individuati dati corrispondenti alle restrizioni indicate. | |
| 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 |