Funzione WSAAsyncGetHostByName (winsock.h)

Articolo
08/27/2023

La funzione WSAAsyncGetHostByName recupera in modo asincrono le informazioni host che corrispondono a un nome host.

Nota La funzione WSAAsyncGetHostByName non è progettata per fornire una risoluzione parallela di diversi nomi. Di conseguenza, le applicazioni che eseguono diverse richieste non devono essere eseguite contemporaneamente. In alternativa, le applicazioni possono avviare un altro thread e usare la funzione getaddrinfo per risolvere i nomi in modo indipendente dalla versione IP. Gli sviluppatori che creano applicazioni Windows Sockets 2 sono invitati a usare la funzione getaddrinfo per abilitare la transizione uniforme alla compatibilità IPv6.

Sintassi

HANDLE WSAAsyncGetHostByName(
  HWND       hWnd,
  u_int      wMsg,
  const char *name,
  char       *buf,
  int        buflen
);

Parametri

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

Valore restituito

Il valore restituito specifica se l'operazione asincrona è stata avviata correttamente. Non implica l'esito positivo o negativo dell'operazione stessa.

Se non si verifica alcun errore, WSAAsyncGetHostByName restituisce un valore diverso da zero di tipo HANDLE che rappresenta l'handle di attività asincrona (da non confondere con un HTASK di Windows) per la richiesta. Questo valore può essere usato in due modi. Può essere usato per annullare l'operazione usando WSACancelAsyncRequest oppure per trovare una corrispondenza con operazioni asincrone e messaggi di completamento esaminando il parametro del messaggio wParam .

Se non è stato possibile avviare l'operazione asincrona, WSAAsyncGetHostByName restituisce un valore zero e un numero di errore specifico può essere recuperato chiamando WSAGetLastError.

Quando una finestra dell'applicazione riceve un messaggio, è possibile impostare i codici di errore seguenti. Come descritto in precedenza, possono essere estratti dal parametro lParam nel messaggio di risposta usando la macro WSAGETASYNCERROR.

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOBUFS	Spazio buffer insufficiente disponibile.
WSAEFAULT	Il nome o il parametro buf non si trova in una parte valida dello spazio indirizzi del processo.
WSAHOST_NOT_FOUND	Host di risposte autorevole non trovato.
WSATRY_AGAIN	Host non autenticativo non trovato o SERVERFAIL.
WSANO_RECOVERY	Errori non irreversibili: EXR, RIFIUTATO, NOTIMP.
WSANO_DATA	Nome valido, nessun record di dati di tipo richiesto.

Al momento della chiamata di funzione possono verificarsi gli errori seguenti e indicare che non è stato possibile avviare l'operazione asincrona.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario che venga eseguita una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEWOULDBLOCK	L'operazione asincrona non può essere pianificata in questo momento a causa di risorse o altri vincoli all'interno dell'implementazione di Windows Sockets.

Commenti

La funzione WSAAsyncGetHostByName è una versione asincrona di gethostbyname e viene usata per recuperare il nome host e le informazioni sull'indirizzo corrispondenti a un nome host. Windows Sockets avvia l'operazione e torna immediatamente al chiamante, passando un handle di attività asincrono opaco che l'applicazione può usare per identificare l'operazione. Al termine dell'operazione, i risultati (se presenti) vengono copiati nel buffer fornito dal chiamante e viene inviato un messaggio alla finestra dell'applicazione.

Al termine dell'operazione asincrona, la finestra dell'applicazione indicata dal parametro hWnd riceve il messaggio nel parametro wMsg . Il parametro wParam contiene l'handle di attività asincrono restituito dalla chiamata di funzione originale. Gli alti 16 bit di lParam contengono qualsiasi codice di errore. Il codice di errore può essere qualsiasi errore definito in Winsock2.h. Un codice di errore pari a zero indica il completamento dell'operazione asincrona.

Al termine, il buffer specificato nella chiamata di funzione originale contiene una struttura hostent . Per accedere agli elementi di questa struttura, è necessario eseguire il cast dell'indirizzo del buffer originale a un puntatore di struttura hostent e accedere in base alle esigenze.

Se il codice di errore è WSAENOBUFS, la dimensione del buffer specificato da buflen nella chiamata originale era troppo piccola per contenere tutte le informazioni risultanti. In questo caso, i 16 bit bassi di lParam contengono le dimensioni del buffer necessarie per fornire tutte le informazioni necessarie. Se l'applicazione decide che i dati parziali non sono adeguati, può eseguire nuovamente la chiamata di funzione WSAAsyncGetHostByName con un buffer sufficientemente grande da ricevere tutte le informazioni desiderate, ovvero non inferiori ai 16 bit bassi di lParam.

Il buffer specificato per questa funzione viene usato da Windows Sockets per costruire una struttura hostent insieme al contenuto delle aree dati a cui fanno riferimento i membri della stessa struttura hostent . Per evitare l'errore WSAENOBUFS , l'applicazione deve fornire un buffer di almeno MAXGETHOSTSTRUCT byte (come definito in Winsock2.h).

Il codice di errore e la lunghezza del buffer devono essere estratti da lParam usando le macro WSAGETASYNCERROR e WSAGETASYNCBUFLEN, definite in Winsock2.h come:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

L'uso di queste macro consente di ottimizzare la portabilità del codice sorgente per l'applicazione.

WSAAsyncGetHostByName è garantito per risolvere la stringa restituita da una chiamata riuscita a gethostname.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Winsock2.h, Winsock.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll