funzione gethostbyname (winsock.h)
La funzione gethostbyname recupera le informazioni host corrispondenti a un nome host da un database host.
Sintassi
hostent * gethostbyname(
const char *name
);
Parametri
name
TBD
Valore restituito
Se non si verifica alcun errore, gethostbyname restituisce un puntatore alla struttura hostent descritta in precedenza. In caso contrario, restituisce un puntatore Null e un numero di errore specifico può essere recuperato chiamando WSAGetLastError.
| Codice di errore | Significato |
|---|---|
| Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Il sottosistema di rete non è riuscito. | |
| Host di risposte autorevole non trovato. | |
| Host non autenticativo non trovato o errore del server. | |
| Si è verificato un errore non recuperabile. | |
|
Il nome richiesto è valido, ma non sono stati trovati dati del tipo richiesto. Questo errore viene restituito anche se il parametro name contiene una rappresentazione stringa di un indirizzo IPv6 o un indirizzo IPv4 illegale.
Questo errore non deve essere interpretato per significare che il parametro name contiene una stringa di nome convalidata per un protocollo specifico (un nome host IP, ad esempio). Poiché Winsock supporta più provider di servizi di nome, un nome può potenzialmente essere valido per un provider e non accettato da un altro provider. |
|
| Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| Il parametro name non è una parte valida dello spazio degli indirizzi utente. | |
| Una chiamata di Windows Socket 1.1 bloccata è stata annullata tramite WSACancelBlockingCall. |
Commenti
La funzione gethostbyname restituisce un puntatore a una struttura hostent , una struttura allocata da Windows Sockets. La struttura hostent contiene i risultati di una ricerca riuscita dell'host specificato nel parametro name .
Se l'host specificato nel parametro name ha sia indirizzi IPv4 che IPv6, verranno restituiti solo gli indirizzi IPv4. La funzione gethostbyname può restituire solo indirizzi IPv4 per il parametro name . La funzione getaddrinfo e la struttura addrinfo associata devono essere usate se sono necessari indirizzi IPv6 per l'host o se sono necessari indirizzi IPv4 e IPv6 per l'host.
Se il parametro name punta a una stringa vuota o al nome è NULL, la stringa restituita corrisponde alla stringa restituita da una chiamata di funzione gethostname completata (nome host standard per il computer locale).
Se il parametro name contiene una rappresentazione stringa di un indirizzo IPv4 legale, l'indirizzo IPv4 binario che rappresenta la stringa viene restituito nella struttura hostent . Il h_name membro della struttura hostent contiene la rappresentazione stringa dell'indirizzo IPv4 e la h_addr_list contiene l'indirizzo IPv4 binario. Se il parametro name contiene una rappresentazione stringa di un indirizzo IPv6 o un indirizzo IPv4 illegale, la funzione gethostbyname avrà esito negativo e restituirà WSANO_DATA.
La memoria per la struttura hostent restituita dalla funzione gethostbyname viene allocata internamente dalla DLL Winsock dall'archiviazione locale del thread. Solo una singola struttura hostent viene allocata e usata, indipendentemente dal numero di volte in cui vengono chiamate le funzioni gethostbyaddr o gethostbyname nel thread. La struttura hostent restituita deve essere copiata in un buffer dell'applicazione se devono essere effettuate chiamate aggiuntive per le funzioni gethostbyname o gethostbyaddr nello stesso thread. In caso contrario, il valore restituito verrà sovrascritto dalla successiva chiamata gethostbyname o gethostbyaddr nello stesso thread. La memoria interna allocata per la struttura hostent restituita viene rilasciata dalla DLL Winsock quando il thread viene chiuso.
Un'applicazione non deve provare a rilasciare la memoria usata dalla struttura hostent restituita. L'applicazione non deve mai tentare di modificare questa struttura o di liberare uno dei relativi componenti. Inoltre, solo una copia di questa struttura viene allocata per thread, quindi l'applicazione deve copiare tutte le informazioni necessarie prima di inviare qualsiasi altra chiamata di funzione per gethostbyname o gethostbyaddr .
La funzione gethostbyname non può accettare una stringa di indirizzo IP come parametro passato al nome e risolverla in un nome host. Tale richiesta viene considerata esattamente come una rappresentazione stringa di un indirizzo IPv4 o un nome host sconosciuto sono stati passati. Un'applicazione può usare la inet_addr per convertire una stringa di indirizzi IPv4 in un indirizzo IPv4 binario, quindi usare un'altra funzione, gethostbyaddr, per risolvere l'indirizzo IPv4 in un nome host.
Codice di esempio
Negli esempi seguenti viene illustrato l'uso della funzione gethostbyname .#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <windows.h>
#pragma comment(lib, "ws2_32.lib")
int main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwError;
int i = 0;
struct hostent *remoteHost;
char *host_name;
struct in_addr addr;
char **pAlias;
// Validate the parameters
if (argc != 2) {
printf("usage: %s hostname\n", argv[0]);
printf(" to return the IP addresses for the host\n");
printf(" %s www.contoso.com\n", argv[0]);
printf(" or\n");
printf(" %s IPv4string\n", argv[0]);
printf(" to return an IPv4 binary address for an IPv4string\n");
printf(" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
return 1;
}
host_name = argv[1];
printf("Calling gethostbyname with %s\n", host_name);
remoteHost = gethostbyname(host_name);
if (remoteHost == NULL) {
dwError = WSAGetLastError();
if (dwError != 0) {
if (dwError == WSAHOST_NOT_FOUND) {
printf("Host not found\n");
return 1;
} else if (dwError == WSANO_DATA) {
printf("No data record found\n");
return 1;
} else {
printf("Function failed with error: %ld\n", dwError);
return 1;
}
}
} else {
printf("Function returned:\n");
printf("\tOfficial name: %s\n", remoteHost->h_name);
for (pAlias = remoteHost->h_aliases; *pAlias != 0; pAlias++) {
printf("\tAlternate name #%d: %s\n", ++i, *pAlias);
}
printf("\tAddress type: ");
switch (remoteHost->h_addrtype) {
case AF_INET:
printf("AF_INET\n");
break;
case AF_NETBIOS:
printf("AF_NETBIOS\n");
break;
default:
printf(" %d\n", remoteHost->h_addrtype);
break;
}
printf("\tAddress length: %d\n", remoteHost->h_length);
i = 0;
if (remoteHost->h_addrtype == AF_INET)
{
while (remoteHost->h_addr_list[i] != 0) {
addr.s_addr = *(u_long *) remoteHost->h_addr_list[i++];
printf("\tIP Address #%d: %s\n", i, inet_ntoa(addr));
}
}
else if (remoteHost->h_addrtype == AF_NETBIOS)
{
printf("NETBIOS address was returned\n");
}
}
return 0;
}
Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.
Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.
Requisiti
| 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 | Windows |
| Intestazione | winsock.h (include Winsock2.h, Winsock.h) |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |