makro gethostbyname (wsipv6ok.h)
Fungsi gethostbyname mengambil informasi host yang sesuai dengan nama host dari database host.
Sintaks
void gethostbyname(
[in] a
);
Parameter
[in] a
Penunjuk ke nama host yang dihentikan null untuk diselesaikan.
Mengembalikan nilai
Tidak ada
Keterangan
Fungsi gethostbyname mengembalikan pointer ke struktur hostent —struktur yang dialokasikan oleh Windows Sockets. Struktur hostent berisi hasil pencarian yang berhasil untuk host yang ditentukan dalam parameter nama .
Jika host yang ditentukan dalam parameter nama memiliki alamat IPv4 dan IPv6, hanya alamat IPv4 yang akan dikembalikan. Fungsi gethostbyname hanya dapat mengembalikan alamat IPv4 untuk parameter nama . Fungsi getaddrinfo dan struktur addrinfo terkait harus digunakan jika alamat IPv6 untuk host diperlukan atau jika alamat IPv4 dan IPv6 untuk host diperlukan.
Jika parameter nama menunjuk ke string atau nama kosong adalah NULL, string yang dikembalikan sama dengan string yang dikembalikan oleh panggilan fungsi gethostname yang berhasil (nama host standar untuk komputer lokal).
Jika parameter nama berisi representasi string dari alamat IPv4 legal, maka alamat IPv4 biner yang mewakili string dikembalikan dalam struktur hosten . Anggota h_name struktur hostent berisi representasi string alamat IPv4 dan h_addr_list berisi alamat IPv4 biner. Jika parameter nama berisi representasi string alamat IPv6 atau alamat IPv4 ilegal, maka fungsi gethostbyname akan gagal dan mengembalikan WSANO_DATA.
Memori untuk struktur hosten yang dikembalikan oleh fungsi gethostbyname dialokasikan secara internal oleh Winsock DLL dari penyimpanan lokal utas. Hanya struktur hosten tunggal yang dialokasikan dan digunakan, tidak peduli berapa kali fungsi gethostbyaddr atau gethostbyname dipanggil pada utas. Struktur hosten yang dikembalikan harus disalin ke buffer aplikasi jika panggilan tambahan harus dilakukan ke fungsi gethostbyname atau gethostbyaddr pada utas yang sama. Jika tidak, nilai yang dikembalikan akan ditimpa oleh panggilan gethostbyname atau gethostbyaddr berikutnya pada utas yang sama. Memori internal yang dialokasikan untuk struktur hosten yang dikembalikan dirilis oleh Winsock DLL ketika utas keluar.
Aplikasi tidak boleh mencoba melepaskan memori yang digunakan oleh struktur hosten yang dikembalikan. Aplikasi tidak boleh mencoba memodifikasi struktur ini atau membebaskan salah satu komponennya. Selain itu, hanya satu salinan struktur ini yang dialokasikan per utas, sehingga aplikasi harus menyalin informasi apa pun yang dibutuhkan sebelum mengeluarkan panggilan fungsi lain ke gethostbyname atau gethostbyaddr .
Fungsi gethostbyname tidak dapat mengambil string alamat IP sebagai parameter yang diteruskan ke dalam nama dan menyelesaikannya ke nama host. Permintaan semacam itu diperlakukan persis sebagai representasi string alamat IPv4 atau nama host yang tidak diketahui diteruskan. Aplikasi dapat menggunakan inet_addr untuk mengonversi string alamat IPv4 ke alamat IPv4 biner, lalu menggunakan fungsi lain, gethostbyaddr, untuk menyelesaikan alamat IPv4 ke nama host.
Contoh Kode
Contoh berikut menunjukkan penggunaan fungsi 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: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.
Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | wsipv6ok.h (termasuk Winsock2.h, Winsock.h) |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.dll |