Fungsi WSAQuerySocketSecurity (ws2tcpip.h)

Artikel
08/28/2023

Fungsi WSAQuerySocketSecurity meminta informasi tentang keamanan yang diterapkan ke koneksi pada soket.

Sintaks

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

Parameter

[in] Socket

Deskriptor yang mengidentifikasi soket tempat informasi keamanan sedang dikueri.

[in, optional] SecurityQueryTemplate

Penunjuk ke struktur SOCKET_SECURITY_QUERY_TEMPLATE yang menentukan jenis informasi kueri yang akan dikembalikan.

Struktur SOCKET_SECURITY_QUERY_TEMPLATE yang ditunjukkan oleh parameter ini mungkin berisi nol bagi semua anggota untuk meminta informasi keamanan default. Saat pengembalian berhasil, hanya anggota Bendera di SOCKET_SECURITY_QUERY_INFO yang akan diatur dalam parameter SecurityQueryInfo yang dikembalikan.

Parameter ini mungkin penunjuk NULL jika parameter Soket dibuat dengan protokol IPPROTO_TCP. Dalam hal ini, informasi yang dikembalikan sama seperti jika struktur SOCKET_SECURITY_QUERY_TEMPLATE dengan semua nilai diatur ke nol diteruskan. Parameter ini harus ditentukan untuk soket dengan protokol IPPROTO_TCP jika lebih dari informasi keamanan default diperlukan.

Jika struktur SOCKET_SECURITY_QUERY_TEMPLATE ditentukan dengan anggota PeerTokenAccessMask tidak ditentukan (diatur ke nol), maka fungsi WSAQuerySocketSecurity tidak akan mengembalikan anggota PeerApplicationAccessTokenHandle dan PeerMachineAccessTokenHandle dalam struktur SOCKET_SECURITY_QUERY_INFO .

Jika parameter Soket dibuat dengan protokol yang tidak sama dengan IPPROTO_TCP, parameter SecurityQueryTemplate harus ditentukan. Dalam kasus ini, anggota PeerAddress dari struktur SOCKET_SECURITY_QUERY_TEMPLATE harus menentukan keluarga alamat AF_INET atau AF_INET6 bersama dengan alamat IP serekan dan nomor port.

[in] SecurityQueryTemplateLen

Ukuran, dalam byte, dari parameter SecurityQueryTemplate .

Parameter ini mungkin nol jika parameter Soket dibuat dengan protokol IPPROTO_TCP. Jika tidak, parameter ini harus ukuran struktur SOCKET_SECURITY_QUERY_TEMPLATE .

[out, optional] SecurityQueryInfo

Penunjuk ke buffer yang akan menerima struktur SOCKET_SECURITY_QUERY_INFO yang berisi informasi yang dikueri. Nilai ini dapat diatur ke NULL untuk mengkueri ukuran buffer output.

[in, out] SecurityQueryInfoLen

Pada input, penunjuk ke ukuran, dalam byte, dari parameter SecurityQueryInfo . Jika buffer terlalu kecil untuk menerima informasi yang dikueri, panggilan akan mengembalikan SOCKET_ERROR, dan jumlah byte yang diperlukan untuk mengembalikan informasi yang dikueri akan diatur dalam nilai yang ditujukkan oleh parameter ini. Pada panggilan yang berhasil, jumlah byte yang disalin dikembalikan.

[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.
WSAECONNRESET	Untuk soket aliran, sirkuit virtual direset oleh sisi jarak jauh. Aplikasi harus menutup soket karena tidak lagi dapat digunakan. Untuk soket datagram UDP, kesalahan ini akan menunjukkan bahwa operasi pengiriman sebelumnya menghasilkan pesan "Port Unreachable" ICMP.
WSAEFAULT	Sistem mendeteksi alamat penunjuk yang tidak valid dalam mencoba menggunakan parameter. Kesalahan ini dikembalikan jika parameter SecurityQueryInfoLen adalah penunjuk NULL .
WSAEINVAL	Parameter yang tidak valid telah 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.
WSAEMSGSIZE	Buffer yang dilewati terlalu kecil. Kesalahan ini dikembalikan untuk parameter Soket ketika protokol tidak IPPROTO_TCP jika parameter SecurityQueryInfo adalah pointer NULL atau parameter SecurityQueryTemplateLen kurang dari ukuran struktur SOCKET_SECURITY_QUERY_TEMPLATE .
WSAENOTSOCK	Deskriptor yang diteruskan dalam parameter Soket bukan soket yang valid.

Keterangan

Fungsi WSAQuerySocketSecurity menyediakan metode untuk mengkueri pengaturan keamanan saat ini pada soket. Setelah koneksi dibuat, fungsi WSAQuerySocketSecurity memungkinkan aplikasi untuk mengkueri properti keamanan koneksi, yang dapat menyertakan informasi tentang token akses serekan.

Untuk soket berorientasi koneksi, lebih disukai untuk memanggil fungsi WSAQuerySocketSecurity segera setelah koneksi dibuat. Untuk soket tanpa koneksi, lebih disukai untuk memanggil fungsi WSAQuerySocketSecurity segera setelah data dikirim ke alamat serekan baru atau diterima dari alamat serekan baru. Fungsi WSAQuerySocketSecurity dapat dipanggil beberapa kali pada satu soket.

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

Fungsi WSAQuerySocketSecurity dapat dipanggil pada parameter Soket yang dibuat dengan keluarga alamat AF_INET atau AF_INET6.

Jika parameter Soket dibuat dengan protokol IPPROTO_TCP, parameter SecurityQueryTemplate mungkin NULL dan parameter SecurityQueryTemplateLen mungkin nol. Jika tidak, parameter SecurityQueryTemplate harus menunjuk ke struktur SOCKET_SECURITY_QUERY_TEMPLATE .

Untuk aplikasi klien yang menggunakan soket berorientasi koneksi (soket yang dibuat dengan protokol IPPROTO_TCP), fungsi WSAQuerySocketSecurity harus dipanggil setelah fungsi connect, ConnectEx, atau WSAConnect kembali. Untuk aplikasi server yang menggunakan soket berorientasi koneksi (protokol IPPROTO_TCP), fungsi WSAQuerySocketSecurity harus dipanggil setelah fungsi accept, AcceptEx, atau WSAAccept kembali.

Untuk soket tanpa koneksi (soket yang dibuat dengan protokol IPPROTO_UDP), aplikasi harus memanggil fungsi WSAQuerySocketSecurity segera setelah WSASendTo atau WSARecvFrom kembali untuk alamat serekan baru.

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

Persyaratan	Nilai
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