Fungsi WSCSetApplicationCategory (ws2spi.h)
Sintaks
int WSCSetApplicationCategory(
[in] LPCWSTR Path,
[in] DWORD PathLength,
[in] LPCWSTR Extra,
[in] DWORD ExtraLength,
[in] DWORD PermittedLspCategories,
[out] DWORD *pPrevPermLspCat,
[out] LPINT lpErrno
);
Parameter
[in] Path
Penunjuk ke string Unicode yang berisi jalur beban ke gambar yang dapat dieksekusi untuk aplikasi. String ini mengamati aturan biasa untuk resolusi jalur dan dapat berisi string lingkungan yang disematkan (seperti %SystemRoot%).
[in] PathLength
Panjang, dalam karakter, dari parameter Jalur . Panjang ini tidak termasuk NULL yang mengakhiri.
[in] Extra
Penunjuk ke string Unicode yang mewakili argumen baris perintah yang digunakan saat memulai aplikasi yang ditentukan dalam parameter Jalur . Parameter Ekstra digunakan untuk membedakan antara beberapa instans aplikasi yang berbeda dan berbeda saat diluncurkan dengan baris perintah yang konsisten. Ini untuk mendukung kategorisasi aplikasi yang berbeda untuk berbagai instans Svchost.exe atau Rundll32.exe. Jika hanya parameter Jalur yang diperlukan dan tidak ada argumen baris perintah yang diperlukan untuk membedakan lebih lanjut antara instans aplikasi, maka parameter Ekstra harus diatur ke NULL.
[in] ExtraLength
Panjangnya, dalam karakter, dari parameter Ekstra . Panjang ini tidak termasuk NULL yang mengakhiri.
[in] PermittedLspCategories
Nilai DWORD dari kategori LSP yang diizinkan untuk semua instans aplikasi ini. Aplikasi ini diidentifikasi oleh kombinasi nilai parameter Path dan Extra .
[out] pPrevPermLspCat
Penunjuk untuk menerima serangkaian kategori LSP yang diizinkan sebelumnya yang diizinkan untuk semua instans aplikasi ini. Parameter ini bersifat opsional dapat berupa NULL.
[out] lpErrno
Penunjuk ke kode kesalahan jika fungsi gagal.
Nilai kembali
Jika tidak ada kesalahan yang terjadi, WSCSetApplicationCategory mengembalikan ERROR_SUCCESS (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. | |
| Terjadi kesalahan yang tidak dapat dipulihkan. Kesalahan ini dikembalikan dalam beberapa kondisi termasuk yang berikut ini: pengguna tidak memiliki hak istimewa administratif yang diperlukan untuk mengakses registri Winsock, atau kegagalan terjadi saat membuka entri katalog Winsock atau entri ID aplikasi. |
Keterangan
WSCSetApplicationCategory digunakan untuk mengatur bendera kategori LSP yang terkait dengan instans aplikasi. Aplikasi dapat menentukan perilaku LSP mana yang dapat diterima dalam konteks aplikasi. Oleh karena itu, melalui menentukan kategori LSP yang diizinkan, aplikasi hanya dapat mengizinkan penyedia layanan berlapis yang menerapkan perilaku yang dapat diterima untuk dimuat.
Parameter Ekstra diperlukan ketika baris perintah digunakan untuk membedakan antara instans yang berbeda dari aplikasi atau layanan yang dihosting dalam executable yang sama. Setiap instans dapat memiliki kebutuhan kategorisasi aplikasi yang berbeda. Svchost.exe dan Rundll32.exe adalah dua contoh di mana baris perintah diperlukan untuk membedakan antara instans proses yang berbeda. Untuk SvcHost.exe, sakelar -k <svcinstance> menentukan instans proses.
Untuk layanan, menggunakan Nama Layanan tidak cukup, karena Katalog Winsock global ke proses tertentu, dan proses dapat menghosting beberapa layanan.
Jika fungsi WSCSetApplicationCategory dipanggil pada aplikasi yang sama (fullpath, nama EXE, dan parameter yang sama) beberapa kali, maka kategorinya adalah ORed bersama-sama. Misalnya jika Anda mengkategorikan "c:\foo.exe -param" dengan LSP_SYSTEM lalu memanggil fungsi WSCSetApplicationCategory lagi dengan LSP_REDIRECTOR, entri yang dihasilkan untuk aplikasi ini berisi LSP_SYSTEM | LSP_REDIRECTOR. Perilaku ini dirancang untuk mendukung satu file yang dapat dieksekusi yang menghosting beberapa aplikasi dalam satu EXE (layanan sistem Windows svchost.exe, misalnya).
Soket jendela menentukan identitas aplikasi dan mengambil kategori LSP yang diizinkan selama panggilan pertama ke WSAStartup. Ini akan menjadi kumpulan kategori LSP yang diizinkan selama durasi instans aplikasi. Perubahan berikutnya pada kategori LSP yang diizinkan untuk identitas aplikasi tertentu tidak akan diambil hingga instans aplikasi berikutnya. Kategori LSP yang diizinkan tidak dapat diubah selama masa pakai instans aplikasi.
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 atau penyedia layanan berlapis adalah lapisan keamanan yang menambahkan protokol ke proses pembentukan koneksi untuk melakukan autentikasi dan untuk membuat 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.
Selama inisialisasi LSP, LSP harus menyediakan pointer ke sejumlah fungsi Winsock SPI. Fungsi-fungsi ini akan dipanggil selama pemrosesan normal oleh lapisan tepat di atas LSP (baik LSP lain atau Ws2_32.dll).
LSP yang mengimplementasikan sistem file yang dapat diinstal (IFS) dapat secara selektif memilih untuk menyediakan pointer ke fungsi yang diimplementasikan dengan sendirinya, atau meneruskan kembali pointer yang disediakan oleh lapisan tepat di bawah LSP. LSP non-IFS, karena menyediakan handel mereka sendiri, harus mengimplementasikan semua fungsi Winsock SPI. Ini karena setiap SPI akan mengharuskan LSP untuk memetakan semua handel soket yang dibuat ke handel soket penyedia yang lebih rendah (baik LSP lain atau protokol dasar).
Namun, semua LSP melakukan pekerjaan spesifik mereka dengan melakukan pemrosesan ekstra hanya pada subset fungsi Winsock SPI.
Dimungkinkan untuk menentukan kategori LSP berdasarkan subset fungsi SPI yang diterapkan LSP dan sifat pemrosesan tambahan yang dilakukan untuk masing-masing fungsi tersebut.
Dengan mengklasifikasikan LSP, serta mengklasifikasikan aplikasi yang menggunakan soket Winsock, menjadi mungkin untuk secara selektif menentukan apakah LSP harus terlibat dalam proses tertentu pada waktu proses.
Pada Windows Vista dan yang lebih baru, LSP dapat diklasifikasikan berdasarkan bagaimana ia berinteraksi dengan panggilan dan data Windows Sockets. Kategori LSP adalah grup perilaku yang dapat diidentifikasi pada subset fungsi Winsock SPI. Misalnya, filter konten HTTP akan dikategorikan sebagai pemeriksa data (kategori LSP_INSPECTOR ). Kategori LSP_INSPECTOR akan memeriksa (tetapi tidak mengubah) parameter ke fungsi SPI transfer data. Aplikasi dapat mengkueri kategori LSP dan memilih untuk tidak memuat LSP berdasarkan kategori LSP dan serangkaian kategori LSP yang diizinkan aplikasi.
Tabel berikut ini mencantumkan kategori di mana LSP dapat diklasifikasikan.
| Kategori LSP | Deskripsi |
|---|---|
| **LSP_CRYPTO_COMPRESS** | LSP adalah penyedia kriptografi atau kompresi data. |
| **LSP_FIREWALL** | LSP adalah penyedia firewall. |
| **LSP_LOCAL_CACHE** | LSP adalah penyedia cache lokal. |
| **LSP_INBOUND_MODIFY** | LSP memodifikasi data masuk. |
| **LSP_INSPECTOR** | LSP memeriksa atau memfilter data. |
| **LSP_OUTBOUND_MODIFY** | LSP memodifikasi data keluar. |
| **LSP_PROXY** | LSP bertindak sebagai proksi dan mengalihkan paket. |
| **LSP_REDIRECTOR** | LSP adalah pengalih jaringan. |
| **LSP_SYSTEM** | LSP dapat diterima untuk digunakan dalam layanan dan proses sistem. |
LSP mungkin termasuk dalam lebih dari satu kategori. Misalnya, LSP firewall/keamanan dapat termasuk dalam kategori pemeriksa (LSP_INSPECTOR) dan firewall (LSP_FIREWALL).
Jika LSP tidak memiliki kumpulan kategori, LSP dianggap berada dalam kategori Semua Lainnya. Kategori LSP ini tidak akan dimuat dalam layanan atau proses sistem (misalnya, lsass, winlogon, dan banyak proses svchost).
Fungsi WSCSetApplicationCategory hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika WSCSetApplicationCategory dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan WSANO_RECOVERY dikembalikan dalam parameter lpErrno . 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.
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 |