Fungsi WSPStartup (ws2spi.h)
Fungsi WSPStartup memulai penggunaan antarmuka penyedia layanan (SPI) Windows Sockets oleh klien.
Sintaks
int WSPStartup(
[in] WORD wVersionRequested,
[out] LPWSPDATA lpWSPData,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfo,
[in] WSPUPCALLTABLE UpcallTable,
[out] LPWSPPROC_TABLE lpProcTable
);
Parameter
[in] wVersionRequested
Versi tertinggi Windows Sockets SPI mendukung yang dapat digunakan pemanggil. Byte urutan tinggi menentukan nomor versi minor (revisi) ; byte urutan rendah menentukan nomor versi utama.
[out] lpWSPData
Penunjuk ke struktur data WSPDATA yang menerima informasi tentang penyedia layanan Windows Sockets.
[in] lpProtocolInfo
Penunjuk ke struktur WSAProtocol_Info yang menentukan karakteristik protokol yang diinginkan. Ini sangat berguna ketika DLL penyedia tunggal mampu membuat instans beberapa penyedia layanan yang berbeda.
[in] UpcallTable
Tabel pengiriman huruf besar Winsock 2 DLL (Ws2_32.dll) yang diteruskan dalam struktur WSPUpCallTable .
[out] lpProcTable
Penunjuk ke tabel penunjuk fungsi SPI. Tabel ini dikembalikan sebagai struktur WSPProc_Table .
Nilai kembali
Fungsi WSPStartup mengembalikan nol jika berhasil. Jika tidak, kode kesalahan akan menampilkan salah satu kode kesalahan yang tercantum di bawah ini.
| Kode kesalahan | Makna |
|---|---|
| Subsistem jaringan tidak tersedia. Kesalahan ini dikembalikan jika implementasi Windows Sockets tidak dapat berfungsi saat ini karena sistem yang mendasar yang digunakannya untuk menyediakan layanan jaringan saat ini tidak tersedia. | |
| Versi Winsock.dll di luar rentang. Kesalahan ini dikembalikan jika versi dukungan Windows Sockets SPI yang diminta tidak disediakan oleh penyedia layanan Windows Sockets khusus ini. | |
| Operasi Windows Sockets 1.1 yang diblokir sedang berlangsung. | |
| Batas jumlah tugas yang didukung oleh implementasi Windows Sockets telah tercapai. | |
| Parameter lpWSPData atau lpProcTable tidak valid. |
Keterangan
Penyedia layanan transportasi Windows Sockets 2 adalah DLL dengan satu titik entri prosedur yang diekspor, WSPStartup, yang digunakan untuk fungsi inisialisasi penyedia layanan. Semua fungsi penyedia layanan lainnya dapat diakses oleh Winsock 2 DLL melalui tabel pengiriman penyedia layanan yang diteruskan dalam parameter lpProcTable ke fungsi WSPStartup . DLL penyedia layanan dimuat ke dalam memori oleh WinSock 2 DLL hanya ketika diperlukan, dan dibongkar ketika layanan mereka tidak lagi diperlukan.
Antarmuka penyedia layanan juga mendefinisikan beberapa keadaan di mana penyedia layanan transportasi memanggil winsock 2 DLL (upcalls) untuk mendapatkan layanan dukungan DLL. Penyedia layanan transportasi dikembalikan tabel pengiriman huruf besar untuk DLL Winsock 2 dalam parameter UpcallTable yang diteruskan ke fungsi WSPStartup .
Fungsi WSPStartup harus menjadi fungsi Windows Sockets SPI pertama yang disebut oleh klien Windows Sockets SPI per proses. Ini memungkinkan klien untuk menentukan versi Windows Sockets SPI yang diperlukan dan untuk menyediakan tabel pengiriman upcall-nya. Semua upcalls (yaitu, fungsi yang diawali dengan WPU) yang dibuat oleh penyedia layanan Windows Sockets dipanggil melalui tabel pengiriman penarikan klien. Fungsi ini juga memungkinkan klien untuk mengambil detail implementasi penyedia layanan Windows Sockets tertentu. Klien Windows Sockets SPI hanya dapat mengeluarkan fungsi SPI Windows Sockets lebih lanjut setelah pemanggilan WSPStartup berhasil. Tabel penunjuk ke fungsi SPI lainnya diambil melalui parameter lpProcTable yang mengembalikan struktur WSPProc_Table .
DLL Winsock 2 memuat DLL antarmuka penyedia layanan ke dalam sistem dengan menggunakan mekanisme pemuatan pustaka dinamis Windows standar, dan menginisialisasinya dengan memanggil fungsi WSPStartup . Ini biasanya dipicu oleh aplikasi yang memanggil soket atau fungsi WSASocket untuk membuat soket baru yang akan dikaitkan dengan penyedia layanan yang DLL antarmukanya saat ini tidak dimuat ke dalam memori.
Untuk mendukung versi Windows Sockets SPI dan Ws2_32.dll di masa mendatang, yang mungkin memiliki perbedaan fungsional dari Windows Sockets SPI saat ini, negosiasi terjadi di WSPStartup. Pemanggil WSPStartup (baik Ws2_32.dll atau protokol berlapis) dan penyedia layanan Windows Sockets menunjukkan satu sama lain versi tertinggi Soket Windows yang dapat mereka dukung, dan masing-masing mengonfirmasi bahwa versi tertinggi lainnya dapat diterima. Setelah masuk ke WSPStartup, penyedia layanan Windows Sockets memeriksa versi yang diminta oleh klien. Jika versi ini sama dengan atau lebih tinggi dari versi terendah yang didukung oleh penyedia layanan, panggilan berhasil dan penyedia layanan kembali dalam anggota wHighVersion dari struktur WSPDATA versi tertinggi yang didukungnya dan di anggota wVersion minimum versi dan versi tinggi yang ditentukan dalam parameter wVersionRequested . Penyedia layanan Windows Sockets kemudian mengasumsikan bahwa klien Windows Sockets SPI akan menggunakan versi Windows Sockets yang ditentukan dalam anggota wVersion . Jika anggota wVersion dari struktur WSPDATA tidak dapat diterima oleh pemanggil, itu harus memanggil LPWSPCleanup dan mencari penyedia layanan Windows Sockets lain atau gagal menginisialisasi.
Negosiasi ini memungkinkan penyedia layanan Windows Sockets dan klien Windows Sockets SPI untuk mendukung berbagai versi Windows Sockets. Klien dapat berhasil menggunakan penyedia layanan Windows Sockets jika ada tumpang tindih dalam rentang versi.
Versi spesifikasi Windows Sockets saat ini adalah versi 2.2. Winsock DLL saat ini, Ws2_32.dll, mendukung aplikasi yang meminta salah satu versi spesifikasi Windows Sockets berikut:
- 1.0
- 1.1
- 2.0
- 2.1
- 2.2
Untuk mendapatkan akses penuh ke sintaks baru dari versi spesifikasi Windows Sockets yang lebih tinggi, aplikasi harus bernegosiasi untuk versi yang lebih tinggi ini. Dalam hal ini, parameter wVersionRequested harus diatur untuk meminta versi 2.2. Aplikasi juga harus sepenuhnya sesuai dengan versi spesifikasi Windows Socket yang lebih tinggi, seperti mengkompilasi terhadap file header yang sesuai, menautkan dengan pustaka baru, atau kasus khusus lainnya. File header Winsock2.h untuk dukungan Winsock 2 disertakan dengan Microsoft Windows Software Development Kit (SDK).
Windows Sockets versi 2.2 didukung pada Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 dengan Paket Layanan 4 (SP4) dan yang lebih baru, Windows Me, Windows 98, dan Windows 95 OSR2.
Windows Sockets versi 2.2 juga didukung pada
Windows 95 dengan Windows Socket 2 Update. Aplikasi pada platform ini biasanya harus meminta Winsock 2.2 dengan mengatur parameter wVersionRequested yang sesuai.
Pada Windows 95 dan versi Windows NT 3.51 dan yang lebih lama, Windows Sockets versi 1.1 adalah versi tertinggi dari spesifikasi Windows Sockets yang didukung.
Adalah legal dan mungkin bagi aplikasi atau DLL yang ditulis untuk menggunakan versi spesifikasi Windows Sockets yang lebih rendah yang didukung oleh Winsock DLL agar berhasil menegosiasikan versi yang lebih rendah ini menggunakan fungsi WSPStartup . Misalnya, aplikasi dapat meminta versi 1.1 dalam parameter wVersionRequested yang diteruskan ke fungsi WSPStartup pada platform dengan DLL Winsock 2.2. Dalam hal ini, aplikasi hanya boleh mengandalkan fitur yang sesuai dengan versi yang diminta. Kode Ioctl baru, perilaku baru fungsi yang ada, dan fungsi baru tidak boleh digunakan. Negosiasi versi yang disediakan oleh WSPStartup terutama digunakan untuk memungkinkan aplikasi Winsock 1.1 yang lebih lama dikembangkan untuk Windows 95 dan Windows NT 3.51 dan yang lebih lama untuk berjalan dengan perilaku yang sama pada versi Windows yang lebih baru. File header Winsock.h untuk dukungan Winsock 1.1 disertakan dengan Windows SDK.
Bagan berikut memberikan contoh cara kerja WSPStartup bersama dengan versi penyedia layanan (SP) WS2_32.DLL dan Windows Sockets yang berbeda.
| DLL |
SP |
wVersionRequested | wVersion | wHighVersion | Hasil akhir |
|---|---|---|---|---|---|
| 1.1 | 1.1 | 1.1 | 1.1 | 1.1 | gunakan 1.1 |
| 1.0 1.1 | 1.0 | 1.1 | 1.0 | 1,0 | gunakan 1.0 |
| 1,0 | 1.0 1.1 | 1,0 | 1.0 | 1.1 | gunakan 1.0 |
| 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | gunakan 1.1 |
| 1.1 | 1.0 | 1.1 | 1.0 | 1,0 | DLL gagal |
| 1.0 | 1.1 | 1.0 | --- | --- | WSAVERNOTSUPPORTED |
| 1.0 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | gunakan 1.1 |
| 1.0 1.1 2.0 | 1.1 | 2.0 | 1.1 | 1.1 | gunakan 1.1 |
| 1.0 1.1 2.0 | 2.0 | 2.0 | 2.0 | 2.0 | gunakan 2.0 |
| 1.0 1.1 2.0 2.1 2.2 | 2.2 | 2.2 | 2.2 | 2.2 | gunakan 2.2 |
Fragmen kode berikut menunjukkan bagaimana klien Windows Sockets SPI, yang hanya mendukung SPI Soket Windows versi 2, melakukan panggilan WSPStartup :
WORD wVersionRequested;
WSPDATA WSPData;
int err;
WSPUPCALLTABLE upcallTable =
{
/* initialize upcallTable with function pointers */
};
LPWSPPROC_TABLE lpProcTable =
{
/* allocate memory for the ProcTable */
};
wVersionRequested = MAKEWORD( 2, 2 );
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
/* Tell the user that we could not find a usable */
/* Windows Sockets service provider. */
return;
}
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider supports versions */
/* greater than 2.2 in addition to 2.2, it will still */
/* return 2.2 in wVersion since that is the version we */
/* requested. */
if ( LOBYTE( WSPData.wVersion ) != 2 ||
HIBYTE( WSPData.wVersion ) != 2 ) {
/* Tell the user that we could not find a usable */
/* Windows Sockets service provider. */
LPWSPCleanup( );
return;
}
/* The Windows Sockets service provider is acceptable. Proceed. */
Dan fragmen kode ini menunjukkan bagaimana penyedia layanan Windows Sockets yang hanya mendukung versi 2.2 melakukan negosiasi WSPStartup :
/* Make sure that the version requested is >= 2.2. */
/* The low byte is the major version and the high */
/* byte is the minor version. */
if ( (LOBYTE( wVersionRequested ) < 2) ||
((LOBYTE( wVersionRequested ) == 2) &&
(HIBYTE( wVersionRequested ) < 2))) {
return WSAVERNOTSUPPORTED;
}
/* Since we only support 2.2, set both wVersion and */
/* wHighVersion to 2.2. */
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );
Setelah klien Windows Sockets SPI melakukan panggilan WSPStartup yang sukses, klien dapat melanjutkan untuk melakukan panggilan Windows Sockets SPI lainnya sesuai kebutuhan. Setelah selesai menggunakan layanan penyedia layanan Windows Sockets, klien harus memanggil LPWSPCleanup untuk memungkinkan penyedia layanan Windows Sockets membebaskan sumber daya apa pun yang dialokasikan untuk klien.
Fungsi WSPStartup harus dipanggil setidaknya sekali oleh setiap proses klien, dan dapat dipanggil beberapa kali oleh Winsock 2 DLL atau entitas lainnya. Fungsi LPWSPCleanup yang cocok harus dipanggil untuk setiap panggilan WSPStartup yang berhasil. Penyedia layanan harus mempertahankan jumlah referensi berdasarkan per proses. Pada setiap panggilan WSPStartup , pemanggil dapat menentukan nomor versi apa pun yang didukung oleh DLL penyedia layanan.
Penyedia layanan harus menyimpan penunjuk ke tabel pengiriman pencadangan klien yang diterima sebagai parameter UpcallTable oleh fungsi WSPStartup berdasarkan per proses. Jika proses tertentu memanggil WSPStartup beberapa kali, penyedia layanan hanya boleh menggunakan penunjuk tabel pengiriman huruf besar yang terakhir disediakan.
Klien Windows Sockets SPI dapat memanggil WSPStartup lebih dari sekali jika perlu mendapatkan informasi struktur WSPDATA lebih dari sekali. Pada setiap panggilan tersebut, klien dapat menentukan nomor versi apa pun yang didukung oleh penyedia.
Harus ada satu panggilan LPWSPCleanup yang sesuai dengan setiap panggilan WSPStartup yang berhasil untuk memungkinkan DLL pihak ketiga menggunakan penyedia Soket Windows. Ini berarti, misalnya, bahwa jika WSPStartup dipanggil tiga kali, panggilan yang sesuai ke LPWSPCleanup harus terjadi tiga kali. Dua panggilan pertama ke LPWSPCleanup tidak melakukan apa pun kecuali menurunkan penghitung internal; panggilan LPWSPCleanup akhir melakukan semua dealokasi sumber daya yang diperlukan.
Fungsi ini (dan sebagian besar fungsi penyedia layanan lainnya) dapat dipanggil dalam utas yang dimulai sebagai proses 16-bit jika klien adalah klien Windows Sockets 1.1 1 16-bit. Salah satu batasan penting dari proses 16-bit adalah bahwa proses 16-bit tidak dapat membuat utas. Ini signifikan bagi pelaksana penyedia layanan yang berencana menggunakan utas layanan internal sebagai bagian dari implementasi.
Untungnya, biasanya hanya ada dua area di mana kondisi untuk utas layanan kuat:
- Dalam implementasi penyelesaian I/O yang tumpang tindih.
- Dalam pelaksanaan LPWSPEventSelect.
Kedua area ini hanya dapat diakses melalui fungsi Windows Sockets 2 baru, yang hanya dapat dipanggil oleh proses 32-bit.
Utas layanan dapat digunakan dengan aman jika kedua aturan desain ini diikuti dengan hati-hati:
- Gunakan utas layanan hanya untuk fungsionalitas yang tidak tersedia untuk klien Windows Sockets 1.1 1 16-bit.
- Buat utas layanan hanya sesuai permintaan.
Beberapa peringatan lain berlaku untuk penggunaan utas layanan internal. Pertama, utas umumnya membawa beberapa penalti performa. Gunakan sesempurna mungkin, dan hindari transisi utas sedapat mungkin. Kedua, kode Anda harus selalu memeriksa kesalahan dalam membuat utas dan gagal dengan anggun dan informatif (misalnya, dengan WSAEOPNOTSUPP) jika beberapa peristiwa eksekusi Anda tidak mengharapkan hasil dalam proses 16-bit yang menjalankan jalur kode yang membutuhkan utas.
Penyedia layanan berlapis menyediakan implementasi fungsi ini, tetapi juga merupakan klien dari fungsi ini ketika memanggil WSPStartup untuk menginisialisasi lapisan berikutnya dalam rantai protokol. Panggilan ke WSPStartup lapisan berikutnya dapat terjadi selama eksekusi WSPStartup lapisan ini atau mungkin tertunda dan dipanggil sesuai permintaan, seperti ketika LPWSPSocket dipanggil. Bagaimanapun, beberapa pertimbangan khusus berlaku untuk parameter lpProtocolInfo fungsi ini karena disebarluaskan ke bawah melalui lapisan rantai protokol.
Penyedia berlapis mencari ProtocolChain struktur yang direferensikan oleh lpProtocolInfo untuk menentukan lokasinya sendiri dalam rantai (dengan mencari Id entri katalog lapisan itu sendiri) dan identitas elemen berikutnya dalam rantai. Jika elemen berikutnya adalah lapisan lain, maka, ketika WSPStartup lapisan berikutnya dipanggil, lapisan ini harus meneruskan ke lapisan berikutnya lpProtocolInfo yang mereferensikan struktur WSAProtocol_Info yang tidak dimodifikasi yang sama dengan informasi rantai yang tidak dimodifikasi yang sama. Namun, jika lapisan berikutnya adalah protokol dasar (yaitu, elemen terakhir dalam rantai), lapisan ini melakukan substitusi saat memanggil WSPStartup penyedia dasar. Dalam hal ini, struktur WSAPROTOCOL_INFO penyedia dasar harus dirujuk oleh parameter lpProtocolInfo .
Salah satu manfaat penting dari kebijakan ini adalah bahwa penyedia layanan dasar tidak perlu menyadari rantai protokol.
Kebijakan penyebaran yang sama ini berlaku saat menyebarkan struktur WSAPROTOCOL_INFO melalui urutan berlapis fungsi lain seperti LPWSPAddressToString, LPWSPDuplicateSocket, LPWSPSocket, atau LPWSPStringToAddress.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk