gethostbyname, fonction (winsock2.h)

Article
03/04/2024

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

hostent *WSAAPI gethostbyname(
  const char *name
);

Paramètres

name

TBD

Valeur retournée

Si aucune erreur ne se produit, gethostbyname retourne un pointeur vers la structure hostente décrite ci-dessus. Sinon, elle retourne un pointeur Null et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAHOST_NOT_FOUND	Hôte de réponse faisant autorité introuvable.
WSATRY_AGAIN	Hôte non authentifié introuvable ou défaillance du serveur.
WSANO_RECOVERY	Une erreur non récupérable s’est produite.
WSANO_DATA	Le nom demandé est valide, mais aucune donnée du type requis n'a été trouvée. Cette erreur est également retournée si le paramètre name contient une représentation sous forme de chaîne d’une adresse IPv6 ou d’une adresse IPv4 non conforme. Cette erreur ne doit pas être interprétée comme signifiant que le paramètre name contient une chaîne de nom qui a été validée pour un protocole particulier (un nom d’hôte IP, par exemple). Étant donné que Winsock prend en charge plusieurs fournisseurs de services de nom, un nom peut potentiellement être valide pour un fournisseur et non accepté par un autre fournisseur.
WSAEINPROGRESS	Un appel Windows Sockets 1.1 bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEFAULT	Le paramètre name n’est pas une partie valide de l’espace d’adressage utilisateur.
WSAEINTR	Un appel Windows Socket 1.1 bloquant a été annulé via WSACancelBlockingCall.

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	winsock2.h (inclure Winsock2.h, Winsock.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll