Función gethostbyname (winsock.h)

Artículo
03/15/2023

La función gethostbyname recupera la información de host correspondiente a un nombre de host de una base de datos host.

Nota La función gethostbyname ha quedado en desuso mediante la introducción de la función getaddrinfo . Se insta a los desarrolladores que crean aplicaciones de Windows Sockets 2 a usar la función getaddrinfo en lugar de gethostbyname.

Sintaxis

hostent * gethostbyname(
  const char *name
);

Parámetros

name

TBD

Valor devuelto

Si no se produce ningún error, gethostbyname devuelve un puntero a la estructura de host descrita anteriormente. De lo contrario, devuelve un puntero nulo y se puede recuperar un número de error específico llamando a WSAGetLastError.

Código de error	Significado
WSANOTINITIALISED	Debe producirse una llamada de WSAStartup correcta antes de usar esta función.
WSAENETDOWN	Error en el subsistema de red.
WSAHOST_NOT_FOUND	No se encontró el host de respuesta autoritativo.
WSATRY_AGAIN	No se encontró el host no autenticado o el error del servidor.
WSANO_RECOVERY	Error irrecuperable.
WSANO_DATA	El nombre solicitado es válido, pero no se ha encontrado ningún dato del tipo solicitado. Este error también se devuelve si el parámetro name contiene una representación de cadena de una dirección IPv6 o una dirección IPv4 no válida. Este error no debe interpretarse para indicar que el parámetro name contiene una cadena de nombre que se ha validado para un protocolo determinado (un nombre de host IP, por ejemplo). Dado que Winsock admite varios proveedores de servicios de nombres, un nombre puede ser válido para un proveedor y no aceptado por otro proveedor.
WSAEINPROGRESS	Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEFAULT	El parámetro name no es una parte válida del espacio de direcciones del usuario.
WSAEINTR	Se canceló una llamada de Bloqueo de Windows Socket 1.1 a través de WSACancelBlockingCall.

Comentarios

La función gethostbyname devuelve un puntero a una estructura de host , una estructura asignada por Windows Sockets. La estructura del host contiene los resultados de una búsqueda correcta del host especificado en el parámetro name .

Si el host especificado en el parámetro name tiene direcciones IPv4 e IPv6, solo se devolverán las direcciones IPv4. La función gethostbyname solo puede devolver direcciones IPv4 para el parámetro name . Se debe usar la función getaddrinfo y la estructura addrinfo asociada si se requieren direcciones IPv6 para el host o si se requieren direcciones IPv4 e IPv6 para el host.

Si el parámetro name apunta a una cadena vacía o un nombre es NULL, la cadena devuelta es la misma que la cadena devuelta por una llamada de función gethostname correcta (el nombre de host estándar para el equipo local).

Si el parámetro name contiene una representación de cadena de una dirección IPv4 legal, la dirección IPv4 binaria que representa la cadena se devuelve en la estructura del host . El miembro h_name de la estructura hostent contiene la representación de cadena de la dirección IPv4 y el h_addr_list contiene la dirección IPv4 binaria. Si el parámetro name contiene una representación de cadena de una dirección IPv6 o una dirección IPv4 no válida, se producirá un error en la función gethostbyname y se devolverá WSANO_DATA.

La memoria de la estructura del host devuelta por la función gethostbyname se asigna internamente mediante el archivo DLL winsock desde el almacenamiento local del subproceso. Solo se asigna y usa una única estructura de host , independientemente de cuántas veces se llamen a las funciones gethostbyaddr o gethostbyname en el subproceso. La estructura de host devuelta debe copiarse en un búfer de aplicación si se van a realizar llamadas adicionales a las funciones gethostbyname o gethostbyaddr en el mismo subproceso. De lo contrario, el valor devuelto se sobrescribirá mediante llamadas gethostbyname o gethostbyaddr posteriores en el mismo subproceso. La memoria interna asignada para la estructura de host devuelta se libera mediante la DLL winsock cuando se cierra el subproceso.

Una aplicación no debe intentar liberar la memoria usada por la estructura hostent devuelta. La aplicación nunca debe intentar modificar esta estructura o liberar cualquiera de sus componentes. Además, solo se asigna una copia de esta estructura por subproceso, por lo que la aplicación debe copiar cualquier información que necesite antes de emitir cualquier otra llamada de función a gethostbyname o gethostbyaddr .

La función gethostbyname no puede tomar una cadena de dirección IP como parámetro que se le pasa en el nombre y resolverla en un nombre de host. Dicha solicitud se trata exactamente como una representación de cadena de una dirección IPv4 o se pasó un nombre de host desconocido. Una aplicación puede usar el inet_addr para convertir una cadena de dirección IPv4 en una dirección IPv4 binaria y, a continuación, usar otra función, gethostbyaddr, para resolver la dirección IPv4 en un nombre de host.

Nota La función gethostbyname no comprueba el tamaño del parámetro name antes de pasar el búfer. Con un parámetro de nombre de tamaño incorrecto, se pueden producir daños en el montón.

Código de ejemplo

En los ejemplos siguientes se muestra el uso de la función 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: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock.h (incluya Winsock2.h, Winsock.h)
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll