Fungsi WSCInstallProvider (ws2spi.h)
int WSCInstallProvider(
[in] LPGUID lpProviderId,
[in] const WCHAR *lpszProviderDllPath,
[in] const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out] LPINT lpErrno
);
[in] lpProviderId
Penunjuk ke pengidentifikasi unik global (GUID) untuk penyedia.
[in] lpszProviderDllPath
Penunjuk ke string Unicode yang berisi jalur beban ke DLL penyedia. String ini mengamati aturan 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] lpProtocolInfoList
Penunjuk ke array struktur WSAProtocol_Info . Setiap struktur mendefinisikan protokol, keluarga alamat, dan jenis soket yang didukung oleh penyedia.
[in] dwNumberOfEntries
Jumlah entri dalam array lpProtocolInfoList .
[out] lpErrno
Penunjuk ke kode kesalahan jika fungsi gagal.
Jika WSCInstallProvider berhasil, WSCInstallProvider 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. | |
| Memori tidak dapat dialokasikan untuk buffer. | |
| Terjadi kesalahan yang tidak dapat dipulihkan. Kesalahan ini dikembalikan dalam beberapa kondisi termasuk yang berikut ini: penyedia sudah diinstal, 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. | |
| Memori tidak cukup tersedia. Kesalahan ini dikembalikan ketika memori tidak cukup untuk mengalokasikan entri katalog baru. |
WSCInstallProvider digunakan untuk menginstal satu penyedia layanan transportasi. Rutinitas ini membuat informasi konfigurasi Windows Sockets 2 umum yang diperlukan untuk penyedia yang ditentukan. Ini berlaku untuk protokol dasar, protokol berlapis, dan rantai protokol. Jika penyedia layanan berlapis sedang diinstal, 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 mengimplementasikan 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 mendasar dan 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 bisa 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 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.
Parameter lpProtocolInfoList berisi daftar entri protokol untuk diinstal. Pemanggil WSCInstallProvider bertanggung jawab untuk menyiapkan entri protokol yang tepat. Parameter lpProtocolInfoList tidak boleh NULL.
Setelah berhasil menyelesaikan panggilan ini, setiap panggilan berikutnya ke WSAEnumProtocols atau WSCEnumProtocols akan mengembalikan entri protokol yang baru dibuat. Ketahuilah bahwa di lingkungan Windows, hanya instans Ws_32.dll yang dibuat dengan memanggil WSAStartup setelah keberhasilan penyelesaian WSCInstallProvider akan menyertakan entri baru ketika WSAEnumProtocols dan WSCEnumProtocols kembali.
Setelah berhasil, WSCInstallProvider akan mencoba memperingatkan semua aplikasi yang tertarik yang telah mendaftar untuk pemberitahuan perubahan dengan memanggil WSAProviderConfigChange.
Fungsi WSCInstallProvider hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika WSCInstallProvider 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 dapat 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 yang diatur ke requireAdministrator. Jika aplikasi di 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.
Setiap penginstalan file atau konfigurasi khusus penyedia layanan harus dilakukan oleh pemanggil.
| 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 |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.dll |