Fungsi WSASetSocketPeerTargetName (ws2tcpip.h)

Artikel
08/28/2023

Fungsi WSASetSocketPeerTargetName digunakan untuk menentukan nama target serekan (SPN) yang sesuai dengan alamat IP serekan. Nama target ini dimaksudkan untuk ditentukan oleh aplikasi klien untuk mengidentifikasi serekan yang harus diautentikasi dengan aman.

Sintaks

INT WSAAPI WSASetSocketPeerTargetName(
  [in]           SOCKET                             Socket,
  [in]           const SOCKET_PEER_TARGET_NAME      *PeerTargetName,
  [in]           ULONG                              PeerTargetNameLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Parameter

[in] Socket

Deskriptor yang mengidentifikasi soket tempat nama target serekan ditetapkan.

[in] PeerTargetName

Penunjuk ke struktur SOCKET_PEER_TARGET_NAME yang menentukan nama target serekan.

[in] PeerTargetNameLen

Ukuran, dalam byte, dari parameter PeerTargetName .

[in, optional] Overlapped

Penunjuk ke struktur WSAOVERLAPPED . Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

[in, optional] CompletionRoutine

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi telah selesai. Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Beberapa kemungkinan kode kesalahan tercantum di bawah ini.

Kode kesalahan	Makna
WSAEAFNOSUPPORT	Keluarga alamat yang ditentukan tidak didukung.
WSAEFAULT	Sistem mendeteksi penunjuk alamat yang tidak valid dalam mencoba menggunakan argumen pointer panggilan. Kesalahan ini dikembalikan jika parameter PeerTargetName adalah penunjuk NULL .
WSAEINVAL	Parameter yang tidak valid diteruskan. Kesalahan ini dikembalikan jika soket yang diteruskan dalam parameter Soket tidak dibuat dengan keluarga alamat AF_INET atau AF_INET6 dan jenis soket SOCK_DGRAM atau SOCK_STREAM. Kesalahan ini juga dikembalikan untuk soket tanpa koneksi jika alamat IP dan port nol di anggota PeerAddress dari struktur SOCKET_PEER_TARGET_NAME yang ditunjukkan oleh parameter PeerTargetName .
WSAEISCONN	Soket tersambung. Fungsi ini tidak diizinkan dengan soket yang terhubung, baik soket berorientasi pada koneksi atau tanpa koneksi.
WSAEMSGSIZE	Buffer yang dilewati terlalu kecil.
WSAENOTSOCK	Deskriptor yang diteruskan dalam parameter Soket bukan soket yang valid.

Keterangan

Fungsi WSASetSocketPeerTargetName menyediakan metode untuk menentukan nama target yang sesuai dengan prinsip keamanan serekan. Fungsi ini dimaksudkan untuk digunakan oleh aplikasi klien untuk mengidentifikasi serekan yang harus diautentikasi. Aplikasi klien harus menentukan nama target serekan untuk mencegah serangan man-in-the-middle tepercaya. Untuk soket tanpa koneksi, aplikasi dapat memanggil fungsi WSASetSocketPeerTargetName beberapa kali untuk menentukan nama target yang berbeda untuk alamat IP peer yang berbeda.

Fungsi ini menyederhanakan harus memanggil fungsi WSAIoctl dengan parameter dwIoControlCode yang diatur ke SIO_SET_PEER_TARGET_NAME.

Untuk soket berorientasi koneksi, fungsi WSASetSocketPeerTargetName harus dipanggil sebelum WSAConnect. Untuk soket tanpa koneksi, fungsi ini harus dipanggil sebelum WSAConnect atau sebelum panggilan WSASendTo pertama diarahkan ke alamat serekan.

Kesalahan akan dikembalikan jika kondisi berikut tidak terpenuhi.

Keluarga alamat parameter Soket harus AF_INET atau AF_INET6.
Jenis soket harus SOCK_STREAM atau SOCK_DGRAM.

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	ws2tcpip.h
Pustaka	Fwpuclnt.lib
DLL	Fwpuclnt.dll