Fungsi InetNtopW (ws2tcpip.h)

Artikel
03/15/2023

Fungsi InetNtop mengonversi alamat jaringan Internet IPv4 atau IPv6 menjadi string dalam format standar Internet. Versi ANSI dari fungsi ini inet_ntop.

Sintaks

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

Parameter

[in] Family

Keluarga alamat.

Nilai yang mungkin untuk keluarga alamat ditentukan dalam file header Ws2def.h . Perhatikan bahwa file header Ws2def.h secara otomatis disertakan dalam Winsock2.h, dan tidak boleh digunakan secara langsung. Perhatikan bahwa nilai untuk keluarga alamat AF_ dan konstanta keluarga protokol PF_ identik (misalnya, AF_INET dan PF_INET), sehingga konstanta dapat digunakan.

Nilai yang saat ini didukung AF_INET dan AF_INET6.

Nilai	Makna
AF_INET 2	Keluarga alamat Protokol Internet versi 4 (IPv4). Ketika parameter ini ditentukan, fungsi ini mengembalikan string alamat IPv4.
AF_INET6 23	Keluarga alamat Protokol Internet versi 6 (IPv6). Ketika parameter ini ditentukan, fungsi ini mengembalikan string alamat IPv6.

[in] pAddr

Penunjuk ke alamat IP dalam byte jaringan untuk dikonversi ke string.

Ketika parameter FamilyAF_INET, parameter pAddr harus menunjuk ke struktur IN_ADDR dengan alamat IPv4 untuk dikonversi.

Ketika parameter FamilyAF_INET6, parameter pAddr harus menunjuk ke struktur IN6_ADDR dengan alamat IPv6 untuk dikonversi.

[out] pStringBuf

Penunjuk ke buffer untuk menyimpan representasi string alamat IP yang dihentikan NULL.

Untuk alamat IPv4, buffer ini harus cukup besar untuk menampung setidaknya 16 karakter.

Untuk alamat IPv6, buffer ini harus cukup besar untuk menampung setidaknya 46 karakter.

[in] StringBufSize

Pada input, panjang, dalam karakter, dari buffer yang ditujukkan oleh parameter pStringBuf .

Nilai kembali

Jika tidak ada kesalahan yang terjadi, fungsi InetNtop mengembalikan penunjuk ke buffer yang berisi representasi string alamat IP dalam format standar.

Jika tidak, nilai NULL dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil
WSAGetLastError untuk informasi kesalahan yang diperluas.

Jika fungsi gagal, kode kesalahan yang diperluas yang dikembalikan oleh WSAGetLastError dapat menjadi salah satu nilai berikut.

Kode kesalahan	Makna
WSAEAFNOSUPPORT	Keluarga alamat yang ditentukan dalam parameter Keluarga tidak didukung. Kesalahan ini dikembalikan jika parameter Keluarga yang ditentukan tidak AF_INET atau AF_INET6.
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika penunjuk NULL diteruskan di pStringBuf atau parameter StringBufSize adalah nol. Kesalahan ini juga dikembalikan jika panjang buffer yang ditunjukkan oleh parameter pStringBuf tidak cukup besar untuk menerima representasi string alamat IP.

Keterangan

Fungsi InetNtop didukung pada Windows Vista dan yang lebih baru.

Fungsi InetNtop menyediakan terjemahan alamat-ke-string yang independen protokol. Fungsi InetNtop mengambil struktur alamat Internet yang ditentukan oleh parameter pAddr dan mengembalikan string yang dihentikan NULL yang mewakili alamat IP. Meskipun fungsi inet_ntoa hanya berfungsi dengan alamat IPv4, fungsi InetNtop berfungsi dengan alamat IPv4 atau IPv6.

Versi ANSI dari fungsi ini inet_ntop seperti yang didefinisikan dalam RFC 2553. Untuk informasi selengkapnya, lihat RFC 2553 yang tersedia di situs web IETF.

Fungsi InetNtop tidak mengharuskan DLL Soket Windows dimuat untuk melakukan alamat IP ke konversi string.

Jika parameter Family yang ditentukan AF_INET, parameter pAddr harus menunjuk ke struktur IN_ADDR dengan alamat IPv4 untuk dikonversi. String alamat yang dikembalikan dalam buffer yang ditunjukkan oleh parameter pStringBuf berada dalam notasi dotted-decimal seperti dalam "192.168.16.0", contoh alamat IPv4 dalam notasi titik-desimal.

Jika parameter Family yang ditentukan AF_INET6, parameter pAddr harus menunjuk ke struktur IN6_ADDR dengan alamat IPv6 untuk dikonversi. String alamat yang dikembalikan dalam buffer yang ditujukkan oleh parameter pStringBuf dalam format standar Internet. Representasi string dasar terdiri dari 8 angka heksadesimal yang dipisahkan oleh titik dua. String angka nol berturut-turut diganti dengan titik dua. Hanya ada satu titik dua dalam representasi string alamat IPv6. 32 bit terakhir diwakili dalam notasi titik-oktet gaya IPv4 jika alamatnya adalah alamat yang kompatibel dengan IPv4.

Jika panjang buffer yang ditunjukkan oleh parameter pStringBuf tidak cukup besar untuk menerima representasi string alamat IP, InetNtop mengembalikan ERROR_INVALID_PARAMETER.

Ketika UNICODE atau _UNICODE ditentukan, InetNtop didefinisikan ke InetNtopW, versi Unicode dari fungsi ini. Parameter pStringBuf didefinisikan ke jenis data PSTR .

Ketika UNICODE atau _UNICODE tidak ditentukan, InetNtop didefinisikan ke InetNtopA, versi ANSI dari fungsi ini. Versi ANSI dari fungsi ini selalu didefinisikan sebagai inet_ntop. Parameter pStringBuf didefinisikan ke jenis data PWSTR .

Struktur IN_ADDR ditentukan dalam file header Inaddr.h .

Struktur IN6_ADDR ditentukan dalam file header In6addr.h .

Pada Windows Vista dan yang lebih baru, fungsi RtlIpv4AddressToString dan RtlIpv4AddressToStringEx dapat digunakan untuk mengonversi alamat IPv4 yang diwakili sebagai struktur IN_ADDR ke representasi string alamat IPv4 dalam notasi dotted-decimal standar Internet. Pada Windows Vista dan yang lebih baru, fungsi RtlIpv6AddressToString dan RtlIpv6AddressToStringEx dapat digunakan untuk mengonversi alamat IPv6 yang direpresentasikan sebagai struktur IN6_ADDR ke representasi string alamat IPv6. Fungsi RtlIpv6AddressToStringEx lebih fleksibel karena juga mengonversi alamat IPv6, ID cakupan, dan port ke string IPv6 dalam format standar.

Windows 8.1 dan Windows Server 2012 R2: Fungsi InetNtopW 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 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	ws2tcpip.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll