Fungsi WSCInstallProviderAndChains (ws2spi.h)

Artikel
03/15/2023

Catatan

Penyedia Layanan Berlapis tidak digunakan lagi. Dimulai dengan Windows 8 dan Windows Server 2012, gunakan Platform Pemfilteran Windows. Fungsi WSCInstallProviderAndChains menginstal penyedia transportasi 32-bit yang ditentukan serta rantai protokol khususnya ke dalam database konfigurasi sistem Winsock 2 pada komputer 32-bit. Fungsi ini memastikan bahwa rantai protokol diurutkan pada awal informasi konfigurasi penyedia transportasi, memastikan bahwa panggilan terpisah ke WSCWriteProviderOrder tidak diperlukan.

Sintaks

int WSCInstallProviderAndChains(
  [in]            LPGUID              lpProviderId,
  [in]            const LPWSTR        lpszProviderDllPath,
  [in]            const LPWSTR        lpszLspName,
  [in]            DWORD               dwServiceFlags,
  [in]            LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]            DWORD               dwNumberOfEntries,
  [out, optional] LPDWORD             lpdwCatalogEntryId,
  [out]           LPINT               lpErrno
);

Parameter

[in] lpProviderId

Penunjuk ke pengidentifikasi unik global (GUID) khusus penyedia.

[in] lpszProviderDllPath

Penunjuk ke string Unicode yang berisi jalur beban ke DLL penyedia. String ini mengamati aturan yang biasa untuk resolusi jalur dan dapat berisi string lingkungan yang disematkan (%SystemRoot%, misalnya). String lingkungan tersebut diperluas setiap kali Ws2_32.dll kemudian memuat DLL penyedia atas nama aplikasi. Setelah string lingkungan yang disematkan diperluas, Ws2_32.dll meneruskan string yang dihasilkan ke dalam fungsi LoadLibrary untuk memuat penyedia ke dalam memori. Untuk informasi selengkapnya, lihat LoadLibrary.

[in] lpszLspName

Penunjuk ke string Unicode yang berisi nama penyedia soket.

[in] dwServiceFlags

Bendera layanan untuk jenis entri katalog "dummy" yang akan dibuat.

Entri dummy adalah struktur WSAProtocol_Info dengan anggota ChainLen diatur ke 0. Entri katalog LSP yang sebenarnya akan mereferensikan ID entri dummy ini di anggota ProtocolChain-nya .

Kemungkinan bendera yang dapat diatur untuk parameter ini adalah sebagai berikut:

Nilai	Makna
XP1_IFS_HANDLES	Entri katalog adalah untuk LSP Installable File System (IFS), yang mengembalikan handel soket khusus IFS. Handel ini dikembalikan langsung ke aplikasi panggilan. IFS LSP tidak dapat mencegat penyelesaian panggilan Winsock, dan tidak harus menerapkan semua fungsi Winsock atau tersedia di dalamnya.

[in] lpProtocolInfoList

Penunjuk ke array struktur WSAProtocol_Info . Setiap struktur mendefinisikan protokol, keluarga alamat, dan jenis soket yang didukung oleh penyedia. Anggota struktur WSAPROTOCOL_INFO yang diperiksa adalah iProtocol, iAddressFamily, dan iSocketType.

[in] dwNumberOfEntries

Jumlah entri dalam array lpProtocolInfoList .

[out, optional] lpdwCatalogEntryId

Menerima penunjuk ke entri "dummy" yang baru diinstal untuk penyedia transportasi di database konfigurasi sistem Winsock 2. ID ini digunakan untuk menginstal entri katalog untuk LSP.

[out] lpErrno

Penunjuk yang menerima kode kesalahan yang dihasilkan oleh panggilan jika fungsi gagal.

Nilai kembali

Jika
WSCInstallProviderAndChains berhasil, mengembalikan nol. Jika tidak, ia mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu dikembalikan dalam parameter lpErrno .

Kode kesalahan	Makna
WSAEFAULT	Satu atau beberapa argumen tidak berada di bagian ruang alamat pengguna yang valid.
WSAEINVAL	Satu atau beberapa argumen tidak valid. Kesalahan ini dikembalikan untuk kondisi berikut: parameter lpProviderId adalah NULL, parameter lpszProviderDllPath tidak valid atau panjang jalur terlalu besar (MAX_PATH terlampaui), parameter lpszLspName tidak valid atau panjang nama terlalu besar (WSAPROTOCOL_LEN terlampaui), lpProtocolInfoList diatur ke non-NULL dan dwNumberOfEntries parameter adalah nol, ID penyedia duplikat atau nama penyedia layanan berlapis yang sudah ada di katalog, atau kecocokan tidak dapat ditemukan untuk protokol, keluarga alamat, dan jenis soket yang ditentukan.
WSAEINPROGRESS	Penginstalan penyedia sudah berlangsung.
WSAEINVALIDPROCTABLE	Penyedia kehilangan fungsionalitas yang diperlukan.
WSAENOBUFS	Memori tidak dapat dialokasikan untuk buffer.
WSANO_RECOVERY	Terjadi kesalahan yang tidak dapat dipulihkan. Kesalahan ini dikembalikan dalam beberapa kondisi termasuk yang berikut: penyedia sudah diinstal, parameter lpProtocolInfoList adalah NULL dan tidak ada penyedia dasar yang ditemukan, panjang rantai protokol maksimum (MAX_PROTOCOL_CHAIN) tercapai, pengguna tidak memiliki hak istimewa administratif yang diperlukan untuk menulis ke registri Winsock, atau kegagalan terjadi saat membuat atau menginstal entri katalog.
WSASYSCALLFAILURE	Panggilan sistem yang seharusnya tidak pernah gagal gagal.

