Fungsi GetHostNameW (winsock2.h)

Artikel
03/08/2023

Fungsi GetHostNameW mengambil nama host standar untuk komputer lokal sebagai string Unicode.

Sintaks

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

Parameter

[out] name

Penunjuk ke buffer yang menerima nama host lokal sebagai string Unicode yang dihentikan null.

[in] namelen

Panjang, dalam karakter lebar, dari buffer yang diacu oleh parameter nama .

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, GetHostNameW mengembalikan nol. Jika tidak, ia mengembalikan SOCKET_ERROR dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan	Makna
WSAEFAULT	Parameter nama adalah penunjuk NULL atau bukan bagian yang valid dari ruang alamat pengguna. Kesalahan ini juga dikembalikan jika ukuran buffer yang ditentukan oleh parameter namelen terlalu kecil untuk menahan nama host lengkap.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAENETDOWN	Subsistem jaringan gagal.

Keterangan

Fungsi GetHostNameW mengembalikan nama host lokal ke dalam buffer yang ditentukan oleh parameter nama di Unicode (UTF-16). Nama host dikembalikan sebagai string Unicode yang dihentikan null. Bentuk nama host tergantung pada penyedia Windows Sockets—itu bisa menjadi nama host sederhana, atau bisa menjadi nama domain yang sepenuhnya memenuhi syarat. Namun, dijamin bahwa nama yang dikembalikan akan berhasil diurai oleh GetAddrInfoW.

Dengan pertumbuhan Internet, ada kebutuhan yang berkembang untuk mengidentifikasi nama host Internet untuk bahasa lain yang tidak diwakili oleh set karakter ASCII. Pengidentifikasi yang memfasilitasi kebutuhan ini dan memungkinkan karakter non-ASCII (Unicode) direpresentasikan sebagai string karakter ASCII khusus (Punycode) dikenal sebagai Nama Domain Internasional (IDN). Mekanisme yang disebut Internationalisasi Nama Domain dalam Aplikasi (IDNA) digunakan untuk menangani IDN dengan cara standar. Fungsi GetHostNameW tidak mengonversi nama host lokal antara Punycode dan Unicode. Fungsi GetAddrInfoW menyediakan dukungan untuk penguraian Nama Domain Internasional (IDN) dan melakukan pengodean dan konversi Punycode/IDN.

Jika fungsi GetHostNameW digunakan pada sumber daya kluster pada Windows Server 2012 dan variabel lingkungan CLUSTER_NETWORK_NAME ditentukan, maka nilai dalam variabel lingkungan ini mengambil alih nama host aktual dan dikembalikan. Pada sumber daya kluster, variabel lingkungan CLUSTER_NETWORK_NAME berisi nama kluster.

Fungsi GetHostNameW meminta penyedia namespace layanan untuk menentukan nama host lokal menggunakan GUID SVCID_HOSTNAME yang ditentukan dalam file header Svgguid.h . Jika tidak ada penyedia namespace layanan yang merespons, maka fungsi GetHostNameW mengembalikan nama NetBIOS komputer lokal di Unicode.

Panjang maksimum, dalam karakter lebar, dari string yang dikembalikan dalam buffer yang diacu oleh parameter nama tergantung pada penyedia namespace layanan, tetapi string ini harus 256 karakter lebar atau kurang. Jadi, jika buffer 256 karakter lebar diteruskan dalam parameter nama dan parameter namelen diatur ke 256, ukuran buffer akan selalu memadai.

Catatan Jika tidak ada nama host lokal yang telah dikonfigurasi, GetHostNameW harus berhasil dan mengembalikan nama host token yang dapat diselesaikan GetAddrInfoW .

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


Klien minimum yang didukung	Windows 8.1, Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winsock2.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll

Lihat juga

Bagikan melalui