Funzione WSAAsyncGetHostByName (winsock2.h)

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

Sintassi

HANDLE WSAAPI 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 esito positivo o negativo dell'operazione stessa.

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

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

I codici di errore seguenti possono essere impostati quando una finestra dell'applicazione riceve un messaggio. Come descritto in precedenza, possono essere estratti dall'oggetto lParam nel messaggio di risposta usando la macro WSAGETASYNCERROR.

Gli errori seguenti possono verificarsi al momento della chiamata alla funzione e indicano che l'operazione asincrona non può essere avviata.

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 Socket avvia l'operazione e restituisce immediatamente al chiamante, passando un handle 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. I 16 bit elevati 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 del completamento, il buffer specificato nella chiamata di funzione originale contiene una struttura hostent . Per accedere agli elementi di questa struttura, l'indirizzo del buffer originale deve essere eseguito il cast in un puntatore della struttura hostent e accessibile in base alle esigenze.

Se il codice di errore è WSAENOBUFS, le dimensioni del buffer specificato da buflen nella chiamata originale erano troppo piccole 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, è possibile riemettere la chiamata alla funzione WSAAsyncGetHostByName con un buffer abbastanza grande per ricevere tutte le informazioni desiderate, ovvero non più piccole rispetto ai bassi 16 bit 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 dall'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 ottimizza la portabilità del codice sorgente per l'applicazione.

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

Requisiti

Vedi anche

WSACancelAsyncRequest

Funzioni Winsock

Informazioni di riferimento su Winsock

getaddrinfo

gethostbyname

getnameinfo

hostent