Keterangan

WSCInstallProviderAndChains adalah versi yang ditingkatkan dari fungsi dasar WSCInstallProvider yang digunakan untuk menginstal satu penyedia layanan transportasi. Jika penyedia layanan berlapis sedang diinstal, maka WSCInstallProviderAndChains harus digunakan. WSCInstallProviderAndChains dapat menginstal protokol berlapis dan satu atau beberapa rantai protokol dengan satu panggilan fungsi. Untuk menyelesaikan pekerjaan yang sama menggunakan WSCInstallProvider akan memerlukan beberapa panggilan fungsi.

Winsock 2 mengakomodasi protokol berlapis. Protokol berlapis adalah protokol yang hanya menerapkan fungsi komunikasi tingkat yang lebih tinggi sambil mengandalkan tumpukan transportasi yang mendasar untuk pertukaran data aktual dengan titik akhir jarak jauh. Contoh protokol berlapis adalah lapisan keamanan yang menambahkan protokol ke proses pembentukan koneksi untuk melakukan autentikasi dan menetapkan skema enkripsi yang disepakati bersama. Protokol keamanan seperti itu umumnya akan memerlukan layanan protokol transportasi yang andal seperti TCP atau SPX. Istilah protokol dasar mengacu pada protokol seperti TCP atau SPX yang mampu melakukan komunikasi data dengan titik akhir jarak jauh. Istilah protokol berlapis digunakan untuk menjelaskan protokol yang tidak dapat berdiri sendiri. Rantai protokol kemudian akan didefinisikan sebagai satu atau beberapa protokol berlapis yang digabungkan dan dilabuhkan oleh protokol dasar. Protokol dasar memiliki anggota ChainLen dari struktur WSAProtocol_Info yang diatur ke BASE_PROTOCOL yang didefinisikan menjadi 1. Protokol berlapis memiliki anggota ChainLen dari struktur WSAPROTOCOL_INFO diatur ke LAYERED_PROTOCOL yang didefinisikan menjadi nol. Rantai protokol memiliki anggota ChainLen dari struktur WSAPROTOCOL_INFO yang diatur ke lebih besar dari 1.

Jika lpProtocolInfoList diatur ke NULL, fungsi ini membuat rantai protokol di mana penyedia berlapis di atas protokol dasar untuk setiap jenis protokol unik seperti yang didefinisikan oleh keluarga alamat, jenis soket, dan protokol. Ini menghilangkan pembuatan entri penyedia duplikat yang tidak dapat diakses.

Jika lpProtocolInfoList diatur ke nilai non-NULL , fungsi ini membuat rantai protokol dengan mendapatkan entri paling atas dalam informasi konfigurasi yang cocok dengan keluarga alamat, jenis soket, dan protokol dari setiap elemen dalam array yang disediakan. Sekali lagi, hanya keluarga alamat, jenis soket, dan protokol yang dipertimbangkan; semua anggota dan duplikat lainnya diabaikan.

Setelah berhasil menyelesaikan panggilan ini, setiap panggilan berikutnya ke WSAEnumProtocols atau WSCEnumProtocols akan mengembalikan entri rantai protokol yang baru dibuat. Ketahuilah bahwa di lingkungan Windows, hanya instans Ws_32.dll yang dibuat dengan memanggil WSAStartup setelah berhasil menyelesaikan WSCInstallProviderAndChains yang akan menyertakan entri baru ketika WSAEnumProtocols dan WSCEnumProtocols kembali.

Catatan Fungsi WSAEnumProtocols tidak menghitung entri protokol berlapis saat WSCEnumProtocols .

Setelah berhasil, WSCInstallProviderAndChains akan mencoba memperingatkan semua aplikasi yang tertarik yang telah mendaftar untuk pemberitahuan perubahan dengan memanggil WSAProviderConfigChange.

Fungsi WSCInstallProviderAndChains hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika WSCInstallProviderAndChains dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan WSANO_RECOVERY dikembalikan dalam parameter lpErrno . Untuk komputer yang menjalankan Windows Vista atau Windows Server 2008, fungsi ini juga bisa gagal karena kontrol akun pengguna (UAC). Jika aplikasi yang berisi fungsi ini dijalankan oleh pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan, panggilan ini akan gagal kecuali aplikasi telah ditandai dalam file manifes dengan requestedExecutionLevel diatur ke requireAdministrator. Jika aplikasi pada Windows Vista atau Windows Server 2008 tidak memiliki file manifes ini, pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan kemudian harus menjalankan aplikasi dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs) agar fungsi ini berhasil.

Penginstalan file atau konfigurasi khusus penyedia harus dilakukan oleh aplikasi panggilan.

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	ws2spi.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll