gethostbyname 宏 (wsipv6ok.h)

项目
03/04/2024

gethostbyname 函数从主机数据库中检索与主机名对应的主机信息。

注意引入 getaddrinfo 函数已弃用 gethostbyname 函数。建议创建 Windows 套接字 2 应用程序的开发人员使用 getaddrinfo 函数而不是 gethostbyname。

语法

void gethostbyname(
  [in]  a
);

参数

[in] a

指向要解析的主机的 以 null 结尾的名称的指针。

返回值

无

备注

gethostbyname 函数返回指向主机结构（由 Windows 套接字分配的结构）的指针。 hostent 结构包含成功搜索 name 参数中指定的主机的结果。

如果 name 参数中指定的主机同时具有 IPv4 和 IPv6 地址，则仅返回 IPv4 地址。 gethostbyname 函数只能返回 name 参数的 IPv4 地址。如果需要主机的 IPv6 地址，或者主机需要 IPv4 和 IPv6 地址，则应使用 getaddrinfo 函数和关联的 addrinfo 结构。

如果 name 参数指向空字符串或名称为 NULL，则返回的字符串与成功的 gethostname 函数调用返回的字符串相同， (本地计算机的标准主机名) 。

如果 name 参数包含合法 IPv4 地址的字符串表示形式，则在主机结构中返回表示该字符串的二进制 IPv4 地址。 hostent 结构的 h_name 成员包含 IPv4 地址的字符串表示形式，h_addr_list包含二进制 IPv4 地址。如果 name 参数包含 IPv6 地址或非法 IPv4 地址的字符串表示形式，则 gethostbyname 函数将失败并返回 WSANO_DATA。

gethostbyname 函数返回的主机结构的内存由 Winsock DLL 从线程本地存储内部分配。无论在线程上调用 gethostbyaddr 或 gethostbyname 函数多少次，都只分配和使用一个 hostent 结构。如果要对同一线程上的 gethostbyname 或 gethostbyaddr 函数进行其他调用，则必须将返回的 hostent 结构复制到应用程序缓冲区。否则，返回值将被同一线程上的后续 gethostbyname 或 gethostbyaddr 调用覆盖。为返回的主机结构分配的内部内存在线程退出时由 Winsock DLL 释放。

应用程序不应尝试释放返回的 hostent 结构使用的内存。应用程序不得尝试修改此结构或释放其任何组件。此外，每个线程只分配此结构的一个副本，因此应用程序应在向 gethostbyname 或 gethostbyaddr 发出任何其他函数调用之前复制它所需的任何信息。

gethostbyname 函数不能将 IP 地址字符串作为在名称中传递给它的参数并将其解析为主机名。此类请求完全被视为 IPv4 地址或传递了未知主机名的字符串表示形式。应用程序可以使用 inet_addr 将 IPv4 地址字符串转换为二进制 IPv4 地址，然后使用另一个函数 gethostbyaddr 将 IPv4 地址解析为主机名。

注意gethostbyname 函数在传递缓冲区之前不会检查 name 参数的大小。如果名称参数大小不正确，可能会发生堆损坏。

示例代码

以下示例演示如何使用 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：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

要求

要求	值
最低受支持的客户端	Windows 8.1、Windows Vista [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	wsipv6ok.h (包括 Winsock2.h、Winsock.h)
Library	Ws2_32.lib
DLL	Ws2_32.dll