Fungsi InetPtonW (ws2tcpip.h)

Artikel
08/28/2023

Fungsi InetPton mengonversi alamat jaringan Internet IPv4 atau IPv6 dalam bentuk presentasi teks standarnya ke dalam bentuk biner numeriknya. Versi ANSI dari fungsi ini inet_pton.

Sintaks

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

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 mana pun dapat digunakan.

Nilai yang saat ini didukung adalah AF_INET dan AF_INET6.

Nilai	Makna
AF_INET 2	Keluarga alamat Protokol Internet versi 4 (IPv4). Ketika parameter ini ditentukan, parameter pszAddrString harus menunjuk ke representasi teks alamat IPv4 dan parameter pAddrBuf mengembalikan penunjuk ke struktur IN_ADDR yang mewakili alamat IPv4.
AF_INET6 23	Keluarga alamat Protokol Internet versi 6 (IPv6). Ketika parameter ini ditentukan, parameter pszAddrString harus menunjuk ke representasi teks alamat IPv6 dan parameter pAddrBuf mengembalikan penunjuk ke struktur IN6_ADDR yang mewakili alamat IPv6.

[in] pszAddrString

Penunjuk ke string yang dihentikan NULL yang berisi representasi teks alamat IP untuk dikonversi ke formulir biner numerik.

Ketika parameter FamilyAF_INET, parameter pszAddrString harus menunjuk ke representasi teks alamat IPv4 dalam notasi dotted-decimal standar.

Ketika parameter FamilyAF_INET6, parameter pszAddrString harus menunjuk ke representasi teks alamat IPv6 dalam notasi standar.

[out] pAddrBuf

Penunjuk ke buffer untuk menyimpan representasi biner numerik alamat IP. Alamat IP dikembalikan dalam urutan byte jaringan.

Ketika parameter FamilyAF_INET, buffer ini harus cukup besar untuk menahan struktur IN_ADDR .

Ketika parameter FamilyAF_INET6, buffer ini harus cukup besar untuk memegang struktur IN6_ADDR .

Nilai kembali

Jika tidak ada kesalahan yang terjadi, fungsi InetPton mengembalikan nilai 1 dan buffer yang ditunjukkan oleh parameter pAddrBuf berisi alamat IP numerik biner dalam urutan byte jaringan.

Fungsi InetPton mengembalikan nilai 0 jika parameter pAddrBuf menunjuk ke string yang bukan string desimal putus-putus IPv4 yang valid atau string alamat IPv6 yang valid. Jika tidak, nilai -1 dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil
WSAGetLastError untuk informasi kesalahan yang diperluas.

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

Kode kesalahan	Makna
WSAEAFNOSUPPORT	Keluarga alamat yang ditentukan dalam parameter Keluarga tidak didukung. Kesalahan ini dikembalikan jika parameter Family yang ditentukan tidak AF_INET atau AF_INET6.
WSAEFAULT	Parameter pszAddrString atau pAddrBuf adalah NULL atau bukan bagian dari ruang alamat pengguna.

Keterangan

Fungsi InetPton didukung pada Windows Vista dan yang lebih baru.

Fungsi InetPton menyediakan konversi protokol independen dari alamat jaringan Internet dalam bentuk presentasi teks standarnya ke dalam bentuk biner numeriknya. Fungsi InetPton mengambil representasi teks dari alamat Internet yang ditunjukkan oleh parameter pszAddrString dan mengembalikan pointer ke alamat IP biner numerik dalam parameter pAddrBuf . Meskipun fungsi inet_addr hanya berfungsi dengan string alamat IPv4, fungsi InetPton berfungsi dengan string alamat IPv4 atau IPv6.

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

Fungsi InetPton tidak mengharuskan DLL Soket Windows dimuat untuk melakukan konversi string teks yang mewakili alamat IP ke alamat IP biner numerik.

Jika parameter Family yang ditentukan AF_INET, parameter pszAddrString harus mengarahkan string teks alamat IPv4 dalam notasi dotted-decimal seperti dalam "192.168.16.0", contoh alamat IPv4 dalam notasi dotted-decimal.

Jika parameter Family yang ditentukan AF_INET6, parameter pszAddrString harus mengarahkan string teks alamat IPv6 dalam format standar Internet. Representasi string dasar terdiri dari 8 angka heksadesimal yang dipisahkan oleh titik dua. String angka nol berturut-turut dapat diganti dengan titik dua. Hanya ada satu titik dua dalam representasi string alamat IPv6. 32 bit terakhir dapat diwakili dalam notasi dotted-octet gaya IPv4 jika alamatnya adalah alamat yang kompatibel dengan IPv4.

Ketika UNICODE atau _UNICODE didefinisikan, InetPton didefinisikan ke InetPtonW, versi Unicode dari fungsi ini. Parameter pszAddrString didefinisikan ke jenis data PCWSTR .

Ketika UNICODE atau _UNICODE tidak ditentukan, InetPton didefinisikan ke InetPtonA, versi ANSI dari fungsi ini. Versi ANSI dari fungsi ini selalu didefinisikan sebagai inet_pton. Parameter pszAddrString didefinisikan ke jenis data PCSTR .

Struktur IN_ADDR didefinisikan dalam file header Inaddr.h .

Struktur IN6_ADDR didefinisikan dalam file header In6addr.h .

Pada Windows Vista dan yang lebih baru, fungsi RtlIpv4StringToAddress dan RtlIpv4StringToAddressEx dapat digunakan untuk mengonversi representasi teks alamat IPv4 dalam notasi dotted-decimal standar Internet ke alamat biner numerik yang direpresentasikan sebagai struktur IN_ADDR . Pada Windows Vista dan yang lebih baru, fungsi RtlIpv6StringToAddress dan RtlIpv6StringToAddressEx dapat digunakan untuk mengonversi representasi string alamat IPv6 ke alamat IPv6 biner numerik yang direpresentasikan sebagai struktur IN6_ADDR . Fungsi RtlIpv6StringToAddressEx lebih fleksibel karena juga mengonversi representasi string alamat IPv6 yang dapat menyertakan ID cakupan dan port dalam notasi standar ke bentuk biner numerik.

Windows 8.1 dan Windows Server 2012 R2: Fungsi InetPtonW 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