PFN_WSK_SOCKET fungsi panggilan balik (wsk.h)

Artikel
08/08/2023

Fungsi WskSocket membuat soket baru dan mengembalikan penunjuk ke objek soket terkait.

Sintaks

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Parameter

[in] Client

Penunjuk ke struktur WSK_CLIENT yang dikembalikan melalui parameter WskProviderNpi dari Fungsi WskCaptureProviderNPI .

[in] AddressFamily

Keluarga alamat untuk soket yang sedang dibuat. Untuk informasi selengkapnya tentang keluarga alamat yang didukung, lihat Keluarga Alamat WSK.

[in] SocketType

Jenis soket yang sedang dibuat. Jenis soket berikut didukung:

SOCK_STREAM

Mendukung komunikasi aliran byte berorientasi koneksi yang andal.

SOCK_DGRAM

Mendukung komunikasi datagram tanpa koneksi yang tidak dapat diandalkan.

SOCK_RAW

Mendukung akses mentah ke protokol transportasi.

Untuk informasi selengkapnya tentang jenis soket yang didukung untuk setiap keluarga alamat yang didukung, lihat
Keluarga Alamat WSK.

[in] Protocol

Protokol transportasi untuk soket yang sedang dibuat. Untuk informasi selengkapnya tentang protokol yang didukung untuk setiap keluarga alamat yang didukung, lihat Keluarga Alamat WSK.

[in] Flags

Bendera yang menentukan kategori soket WSK untuk soket yang sedang dibuat. Parameter ini bisa menjadi salah satu bendera berikut:

WSK_FLAG_BASIC_SOCKET

Soket dasar akan dibuat yang hanya dapat digunakan untuk mendapatkan dan mengatur opsi soket tumpukan transportasi atau untuk melakukan operasi kontrol I/O soket.

WSK_FLAG_LISTEN_SOCKET

Soket mendengarkan akan dibuat yang dapat digunakan untuk mendengarkan koneksi masuk dari alamat transportasi jarak jauh.

WSK_FLAG_DATAGRAM_SOCKET

Soket datagram akan dibuat yang dapat digunakan untuk mengirim dan menerima datagram.

WSK_FLAG_CONNECTION_SOCKET

Soket berorientasi koneksi akan dibuat yang dapat digunakan untuk mengirim dan menerima data jaringan melalui koneksi.

WSK_FLAG_STREAM_SOCKET

Soket aliran akan dibuat yang dapat digunakan untuk mendengarkan koneksi masuk dari alamat transportasi jarak jauh, atau mengirim dan menerima data jaringan melalui koneksi.

Jika aplikasi WSK tidak menentukan bendera sebelumnya, WskSocket membuat soket dasar.

[in, optional] SocketContext

Penunjuk ke konteks yang disediakan penelepon untuk soket yang sedang dibuat. Subsistem WSK meneruskan penunjuk ini ke fungsi panggilan balik peristiwa soket. Informasi konteks buram ke subsistem WSK dan harus disimpan dalam memori non-halaman. Jika aplikasi WSK tidak akan mengaktifkan fungsi panggilan balik peristiwa apa pun pada soket baru, aplikasi tersebut harus mengatur penunjuk ini ke NULL. Untuk soket dasar, pointer ini harus selalu NULL.

[in, optional] Dispatch

Penunjuk ke struktur pengiriman klien yang konstan. Struktur ini adalah tabel pengiriman yang berisi pointer ke fungsi panggilan balik peristiwa untuk soket baru. Bergantung pada kategori soket WSK dari soket (seperti yang ditentukan oleh parameter Bendera ), parameter ini adalah penunjuk ke salah satu struktur berikut.

Bendera	Mengirimkan struktur tabel
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

Jika aplikasi WSK tidak akan mengaktifkan semua fungsi panggilan balik peristiwa untuk soket baru, aplikasi tersebut harus mengatur pointer dalam tabel pengiriman ke NULL untuk fungsi panggilan balik peristiwa yang tidak diaktifkan. Jika aplikasi WSK tidak akan mengaktifkan fungsi panggilan balik peristiwa apa pun pada soket baru, aplikasi tersebut harus mengatur penunjuk Pengiriman ke NULL. Untuk soket dasar, pointer ini harus selalu NULL.

[in, optional] OwningProcess

Penunjuk ke proses tempat subsistem WSK akan mengambil konteks keamanan untuk digunakan saat mengikat soket. Subsistem WSK menggunakan konteks keamanan untuk menentukan apakah alamat transportasi lokal dapat dibagikan jika alamat tersebut sudah digunakan. Untuk menentukan proses saat ini, aplikasi WSK mengatur penunjuk ini ke NULL.

[in, optional] OwningThread

Penunjuk ke utas tertentu tempat subsistem WSK akan mengambil konteks keamanan untuk digunakan saat mengikat soket. Subsistem WSK menggunakan konteks keamanan untuk menentukan apakah alamat transportasi lokal dapat dibagikan jika alamat tersebut sudah digunakan. Jika aplikasi WSK tidak perlu menentukan utas tertentu, aplikasi ini mengatur penunjuk ini ke NULL.

[in, optional] SecurityDescriptor

Penunjuk ke struktur SECURITY_DESCRIPTOR yang menentukan deskriptor keamanan untuk diterapkan ke soket yang sedang dibuat. Deskriptor keamanan mengontrol berbagi alamat transportasi lokal tempat soket terikat. Jika aplikasi WSK menentukan penunjuk non-NULL , aplikasi tersebut harus menentukan pointer ke salinan cache deskriptor keamanan yang diperoleh dengan memanggil fungsi WskControlClient dengan kode kontrol WSK_CACHE_SD . Untuk menentukan pendeskripsi keamanan default yang tidak mengizinkan berbagi alamat transportasi lokal, aplikasi WSK mengatur SecurityDescriptor ke NULL.

Untuk informasi selengkapnya tentang struktur SECURITY_DESCRIPTOR, lihat halaman referensi untuk SECURITY_DESCRIPTOR dalam dokumentasi Microsoft Windows SDK.

[in, out] Irp

Penunjuk ke IRP yang dialokasikan penelepon yang digunakan subsistem WSK untuk menyelesaikan pembuatan soket baru secara asinkron. Untuk informasi selengkapnya tentang menggunakan runtime integrasi dengan fungsi WSK, lihat Menggunakan IRP dengan Fungsi Kernel Winsock.

Nilai kembali

WskSocket mengembalikan salah satu kode NTSTATUS berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Soket baru berhasil dibuat. IRP akan diselesaikan dengan status keberhasilan.
STATUS_PENDING	Subsistem WSK tidak dapat segera membuat soket. Subsistem WSK akan menyelesaikan IRP setelah membuat soket baru. Status pembuatan soket akan dikembalikan di bidang IoStatus.Status dari IRP.
Kode status lainnya	Terjadi kesalahan. IRP akan diselesaikan dengan status kegagalan.

Keterangan

Jika IRP selesai dengan status keberhasilan, bidang IoStatus.Information dari IRP berisi penunjuk ke struktur objek soket ( WSK_SOCKET) untuk soket baru.

Aplikasi WSK dapat memperoleh daftar protokol transportasi yang tersedia dengan memanggil fungsi WskControlClient dengan kode kontrol WSK_TRANSPORT_LIST_QUERY . WskControlClient mengembalikan daftar struktur WSK_TRANSPORT yang berisi semua kombinasi parameter AddressFamily, SocketType, dan Protocol yang valid.

Ketika aplikasi WSK berhasil membuat soket baru, semua fungsi panggilan balik peristiwa pada soket baru dinonaktifkan secara default. Untuk informasi selengkapnya tentang mengaktifkan salah satu fungsi panggilan balik peristiwa soket baru, lihat Mengaktifkan dan Menonaktifkan Fungsi Panggilan Balik Peristiwa.

Jika aplikasi WSK menentukan penunjuk non-NULL untuk parameter SecurityDescriptor , aplikasi tersebut tidak boleh merilis deskriptor keamanan yang di-cache hingga setelah IRP selesai.

Subsistem WSK mengalokasikan memori untuk struktur objek soket (WSK_SOCKET) untuk soket baru atas nama aplikasi WSK. Subsistem WSK membatalkan alokasi memori ini ketika soket ditutup.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows Vista dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Universal
Header	wsk.h (termasuk Wsk.h)
IRQL	<= DISPATCH_LEVEL