fungsi WSCInstallProviderAndChains64_32 (ws2spi.h)
Fungsi WSCInstallProviderAndChains64_32 menginstal penyedia transportasi yang ditentukan dan rantai protokol khususnya ke database konfigurasi sistem Winsock 2 32-bit dan 64-bit pada komputer 64-bit. Fungsi ini memastikan bahwa rantai protokol diurutkan di awal informasi konfigurasi penyedia transportasi, melakukan panggilan terpisah ke WSCWriteProviderOrder tidak perlu.
Sintaks
int WSCInstallProviderAndChains64_32(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[in] const LPWSTR lpszProviderDllPath32,
[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) untuk penyedia.
[in] lpszProviderDllPath
Penunjuk ke string Unicode yang berisi jalur beban ke PENYEDIA DLL 64-bit. String ini mengamati aturan yang biasa untuk resolusi jalur dan dapat berisi string lingkungan yang disematkan (seperti %SystemRoot%). String lingkungan tersebut diperluas ketika Ws2_32.dll kemudian harus memuat DLL penyedia atas nama aplikasi. Setelah string lingkungan yang disematkan diperluas, Ws2_32.dll meneruskan string yang dihasilkan ke fungsi LoadLibrary yang memuat penyedia ke dalam memori. Untuk informasi selengkapnya, lihat LoadLibrary.
[in] lpszProviderDllPath32
Penunjuk ke string Unicode yang berisi jalur yang sepenuhnya memenuhi syarat ke dll penyedia 32-bit. String ini mengamati aturan yang biasa untuk resolusi jalur dan dapat berisi string lingkungan yang disematkan (seperti %SystemRoot%). String lingkungan tersebut diperluas ketika 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 layanan berlapis (LSP).
[in] dwServiceFlags
Bendera layanan untuk jenis entri katalog protokol berlapis yang akan dibuat. Entri protokol berlapis adalah struktur WSAProtocol_Info dengan anggota ChainLen diatur ke 0. Entri katalog aktual untuk LSP akan mereferensikan ID entri protokol berlapis ini di anggota ProtocolChain-nya .
[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
Penunjuk ke entri protokol berlapis yang baru dipasang untuk penyedia transportasi di database konfigurasi sistem Winsock 2. Ini adalah ID yang digunakan untuk membangun entri rantai protokol yang diinstal dalam katalog untuk LSP.
[out] lpErrno
Penunjuk ke kode kesalahan yang dihasilkan oleh panggilan jika fungsi gagal.
Mengembalikan nilai
Jika WSCInstallProviderAndChains64_32 berhasil, ia mengembalikan nol. Jika tidak, ia mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu dikembalikan dalam parameter lpErrno .
| Kode kesalahan | Makna |
|---|---|
| Satu atau beberapa argumen tidak berada di bagian ruang alamat pengguna yang valid. | |
| 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. | |
|
Penyedia kehilangan fungsionalitas yang diperlukan. Penyedia non-IFS harus menerapkan semua fungsi ekstensi Winsock 2 (AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, dan LPFN_WSARECVMSG (WSARecvMsg)). |
| Penginstalan penyedia sudah berlangsung. | |
| Memori tidak dapat dialokasikan untuk buffer. | |
| 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. | |
| Panggilan sistem yang seharusnya tidak pernah gagal gagal. |
Keterangan
WSCInstallProviderAndChains64_32 adalah versi yang disempurnakan dari fungsi WSCInstallProvider64_32 dasar yang digunakan untuk menginstal satu penyedia layanan transportasi. Jika penyedia layanan berlapis sedang diinstal, maka WSCInstallProviderAndChains64_32 harus digunakan. WSCInstallProviderAndChains64_32 dapat menginstal protokol berlapis dan satu atau beberapa rantai protokol dengan satu panggilan fungsi. Untuk menyelesaikan pekerjaan yang sama menggunakan WSCInstallProvider64_32 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.
WSCInstallProviderAndChains64_32 adalah WSCInstallProviderAndChains versi 64-bit. Ini menginstal penyedia ke katalog 32-bit dan 64-bit pada platform 64-bit. Ini berarti bahwa pada platform 64-bit, dua katalog Winsock dipertahankan, dan bahwa proses 32-bit dan 64-bit dapat memuat LSP yang diinstal dengan fungsi ini.
Pada komputer 64-bit, semua panggilan tidak dirancang khusus untuk 32-bit (misalnya, semua fungsi yang tidak berakhiran "32") beroperasi pada katalog 64-bit asli. Proses yang dijalankan pada komputer 64-bit harus menggunakan WSCInstallProviderAndChains64_32 untuk beroperasi pada katalog 32-bit serta katalog 64-bit, mempertahankan kompatibilitas. Definisi dan semantik panggilan 32-bit tertentu sama dengan rekan-rekan aslinya.
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 {address family, socket type, protocol} tuple dari setiap elemen dalam array yang disediakan. Sekali lagi, hanya {keluarga alamat, jenis soket, protokol} tuple yang dipertimbangkan; semua anggota dan duplikat lainnya diabaikan.
Setelah berhasil menyelesaikan panggilan ini, setiap panggilan berikutnya ke WSAEnumProtocols, WSCEnumProtocols, atau WSCEnumProtocols32 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 WSCInstallProviderAndChains64_32 akan menyertakan entri baru ketika WSAEnumProtocols, WSCEnumProtocols, dan WSCEnumProtocols32 kembali.
Setelah berhasil, WSCInstallProviderAndChains64_32 akan mencoba memperingatkan semua aplikasi yang tertarik yang telah mendaftar untuk pemberitahuan perubahan dengan memanggil WSAProviderConfigChange.
Fungsi WSCInstallProviderAndChains64_32 hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika WSCInstallProviderAndChains64_32 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.
Penyedia IFS dan Non-IFS
Penyedia IFS adalah penyedia yang mengembalikan handel sistem operasi asli. Biasanya handel ini dikaitkan dengan driver protokol mode kernel. Misalnya, TCP/IPv4 dasar, UDP/IPv4, TCP/IPv6, dan UDP/IPv6 adalah penyedia IFS karena entri ini sesuai dengan komponen mode kernel. Handel IFS dapat digunakan dalam **ReadFile**, **WriteFile**, dan **CancelIo** panggilan fungsi. Penyedia layanan berlapis yang merupakan penyedia IFS hanya mengembalikan handel soket yang dibuat dari penyedia yang lebih rendah (yang juga harus menjadi penyedia IFS) langsung ke aplikasi panggilan. IFS LSP tidak dapat mencegat pemberitahuan penyelesaian untuk panggilan Winsock.Penyedia non-IFS adalah penyedia yang membuat handel perantara dengan WPUCreateSocketHandle dan mengembalikan handel ini ke pemanggil. Ini memungkinkan LSP non-IFS untuk mencegat mengirim dan menerima peristiwa penyelesaian sebelum aplikasi panggilan untuk memungkinkan pemrosesan pasca (misalnya, mendekripsi potongan data yang diterima). Handel soket non-IFS dapat digunakan dalam panggilan ke ReadFile dan WriteFile, tetapi tidak dapat digunakan dengan CancelIo. Satu-satunya metode yang dijamin untuk membatalkan operasi pada handel non-IFS adalah dengan menutup soket dengan closesocket.
Jalur untuk DLL Penyedia 32-bit dan 64-bit
lpszProviderDllPath mewakili jalur yang sepenuhnya memenuhi syarat ke DLL penyedia versi 64-bit. Parameter ini dapat berisi string lingkungan yang disematkan (seperti %SystemRoot%).lpszProviderDllPath32 mewakili jalur yang sepenuhnya memenuhi syarat ke versi 32-bit dari DLL penyedia. Parameter ini dapat berisi string lingkungan yang disematkan (seperti %SystemRoot%).
Jika lpszProviderDllPath32adalah NULL, maka lpszProviderDllPath adalah jalur untuk penyedia 32 dan 64 bit. Ketika proses 32-bit pada komputer 64-bit berjalan (misalnya, ketika aplikasi Winsock memuat LSP versi 32-bit), aplikasi tersebut mencoba memuat penyedia 32-bit yang ditentukan dalam lpszProviderDllPath. Jika lpszProviderDllPath32ADALAH NULL, maka parameter lpszProviderDllPath harus diatur ke %windir%\system32< nama> dll. Jika tidak demikian, panggilan gagal dengan WSAEINVAL. Jika jalur di lpszProviderDllPath adalah %windir%\system32< dllname> ketika lpszProviderDllPath32 adalah NULL, panggilan akan dialihkan (menggunakan pengalih sistem file) ke direktori yang dikembalikan oleh GetSystemWow64Directory tempat LSP 32-bit harus berada. Untuk Windows XP 64-bit edition, Windows Server 2003 dan Windows Vista, direktori ini adalah %windir%\syswow64.
Persyaratan
| 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 |