macro gethostbyname (wsipv6ok.h)

Artículo
08/28/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

void gethostbyname(
  [in]  a
);

Parámetros

[in] a

Puntero al nombre terminado en null del host que se va a resolver.

Valor devuelto

None

Observaciones

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	wsipv6ok.h (incluya Winsock2.h, Winsock.h)
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll