Fungsi GetNameInfoW (ws2tcpip.h)

Artikel
08/28/2023

Fungsi GetNameInfoW menyediakan resolusi nama independen protokol dari alamat ke nama host Unicode dan dari nomor port ke nama layanan Unicode.

Sintaks

INT WSAAPI GetNameInfoW(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PWCHAR         pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PWCHAR         pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

Parameter

[in] pSockaddr

Penunjuk ke struktur alamat soket yang berisi alamat IP dan nomor port soket. Untuk IPv4, parameter pSockaddr menunjuk ke struktur sockaddr_in . Untuk IPv6, parameter pSockaddr menunjuk ke struktur sockaddr_in6 .

[in] SockaddrLength

Panjangnya, dalam byte, dari struktur yang ditujukkan oleh parameter pSockaddr .

[out] pNodeBuffer

Penunjuk ke string Unicode untuk menahan nama host. Jika berhasil, penunjuk ke nama host Unicode dikembalikan sebagai Nama Domain yang Sepenuhnya Memenuhi Syarat (FQDN) secara default. Jika parameter pNodeBufferadalah NULL, ini menunjukkan pemanggil tidak ingin menerima string nama host.

[in] NodeBufferSize

Jumlah karakter WCHAR dalam buffer yang ditujukkan oleh parameter pNodeBuffer . Pemanggil harus menyediakan buffer yang cukup besar untuk menahan nama host Unicode, termasuk karakter NULL yang mengakhiri.

[out] pServiceBuffer

Penunjuk ke string Unicode untuk menyimpan nama layanan. Jika berhasil, penunjuk dikembalikan ke string Unicode yang mewakili nama layanan yang terkait dengan nomor port. Jika parameter pServiceBufferadalah NULL, ini menunjukkan pemanggil tidak ingin menerima string nama layanan.

[in] ServiceBufferSize

Jumlah karakter WCHAR dalam buffer yang ditujukkan oleh parameter pServiceBuffer . Pemanggil harus menyediakan buffer yang cukup besar untuk menahan nama layanan Unicode, termasuk karakter NULL yang mengakhiri.

[in] Flags

Nilai yang digunakan untuk menyesuaikan pemrosesan fungsi GetNameInfoW . Lihat bagian Keterangan.

Nilai kembali

Jika berhasil, GetNameInfoW mengembalikan nol. Setiap nilai pengembalian bukan nol menunjukkan kegagalan dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan bukan nol yang dikembalikan oleh fungsi GetNameInfoW juga memetakan ke serangkaian kesalahan yang diuraikan oleh rekomendasi Internet Engineering Task Force (IETF). Tabel berikut menunjukkan kode kesalahan ini dan setara WSA-nya. Disarankan agar kode kesalahan WSA digunakan, karena mereka menawarkan informasi kesalahan yang akrab dan komprehensif untuk programmer Winsock.

Nilai kesalahan	Setara WSA	Deskripsi
EAI_AGAIN	WSATRY_AGAIN	Terjadi kegagalan sementara dalam resolusi nama.
EAI_BADFLAGS	WSAEINVAL	Satu atau beberapa parameter yang tidak valid diteruskan ke fungsi GetNameInfoW . Kesalahan ini dikembalikan jika nama host diminta tetapi parameter NodeBufferSize adalah nol atau jika nama layanan diminta tetapi parameter ServiceBufferSize adalah nol.
EAI_FAIL	WSANO_RECOVERY	Terjadi kegagalan yang tidak dapat dipulihkan dalam resolusi nama.
EAI_FAMILY	WSAEAFNOSUPPORT	Anggota sa_family struktur alamat soket yang ditunjukkan oleh parameter pSockaddr tidak didukung.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Terjadi kegagalan alokasi memori.
EAI_NONAME	WSAHOST_NOT_FOUND	Nama layanan diminta, tetapi tidak ada nomor port yang ditemukan dalam struktur yang diacu oleh parameter pSockaddr atau tidak ada nama layanan yang cocok dengan nomor port yang ditemukan. NI_NAMEREQD diatur dan nama host tidak dapat ditemukan, atau parameter pNodeBuffer dan pServiceBufferadalah NULL.

Anda dapat menggunakan fungsi gai_strerror untuk mencetak pesan kesalahan berdasarkan kode EAI yang dikembalikan oleh fungsi GetNameInfoW . Fungsi gai_strerror disediakan untuk kepatuhan terhadap rekomendasi IETF, tetapi tidak aman untuk utas. Oleh karena itu, penggunaan fungsi Windows Sockets tradisional seperti WSAGetLastError direkomendasikan.

Selain itu, kode kesalahan berikut dapat dikembalikan.

Kode kesalahan	Makna
WSAEFAULT	Kesalahan ini dikembalikan jika parameter pSockaddr adalah NULL atau parameter SockaddrLength kurang dari panjang yang diperlukan untuk ukuran struktur sockaddr_in untuk IPv4 atau struktur sockaddr_in6 untuk IPv6.

Keterangan

Fungsi GetNameInfoW adalah versi Unicode dari fungsi yang menyediakan resolusi nama yang independen protokol. Fungsi GetNameInfoW digunakan untuk menerjemahkan konten struktur alamat soket ke nama node dan/atau nama layanan.

Untuk protokol IPv6 dan IPv4, resolusi nama dapat dilakukan oleh Sistem Nama Domain (DNS), file host lokal, atau dengan mekanisme penamaan lainnya. Fungsi ini dapat digunakan untuk menentukan nama host untuk alamat IPv4 atau IPv6, pencarian DNS terbalik, atau menentukan nama layanan untuk nomor port. Fungsi GetNameInfoW juga dapat digunakan untuk mengonversi alamat IP atau nomor port dalam struktur SOCKADDR menjadi string Unicode. Fungsi ini juga dapat digunakan untuk menentukan alamat IP untuk nama host.

Versi ANSI dari fungsi ini adalah getnameinfo.

Makro dalam file header Winsock menentukan nama fungsi kasus campuran GetNameInfo yang dapat digunakan ketika aplikasi ditargetkan untuk Windows XP dengan Paket Layanan 2 (SP2) dan yang lebih baru (_WIN32_WINNT >= 0x0502). Fungsi GetNameInfo ini harus dipanggil dengan parameter pNodeBuffer dan pServiceBuffer dari pointer jenis TCHAR. Ketika UNICODE atau _UNICODE ditentukan, GetNameInfo didefinisikan ke versi Unicode dan GetNameInfoW dipanggil dengan parameter host dan serv dari pointer jenis karakter. Ketika UNICODE atau _UNICODE tidak ditentukan, GetNameInfo didefinisikan ke versi ANSI dan getnameinfo dipanggil dengan parameter pNodeBuffer dan pServiceBuffer dari pointer jenis PWCHAR.

Untuk menyederhanakan penentuan persyaratan buffer untuk parameter pNodeBuffer dan pServiceBuffer , nilai berikut untuk panjang nama host maksimum dan nama layanan maksimum ditentukan dalam file header Ws2tcpip.h :

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Parameter Bendera dapat digunakan untuk menyesuaikan pemrosesan fungsi GetNameInfoW . Bendera berikut tersedia:

NI_NOFQDN
NI_NUMERICHOST
NI_NAMEREQD
NI_NUMERICSERV
NI_DGRAM

Saat bendera NI_NAMEREQD diatur, nama host yang tidak dapat diselesaikan oleh DNS menghasilkan kesalahan.

Mengatur bendera NI_NOFQDN menghasilkan host lokal yang hanya memiliki Relative Distinguished Name (RDN) yang dikembalikan dalam parameter pNodeBuffer .

Mengatur bendera NI_NUMERICHOST mengembalikan bentuk numerik nama host alih-alih namanya. Bentuk numerik nama host juga dikembalikan jika nama host tidak dapat diselesaikan oleh DNS.

Mengatur bendera NI_NUMERICSERV mengembalikan nomor port layanan alih-alih namanya. Selain itu, jika nama host tidak ditemukan untuk alamat IP (127.0.0.2, misalnya), nama host dikembalikan sebagai alamat IP.

Pada Windows Vista dan yang lebih baru, jika NI_NUMERICSERV tidak ditentukan dalam parameter bendera , dan nomor port yang terkandung dalam struktur sockaddr yang diarahkan oleh parameter sa tidak diselesaikan ke layanan terkenal, fungsi GetNameInfoW mengembalikan bentuk numerik alamat layanan (nomor port) sebagai string numerik. Ketika NI_NUMERICSERV ditentukan, nomor port dikembalikan sebagai string numerik. Perilaku ini ditentukan dalam bagian 6.2 RFC 3493. Untuk informasi selengkapnya, lihat www.ietf.org/rfc/rfc3493.txt

Pada Windows Server 2003 dan yang lebih lama, jika NI_NUMERICSERV tidak ditentukan dalam parameter bendera dan nomor port yang terkandung dalam struktur sockaddr yang ditunjukkan oleh parameter sa tidak diselesaikan ke layanan terkenal, fungsi GetNameInfoW gagal. Ketika NI_NUMERICSERV ditentukan, nomor port dikembalikan sebagai string numerik.

Mengatur bendera NI_DGRAM menunjukkan bahwa layanan tersebut adalah layanan datagram. Bendera ini diperlukan untuk beberapa layanan yang menyediakan nomor port yang berbeda untuk layanan UDP dan TCP.

Catatan Kemampuan untuk melakukan pencarian DNS terbalik menggunakan fungsi GetNameInfoW nyaman, tetapi pencarian tersebut dianggap secara inheren tidak dapat diandalkan, dan harus digunakan hanya sebagai petunjuk.

CatatanGetNameInfoW tidak dapat digunakan untuk mengatasi nama alias.

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.

Contoh Kode

Contoh berikut menunjukkan penggunaan fungsi GetNameInfoW .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int __cdecl main(int argc, char **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwRetval;

    struct sockaddr_in saGNI;
    WCHAR hostname[NI_MAXHOST];
    WCHAR servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %s IPv4 address\n", argv[0]);
        wprintf(L"  to return hostname\n");
        wprintf(L"       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }
    //-----------------------------------------
    // Set up sockaddr_in structure which is passed
    // to the getnameinfo function
    saGNI.sin_family = AF_INET;
    saGNI.sin_addr.s_addr = inet_addr(argv[1]);
    saGNI.sin_port = htons(port);

    //-----------------------------------------
    // Call GetNameInfoW
    dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
        return 0;
    }
}

Catatan

Header ws2tcpip.h mendefinisikan GetNameInfo sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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	ws2tcpip.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll