Fungsi WSAAddressToStringA (winsock2.h)

Artikel
03/08/2023

Fungsi WSAAddressToString mengonversi semua komponen struktur sockaddr menjadi representasi string alamat yang dapat dibaca manusia.

Ini dimaksudkan untuk digunakan terutama untuk tujuan tampilan. Jika penelepon mengharuskan terjemahan dilakukan oleh penyedia tertentu, penelepon harus menyediakan struktur WSAPROTOCOL_INFO yang sesuai dalam parameter lpProtocolInfo .

Sintaks

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parameter

[in] lpsaAddress

Penunjuk ke struktur sockaddr untuk diterjemahkan ke dalam string.

[in] dwAddressLength

Panjang, dalam byte, dari alamat dalam struktur sockaddr yang ditujukkan oleh parameter lpsaAddress . Parameter dwAddressLength dapat bervariasi dalam ukuran dengan protokol yang berbeda.

[in, optional] lpProtocolInfo

Penunjuk ke struktur WSAPROTOCOL_INFO untuk penyedia tertentu. Jika ini adalah parameter NULL, panggilan dirutekan ke penyedia protokol pertama yang mendukung keluarga alamat yang ditunjukkan dalam parameter lpsaAddress .

[in, out] lpszAddressString

Penunjuk ke buffer yang menerima string alamat yang dapat dibaca manusia.

[in, out] lpdwAddressStringLength

Pada input, parameter ini menentukan panjang buffer yang diacu oleh parameter lpszAddressString . Panjangnya diwakili dalam byte untuk string ANSI, dan dalam WCHAR untuk string Unicode. Pada output, parameter ini mengembalikan panjang string termasuk terminator NULL yang benar-benar disalin ke dalam buffer yang ditujukkan oleh parameter lpszAddressString . Jika buffer yang ditentukan tidak cukup besar, fungsi gagal dengan kesalahan tertentu dari WSAEFAULT dan parameter ini diperbarui dengan ukuran yang diperlukan.

Nilai kembali

Jika tidak ada kesalahan yang terjadi, WSAAddressToString mengembalikan nilai nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan nomor kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan	Makna
WSAEFAULT	Parameter lpcsAddress, lpProtocolInfo, dan lpszAddressString yang ditentukan menunjuk ke memori yang tidak semuanya berada di ruang alamat proses, atau buffer yang ditunjukkan oleh parameter lpszAddressString terlalu kecil. Berikan buffer yang lebih besar.
WSAEINVAL	Parameter yang tidak valid diteruskan. Kesalahan ini dikembalikan jika parameter lpsaAddress, dwAddressLength, atau lpdwAddressStringLength adalah NULL. Kesalahan ini juga dikembalikan jika alamat yang ditentukan bukan alamat soket yang valid, atau tidak ada penyedia transportasi yang mendukung keluarga alamat yang ditunjukkan.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia.
WSANOTINITIALISED	DLL Winsock 2 belum diinisialisasi. Aplikasi harus terlebih dahulu memanggil WSAStartup sebelum memanggil fungsi Windows Sockets apa pun.

Keterangan

Fungsi WSAAddressToString menyediakan terjemahan alamat-ke-string independen protokol. Fungsi WSAAddressToString mengambil struktur alamat soket yang ditunjukkan oleh parameter lpsaAddress dan mengembalikan penunjuk ke string yang dihentikan NULL yang mewakili alamat soket dalam parameter lpszAddressString . Meskipun fungsi inet_ntoa hanya berfungsi dengan alamat IPv4, fungsi WSAAddressToString berfungsi dengan alamat soket apa pun yang didukung oleh penyedia Winsock di komputer lokal termasuk alamat IPv6.

Jika parameter lpsaAddress menunjuk ke alamat soket IPv4 (keluarga alamat AF_INET), maka string alamat yang dikembalikan dalam buffer yang ditunjukkan oleh parameter lpszAddressString berada dalam notasi dotted-decimal seperti dalam "192.168.16.0", contoh alamat IPv4 dalam notasi dotted-decimal.

Jika parameter lpsaAddress menunjuk ke alamat soket IPv6 (keluarga alamat AF_INET6), maka string alamat yang dikembalikan dalam buffer yang ditujukan oleh parameter lpszAddressString 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.

Jika panjang buffer yang diarahkan oleh parameter lpszAddressString tidak cukup besar untuk menerima representasi string alamat soket, WSAAddressToString mengembalikan WSAEFAULT.

Dukungan untuk alamat IPv6 menggunakan fungsi WSAAddressToString ditambahkan pada Windows XP dengan Paket Layanan 1 (SP1) dan yang lebih baru. IPv6 juga harus diinstal pada komputer lokal untuk fungsi WSAAddressToString untuk mendukung alamat IPv6.

Windows Phone 8: Fungsi WSAAddressToStringW didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi WSAAddressToStringW didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Catatan

Header winsock2.h mendefinisikan WSAAddressToString sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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 XP, Windows 8.1 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winsock2.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll