Fungsi WPUCreateSocketHandle (ws2spi.h)

Artikel
08/28/2023

Fungsi WPUCreateSocketHandle membuat handel soket baru.

Sintaks

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

Parameter

[in] dwCatalogEntryId

Deskriptor mengidentifikasi penyedia layanan panggilan.

[in] dwContext

Nilai konteks untuk dikaitkan dengan handel soket baru.

[out] lpErrno

Arahkan ke kode kesalahan.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, WPUCreateSocketHandle mengembalikan handel soket baru. Jika tidak, kode mengembalikan INVALID_SOCKET, dan kode kesalahan tertentu tersedia di lpErrno.

Kode kesalahan	Makna
WSAENOBUFS	Tidak tersedia cukup buffer untuk membuat handel soket baru.

Keterangan

Fungsi WPUCreateSocketHandle membuat handel soket baru untuk penyedia yang ditentukan. Handel yang dibuat oleh WPUCreateSocketHandle tidak dapat dibedakan dari handel sistem file sejati. Ini signifikan dalam dua hal. Pertama, arsitektur Windows Socket 2 mengurus pengalihan fungsi sistem file ReadFile dan WriteFile ke fungsi LPWSPRecv dan LPWSPSend penyedia layanan ini. Kedua, dalam sistem operasi yang mendukung port penyelesaian, arsitektur Windows Sockets 2 mendukung pengaitan port penyelesaian dengan handel soket dan menggunakannya untuk melaporkan penyelesaian I/O yang tumpang tindih.

**Catatan** Mekanisme untuk mengalihkan ReadFile dan WriteFile selalu melibatkan transisi pengguna-ke-kernel untuk sampai ke pengalihan, diikuti dengan transisi kernel-ke-pengguna untuk sampai ke [LPWSPRecv](nc-ws2spi-lpwsprecv.md) atau [LPWSPSend](nc-ws2spi-lpwspsend.md). Saat kembali, transisi ini dicabut secara terbalik. Ini bisa menjadi penalti performa yang signifikan. Setiap penyedia layanan yang menggunakan **WPUCreateSocketHandle** untuk membuat handel soketnya tidak boleh mengatur XP1_IFS_HANDLES dalam struktur WSAProtocol_Info . Klien harus mengambil tidak adanya XP1_IFS_HANDLES sebagai panduan untuk menghindari penggunaan **ReadFile** dan **WriteFile**.

**Catatan** Tidak ada penalti performa yang luar biasa untuk menggunakan mekanisme port penyelesaian dengan handel soket yang dibuat dengan **WPUCreateSocketHandle**. Penyedia layanan harus menggunakan WPUCompleteOverlappedRequest untuk mengumumkan penyelesaian operasi I/O yang tumpang tindih yang mungkin melibatkan port penyelesaian. Klien dapat dengan bebas menggunakan fungsi sistem operasi untuk membuat, mengaitkan, dan menggunakan port penyelesaian untuk pemberitahuan penyelesaian (misalnya, CreateIoCompletionPort, GetQueuedCompletionStatus, lihat dokumentasi sistem operasi yang relevan untuk detailnya). Perhatikan bahwa port penyelesaian tidak terintegrasi dengan mekanisme pemberitahuan asinkron lainnya yang ditawarkan oleh Windows Sockets 2. Artinya, klien dapat melakukan beberapa penantian yang mencakup beberapa peristiwa dan panggilan balik penyelesaian, tetapi tidak ada cara yang telah ditentukan sebelumnya bagi beberapa penantian untuk menyertakan port penyelesaian.

**Pertimbangan Penyedia Layanan Berlapis**

Prosedur ini sangat menarik bagi Penyedia Layanan Berlapis. Penyedia layanan berlapis dapat menggunakan prosedur ini, alih-alih WPUModifyIFSHandle untuk membuat handel soket yang diekspos ke kliennya. Keuntungan menggunakan prosedur ini adalah bahwa semua permintaan I/O yang melibatkan soket dapat dijamin untuk melalui penyedia layanan ini. Ini benar bahkan jika klien mengasumsikan bahwa soket adalah handel sistem file dan memanggil fungsi sistem file ReadFile dan WriteFile (meskipun akan membayar penalti performa untuk asumsi ini).

Jaminan bahwa semua I/O melewati lapisan ini adalah persyaratan untuk lapisan yang perlu memproses aliran I/O baik sebelum atau sesudah operasi I/O yang sebenarnya. Membuat handel soket menggunakan WPUCreateSocketHandle dan menentukan tabel pengiriman prosedur antarmuka penyedia layanan yang sesuai pada saat WSPStartup memastikan bahwa lapisan memiliki kesempatan untuk terlibat dalam memulai setiap operasi I/O. Ketika permintaan klien tumpang tindih operasi I/O, lapisan penyedia layanan ini biasanya harus mengatur untuk masuk ke jalur pemberitahuan penyelesaian I/O juga.

Untuk melihat mengapa ini benar, pertimbangkan apa yang terjadi jika klien mengaitkan port penyelesaian dengan handel soket untuk tujuan pemberitahuan penyelesaian I/O yang tumpang tindih. Port dikaitkan dengan handel soket yang diekspos oleh lapisan ini, bukan handel soket lapisan berikutnya. Tidak ada cara bagi lapisan ini untuk menentukan apakah port penyelesaian telah dikaitkan atau apa port tersebut. Ketika lapisan ini memanggil operasi I/O lapisan berikutnya, lapisan ini menggunakan handel soket lapisan berikutnya. Handel soket lapisan berikutnya tidak akan memiliki asosiasi port penyelesaian yang sama. Pemberitahuan port penyelesaian klien yang diharapkan tidak akan terjadi tanpa bantuan tambahan.

Cara biasa yang dilakukan penyedia layanan berlapis adalah dengan mengganti struktur I/O yang tumpang tindih yang berbeda dan parameter I/O yang tumpang tindih yang berbeda saat memanggil operasi I/O di lapisan berikutnya. Struktur I/O yang tumpang tindih dengan pengganti mereferensikan struktur dan parameter klien yang tumpang tindih yang disimpan. Pemanggilan lapisan berikutnya menyiapkan pemberitahuan panggilan balik. Ketika pemberitahuan panggilan balik terjadi, lapisan ini melakukan setiap pasca-pemrosesan yang diinginkan, mengambil informasi I/O yang tumpang tindih yang disimpan atas nama klien, membuang struktur pengganti, dan meneruskan pemberitahuan penyelesaian yang sesuai ke klien.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ws2spi.h