macro gethostbyname (wsipv6ok.h)

Article
08/28/2023

La fonction gethostbyname récupère les informations d’hôte correspondant à un nom d’hôte à partir d’une base de données hôte.

Note La fonction gethostbyname a été dépréciée par l’introduction de la fonction getaddrinfo . Les développeurs qui créent des applications Windows Sockets 2 sont invités à utiliser la fonction getaddrinfo au lieu de gethostbyname.

Syntaxe

void gethostbyname(
  [in]  a
);

Paramètres

[in] a

Pointeur vers le nom terminé par null de l’hôte à résoudre.

Valeur de retour

None

Remarques

La fonction gethostbyname retourne un pointeur vers une structure hostente , une structure allouée par Windows Sockets. La structure hostent contient les résultats d’une recherche réussie pour l’hôte spécifié dans le paramètre name .

Si l’hôte spécifié dans le paramètre name a à la fois des adresses IPv4 et IPv6, seules les adresses IPv4 sont retournées. La fonction gethostbyname peut uniquement retourner des adresses IPv4 pour le paramètre name . La fonction getaddrinfo et la structure addrinfo associée doivent être utilisées si des adresses IPv6 pour l’hôte sont requises ou si les adresses IPv4 et IPv6 pour l’hôte sont requises.

Si le paramètre name pointe vers une chaîne vide ou si le nom est NULL, la chaîne retournée est identique à la chaîne retournée par un appel de fonction gethostname réussi (le nom d’hôte standard de l’ordinateur local).

Si le paramètre name contient une représentation sous forme de chaîne d’une adresse IPv4 légale, l’adresse IPv4 binaire qui représente la chaîne est retournée dans la structure hostente . Le h_name membre de la structure hostent contient la représentation sous forme de chaîne de l’adresse IPv4 et le h_addr_list contient l’adresse IPv4 binaire. Si le paramètre name contient une représentation sous forme de chaîne d’une adresse IPv6 ou une adresse IPv4 non conforme, la fonction gethostbyname échoue et retourne WSANO_DATA.

La mémoire de la structure hostente retournée par la fonction gethostbyname est allouée en interne par la DLL Winsock à partir du stockage local du thread. Une seule structure hostente est allouée et utilisée, quel que soit le nombre d’appel des fonctions gethostbyaddr ou gethostbyname sur le thread. La structure hostent retournée doit être copiée dans une mémoire tampon d’application si des appels supplémentaires doivent être effectués aux fonctions gethostbyname ou gethostbyaddr sur le même thread. Sinon, la valeur de retour sera remplacée par les appels gethostbyname ou gethostbyaddr suivants sur le même thread. La mémoire interne allouée à la structure hostente retournée est libérée par la DLL Winsock lorsque le thread se ferme.

Une application ne doit pas essayer de libérer la mémoire utilisée par la structure hostente retournée. L’application ne doit jamais tenter de modifier cette structure ou de libérer aucun de ses composants. En outre, une seule copie de cette structure étant allouée par thread, l’application doit copier toutes les informations dont elle a besoin avant d’émettre d’autres appels de fonction à gethostbyname ou gethostbyaddr .

La fonction gethostbyname ne peut pas prendre une chaîne d’adresse IP comme paramètre qui lui est passé dans le nom et la résoudre en nom d’hôte. Une telle requête est traitée exactement comme une représentation sous forme de chaîne d’une adresse IPv4 ou d’un nom d’hôte inconnu passé. Une application peut utiliser la inet_addr pour convertir une chaîne d’adresse IPv4 en adresse IPv4 binaire, puis utiliser une autre fonction, gethostbyaddr, pour résoudre l’adresse IPv4 en un nom d’hôte.

Note La fonction gethostbyname ne case activée pas la taille du paramètre name avant de passer la mémoire tampon. Avec un paramètre de nom de taille incorrecte, une altération du tas peut se produire.

Exemple de code

Les exemples suivants illustrent l’utilisation de la fonction 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 : cette fonction est prise en charge pour les applications Windows Phone Store sur Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	wsipv6ok.h (inclure Winsock2.h, Winsock.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll