macro gethostbyname (wsipv6ok.h)

Articolo
08/28/2023

La funzione gethostbyname recupera le informazioni host corrispondenti a un nome host da un database host.

Nota La funzione gethostbyname è stata deprecata dall'introduzione della funzione getaddrinfo . Gli sviluppatori che creano applicazioni Windows Sockets 2 sono invitati a usare la funzione getaddrinfo anziché gethostbyname.

Sintassi

void gethostbyname(
  [in]  a
);

Parametri

[in] a

Puntatore al nome con terminazione Null dell'host da risolvere.

Valore restituito

nessuno

Osservazioni

La funzione gethostbyname restituisce un puntatore a una struttura hostent , ovvero una struttura allocata da Windows Sockets. La struttura hostent contiene i risultati di una ricerca corretta dell'host specificato nel parametro name .

Se l'host specificato nel parametro name ha indirizzi IPv4 e IPv6, verranno restituiti solo gli indirizzi IPv4. La funzione gethostbyname può restituire solo indirizzi IPv4 per il parametro name . È necessario usare la funzione getaddrinfo e la struttura addrinfo associata se sono necessari indirizzi IPv6 per l'host o se sono necessari entrambi gli indirizzi IPv4 e IPv6 per l'host.

Se il parametro name punta a una stringa o un nome vuoto è NULL, la stringa restituita corrisponde alla stringa restituita da una chiamata di funzione gethostname riuscita (il nome host standard per il computer locale).

Se il parametro name contiene una rappresentazione di stringa di un indirizzo IPv4 legale, l'indirizzo IPv4 binario che rappresenta la stringa viene restituito nella struttura hostent . Il membro h_name della struttura hostent contiene la rappresentazione di stringa dell'indirizzo IPv4 e il h_addr_list contiene l'indirizzo IPv4 binario. Se il parametro name contiene una rappresentazione di stringa di un indirizzo IPv6 o un indirizzo IPv4 non valido, 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 alle funzioni gethostbyname o gethostbyaddr nello stesso thread. In caso contrario, il valore restituito verrà sovrascritto dalle successive chiamate 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 i relativi componenti. Inoltre, viene allocata una sola copia di questa struttura per ogni thread, quindi l'applicazione deve copiare tutte le informazioni necessarie prima di eseguire qualsiasi altra chiamata di funzione a 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 di stringa di un indirizzo IPv4 o viene passato un nome host sconosciuto. Un'applicazione può usare il inet_addr per convertire una stringa di indirizzo IPv4 in un indirizzo IPv4 binario, quindi usare un'altra funzione, gethostbyaddr, per risolvere l'indirizzo IPv4 in un nome host.

Nota La funzione gethostbyname non controlla le dimensioni del parametro name prima di passare il buffer. Con un parametro name di dimensioni non corrette, può verificarsi un danneggiamento dell'heap.

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 dello Store di Windows Phone 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	wsipv6ok.h (include Winsock2.h, Winsock.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll