PFN_WSK_SOCKET_CONNECT fungsi panggilan balik (wsk.h)

Fungsi WskSocketConnect membuat soket berorientasi koneksi baru, mengikatnya ke alamat transportasi lokal, menghubungkannya ke alamat transportasi jarak jauh tertentu, dan mengembalikan penunjuk ke objek soket terkait.

Sintaks

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *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 Fungsi WskCaptureProviderNPI .

[in] SocketType

Jenis soket yang sedang dibuat. Jenis soket berikut ini didukung:

SOCK_STREAM

Mendukung komunikasi aliran byte yang 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] LocalAddress

Penunjuk ke struktur yang menentukan alamat transportasi lokal yang akan mengikat soket. Aplikasi WSK harus menentukan penunjuk ke jenis struktur SOCKADDR tertentu yang sesuai dengan keluarga alamat untuk soket yang sedang dibuat.

[in] RemoteAddress

Penunjuk ke struktur yang menentukan alamat transportasi jarak jauh untuk menyambungkan soket. Aplikasi WSK harus menentukan penunjuk ke jenis struktur SOCKADDR tertentu yang sesuai dengan keluarga alamat untuk soket yang sedang dibuat.

Flags

Parameter ini dicadangkan untuk penggunaan sistem. Aplikasi WSK harus mengatur parameter ini ke nol.

[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.

[in, optional] Dispatch

Penunjuk ke konstanta WSK_CLIENT_CONNECTION_DISPATCH struktur. Struktur ini adalah tabel pengiriman yang berisi pointer ke fungsi panggilan balik peristiwa untuk soket baru. Jika aplikasi WSK tidak akan mengaktifkan semua fungsi panggilan balik peristiwa untuk soket baru, aplikasi tersebut harus mengatur penunjuk dalam tabel pengiriman ke NULL untuk fungsi panggilan balik peristiwa yang tidak diaktifkannya. Jika aplikasi WSK tidak akan mengaktifkan fungsi panggilan balik peristiwa apa pun pada soket baru, aplikasi tersebut harus mengatur penunjuk ini ke 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 penunjuk ke salinan cache deskriptor keamanan yang diperoleh dengan memanggil fungsi WskControlClient dengan kode kontrol WSK_CACHE_SD . Untuk menentukan deskriptor 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 pemanggil yang digunakan subsistem WSK untuk menyelesaikan pembuatan soket baru secara asinkron. Untuk informasi selengkapnya tentang menggunakan IRP dengan fungsi WSK, lihat Menggunakan RUNP dengan Fungsi Kernel Winsock.

Nilai kembali

WskSocketConnect 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 SocketType dan Protocol yang valid.

Subsistem WSK menentukan keluarga alamat untuk soket baru dari keluarga alamat yang ditentukan dalam struktur SOCKADDR yang diarahkan oleh parameter LocalAddress .

Jika aplikasi WSK perlu mengatur opsi soket atau mengeluarkan operasi kontrol I/O pada soket sebelum mengikat atau menghubungkan soket, aplikasi WSK harus memanggil fungsi WskSocket, WskBind, dan WskConnect alih-alih memanggil fungsi WskSocketConnect .

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

Lihat juga

SOCKADDR

WSK_CLIENT

WSK_CLIENT_CONNECTION_DISPATCH

WSK_PROVIDER_DISPATCH

WSK_PROVIDER_NPI

WSK_SOCKET

WskCaptureProviderNPI

WskCloseSocket

WskControlClient

WskSocket