fungsi getnameinfo (ws2tcpip.h)

Artikel
08/28/2023

Fungsi getnameinfo menyediakan resolusi nama independen protokol dari alamat ke nama host ANSI dan dari nomor port ke nama layanan ANSI.

Sintaks

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

Parameter

[in] pSockaddr

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

[in] SockaddrLength

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

[out] pNodeBuffer

Penunjuk ke string ANSI yang digunakan untuk menyimpan nama host. Setelah berhasil, nama host dikembalikan sebagai Nama Domain yang Sepenuhnya Memenuhi Syarat (FQDN) secara default. Jika parameter hostadalah NULL, ini menunjukkan pemanggil tidak ingin menerima string nama host.

[in] NodeBufferSize

Panjangnya, dalam byte, dari buffer yang diacu oleh parameter host . Pemanggil harus menyediakan buffer yang cukup besar untuk menahan nama host, termasuk karakter NULL yang mengakhiri.

[out] pServiceBuffer

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

[in] ServiceBufferSize

Panjangnya, dalam byte, dari buffer yang diacu oleh parameter serv . Pemanggil harus menyediakan buffer yang cukup besar untuk menahan nama layanan, termasuk karakter NULL yang mengakhiri.

[in] Flags

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

Nilai kembali

Pada keberhasilan, getnameinfo 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 getnameinfo juga memetakan ke serangkaian kesalahan yang diuraikan oleh rekomendasi Internet Engineering Task Force (IETF). Tabel berikut mencantumkan kode kesalahan ini dan setara WSA-nya. Disarankan agar kode kesalahan WSA digunakan, karena 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 getnameinfo . Kesalahan ini dikembalikan jika nama host diminta tetapi parameter hostlen adalah nol atau jika nama layanan diminta, tetapi parameter servlen 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 ditujukan oleh parameter sa 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 sa atau tidak ada nama layanan yang cocok dengan nomor port yang ditemukan. NI_NAMEREQD diatur dan nama host tidak dapat ditemukan, atau parameter host dan servadalah NULL.

Gunakan fungsi gai_strerror untuk mencetak pesan kesalahan berdasarkan kode EAI yang dikembalikan oleh fungsi getnameinfo . 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 sa adalah NULL atau parameter salen kurang dari panjang yang diperlukan untuk ukuran struktur sockaddr_in untuk IPv4 atau struktur sockaddr_in6 untuk IPv6.

Keterangan

Fungsi getnameinfo adalah versi ANSI dari fungsi yang menyediakan resolusi nama independen protokol. Fungsi getnameinfo digunakan untuk menerjemahkan konten struktur alamat soket ke nama simpul 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 getnameinfo juga dapat digunakan untuk mengonversi alamat IP atau nomor port dalam struktur sockaddr ke string ANSI. Fungsi ini juga dapat digunakan untuk menentukan alamat IP untuk nama host.

Nama lain yang dapat digunakan untuk fungsi getnameinfo adalah GetNameInfoA. Makro dalam file header Ws2tcpip.h menentukan GetNameInfoA ke getnameinfo.

Versi Unicode dari fungsi ini tersedia di Windows XP dengan Paket Layanan 2 (SP2) dan yang lebih baru adalah GetNameInfoW.

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

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

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Parameter bendera dapat digunakan untuk menyesuaikan pemrosesan fungsi getnameinfo . 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 host .

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 ditunjukkan oleh parameter sa tidak diselesaikan ke layanan terkenal, fungsi getnameinfo 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 dari RFC 3493. Untuk informasi selengkapnya, lihat www.ietf.org/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 menyelesaikan ke layanan terkenal, fungsi getnameinfo 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 REVERSE DNS menggunakan fungsi getnameinfo nyaman, tetapi pencarian tersebut dianggap secara inheren tidak dapat diandalkan, dan harus digunakan hanya sebagai petunjuk.

Catatan Fungsi getnameinfo tidak dapat digunakan untuk mengatasi nama alias.

Contoh Kode

Contoh kode berikut menunjukkan cara menggunakan fungsi getnameinfo .

#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 = {0};
    int iResult = 0;

    DWORD dwRetval;

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

    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IPv4 address\n", argv[0]);
        printf("  to return hostname\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;
    }
    //-----------------------------------------
    // 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 getnameinfo
    dwRetval = getnameinfo((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        printf("getnameinfo returned hostname = %s\n", hostname);
        return 0;
    }
}

Dukungan untuk getnameinfo pada versi Windows yang lebih lama

Fungsi getnameinfo ditambahkan ke Ws2_32.dll pada Windows XP dan yang lebih baru. Jika Anda ingin menjalankan aplikasi menggunakan fungsi ini pada versi Windows yang lebih lama (Windows 2000, Windows NT, dan Windows Me/98/95), maka Anda perlu menyertakan file Ws2tcpip.h dan juga menyertakan file Wspiapi.h . Ketika file yang disertakan Wspiapi.h ditambahkan, fungsi getnameinfo didefinisikan ke fungsi sebaris WspiapiGetNameInfo dalam file Wspiapi.h . Pada runtime, fungsi WspiapiGetNameInfo diimplementasikan sedemikian sehingga jika Ws2_32.dll atau Wship6.dll (file yang berisi getnameinfo dalam Pratinjau Teknologi IPv6 untuk Windows 2000) tidak menyertakan getnameinfo, maka versi getnameinfo diimplementasikan sebaris berdasarkan kode dalam file header Wspiapi.h . Kode sebaris ini akan digunakan pada platform Windows lama yang tidak secara asli mendukung fungsi getnameinfo .

Protokol IPv6 didukung pada Windows 2000 ketika Pratinjau Teknologi IPv6 untuk Windows 2000 diinstal. Jika tidak , dukungan getnameinfo pada versi Windows yang lebih lama dari Windows XP terbatas untuk menangani resolusi nama IPv4.

Fungsi GetNameInfoW adalah versi Unicode dari getnameinfo. Fungsi GetNameInfoW ditambahkan ke Ws2_32.dll di Windows XP dengan SP2. Fungsi GetNameInfoW tidak dapat digunakan pada versi Windows yang lebih lama dari Windows XP dengan SP2.

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