gethostbyname-Makro (wsipv6ok.h)

Die gethostbyname-Funktion ruft Hostinformationen ab, die einem Hostnamen entsprechen, aus einer Hostdatenbank.

Syntax

void gethostbyname(
  [in]  a
);

Parameter

[in] a

Ein Zeiger auf den NULL-endendten Namen des aufzulösenden Hosts.

Rückgabewert

Keine

Bemerkungen

Die gethostbyname-Funktion gibt einen Zeiger auf eine Hostentstruktur zurück– eine Struktur, die von Windows Sockets zugeordnet wird. Die hostent-Struktur enthält die Ergebnisse einer erfolgreichen Suche nach dem im name-Parameter angegebenen Host.

Wenn der im name-Parameter angegebene Host sowohl über IPv4- als auch über IPv6-Adressen verfügt, werden nur die IPv4-Adressen zurückgegeben. Die gethostbyname-Funktion kann nur IPv4-Adressen für den name-Parameter zurückgeben. Die getaddrinfo-Funktion und die zugehörige addrinfo-Struktur sollten verwendet werden, wenn IPv6-Adressen für den Host erforderlich sind oder wenn sowohl IPv4- als auch IPv6-Adressen für den Host erforderlich sind.

Wenn der name-Parameter auf eine leere Zeichenfolge zeigt oder der NameNULL ist, entspricht die zurückgegebene Zeichenfolge der Zeichenfolge, die von einem erfolgreichen Aufruf der gethostname-Funktion zurückgegeben wird (der Standardhostname für den lokalen Computer).

Wenn der name-Parameter eine Zeichenfolgendarstellung einer legalen IPv4-Adresse enthält, wird die binäre IPv4-Adresse, die die Zeichenfolge darstellt, in der Hostentstruktur zurückgegeben. Der h_name Member der Hostent-Struktur enthält die Zeichenfolgendarstellung der IPv4-Adresse und die h_addr_list die binäre IPv4-Adresse. Wenn der name-Parameter eine Zeichenfolgendarstellung einer IPv6-Adresse oder einer unzulässigen IPv4-Adresse enthält, schlägt die gethostbyname-Funktion fehl und gibt WSANO_DATA zurück.

Der Arbeitsspeicher für die hostent-Struktur , die von der gethostbyname-Funktion zurückgegeben wird, wird intern von der Winsock-DLL aus dem lokalen Threadspeicher zugeordnet. Es wird nur eine einzelne hostent-Struktur zugeordnet und verwendet, unabhängig davon, wie oft die Funktionen gethostbyaddr oder gethostbyname im Thread aufgerufen werden. Die zurückgegebene hostent-Struktur muss in einen Anwendungspuffer kopiert werden, wenn zusätzliche Aufrufe an die Funktionen gethostbyname oder gethostbyaddr im selben Thread ausgeführt werden sollen. Andernfalls wird der Rückgabewert durch nachfolgende gethostbyname - oder gethostbyaddr-Aufrufe im selben Thread überschrieben. Der für die zurückgegebene Hostent-Struktur zugeordnete interne Speicher wird von der Winsock-DLL freigegeben, wenn der Thread beendet wird.

Eine Anwendung sollte nicht versuchen, den von der zurückgegebenen Hostent-Struktur verwendeten Arbeitsspeicher freizugeben. Die Anwendung darf niemals versuchen, diese Struktur zu ändern oder ihre Komponenten frei zu geben. Darüber hinaus wird pro Thread nur eine Kopie dieser Struktur zugeordnet, sodass die Anwendung alle benötigten Informationen kopieren sollte, bevor sie andere Funktionsaufrufe für gethostbyname oder gethostbyaddr ausgibt .

Die gethostbyname-Funktion kann keine IP-Adresszeichenfolge als Parameter annehmen, der im Namen an sie übergeben wird, und sie in einen Hostnamen auflösen. Eine solche Anforderung wird genau so behandelt, wie eine Zeichenfolgendarstellung einer IPv4-Adresse oder eines unbekannten Hostnamens übergeben wurde. Eine Anwendung kann die inet_addr verwenden, um eine IPv4-Adresszeichenfolge in eine binäre IPv4-Adresse zu konvertieren, und dann eine andere Funktion, gethostbyaddr, verwenden, um die IPv4-Adresse in einen Hostnamen aufzulösen.

Beispielcode

#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: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Weitere Informationen

GetAddrInfoEx

GetAddrInfoW

WSAAsyncGetHostByName

Winsock-Funktionen

Winsock-Referenz

addrinfo

addrinfoW

getaddrinfo

gethostbyaddr

Gethostname

hostent

inet_addr