Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Penting
Info dalam topik ini berlaku untuk semua versi Windows 10, dan yang lebih baru. Di sini, kami akan menyebut versi-versi tersebut sebagai "Windows", dan menyebutkan pengecualian apa pun jika perlu.
Semua versi Windows berbagi komponen dasar sistem operasi (OS) umum yang disebut OS inti (dalam beberapa konteks basis umum ini juga disebut OneCore). Dalam komponen OS inti, API Win32 diatur ke dalam grup fungsional yang disebut set API.
Tujuan dari set API adalah untuk memberikan pemisahan arsitektur antara DLL host tempat API Win32 tertentu diterapkan, dan kontrak fungsional tempat API berada. Pemisahan yang disediakan set API antara implementasi dan kontrak menawarkan banyak keuntungan rekayasa bagi pengembang. Secara khusus, menggunakan set API dalam kode Anda dapat meningkatkan kompatibilitas dengan perangkat Windows.
Set API secara khusus membahas skenario berikut:
Meskipun luas penuh API Win32 didukung pada PC, hanya subset API Win32 yang tersedia di perangkat Windows lain seperti HoloLens, XBOX, dan perangkat lainnya. Nama kumpulan API memberi Anda acuan yang stabil untuk dijadikan rujukan, sehingga aplikasi Anda dapat mendeteksi saat dijalankan apakah suatu kapabilitas tersedia pada perangkat saat ini. Kueri itu sendiri dilakukan oleh fungsi IsApiSetImplemented .
Beberapa implementasi API Win32 ada di DLL dengan nama yang berbeda di berbagai perangkat Windows. Menggunakan nama set API alih-alih nama DLL saat mendeteksi ketersediaan API dan memuat API secara tertunda akan memberikan jalur yang tepat ke implementasinya, di mana pun API tersebut sebenarnya diimplementasikan.
Untuk detail lebih lanjut, lihat operasi pemuat kumpulan API dan mendeteksi ketersediaan kumpulan API.
Apakah set API dan DLL sama?
Tidak—nama set API mengidentifikasi kontrak, bukan file. Pada waktu proses, loader menyelesaikan kontrak tersebut melalui skema set API pada perangkat saat ini, dan merutekan referensi ke DLL yang menghosting implementasi. Ini adalah teknik persembunyian implementasi, di mana Anda sebagai pemanggil tidak perlu tahu persis modul mana yang menghosting informasi.
Teknik ini memungkinkan modul untuk direfaktor (terpisah, dikonsolidasikan, diganti namanya, dan sebagainya) pada versi dan edisi Windows yang berbeda. Dan aplikasi Anda tetap tertaut, dan tetap diarahkan ke kode yang benar saat runtime.
Jadi mengapa set API memiliki .dll atas namanya? Alasannya adalah cara DLL loader diimplementasikan. Loader adalah bagian dari OS yang memuat DLL dan/atau meresolusikan referensi ke DLL, serta menentukan apa yang harus dimuat berdasarkan nama modul yang dituliskan dengan cara yang sama seperti nama file dituliskan dalam tabel impor. Nama kumpulan API mengikuti konvensi yang sama sehingga pas di tempat yang sama.
Loader mengenali nama yang dimulai dengan api- atau ext- dan merutekannya ke runtime set API, ekstensi loader yang menyelesaikan kontrak melalui skema. Mulai dari titik itu, nama tersebut diparsing menurut aturan penamaan API set, alih-alih sebagai nama file, sehingga akhiran .dll bukan bagian dari nama kontrak yang sedang diresolusikan.
Anda dapat meneruskan nama set API ke LoadLibrary, atau menggunakannya sebagai target delay-load. Operasi berhasil ketika skema pada perangkat saat ini memetakan kontrak tersebut ke host yang dapat digunakan; belum tentu ada file aktual dengan nama tersebut di mana pun pada PC. Jika kontrak tidak dipetakan pada perangkat saat ini, LoadLibrary akan langsung gagal. Referensi yang dimuat tertunda berperilaku berbeda: proses tetap dimuat, dan ketiadaannya baru terlihat kemudian, saat API dipanggil.
Bagaimanapun, tautan atau beban yang berhasil bukan dengan sendirinya bukti bahwa implementasi ada. Untuk menentukannya, lihat Mendeteksi ketersediaan set API.
Menghubungkan pustaka induk
Untuk mempermudah pembatasan kode Anda ke API Win32 yang didukung di OS inti, kami menyediakan serangkaian pustaka payung. Pustaka payung memungkinkan Anda menautkan satu pustaka alih-alih mengidentifikasi pustaka impor individual untuk setiap API yang Anda panggil.
Untuk detail selengkapnya, dan untuk memilih pustaka payung yang cocok dengan apa yang Anda targetkan, lihat pustaka payung Windows.
Nama kontrak kumpulan API
Set API diidentifikasi dengan nama kontrak yang mengikuti konvensi yang dikenali oleh pemuat pustaka.
Semua nama kontrak berbagi konvensi ini:
- Nama dimulai dengan string api- atau ext-.
- Isi nama dapat berupa karakter alfanumerik, atau tanda hubung (-). Tilde (~) hanya muncul sebagai pemisah sebelum nama grup.
- Nama tidak peka terhadap huruf besar/kecil.
Dua bentuk nama kontrak sedang digunakan, dan Anda dapat menemukan salah satu dari keduanya.
Sebuah nama kontrak berversi diakhiri dengan urutan l<n>->n<->n<, di mana n terdiri dari digit desimal—misalnya, ext-ms-win-core-samplefeature-l1-1-0. Nomor berikutnya mengidentifikasi satu versi kontrak tertentu, dan nama dalam formulir ini harus dianggap sebagai pengidentifikasi yang tidak dapat diubah untuk versi tersebut.
Alias kontrak tidak memiliki versi—misalnya, api-win-core-samplefeature. Ini mengacu pada kontrak itu sendiri, alih-alih salah satu versinya. Saat sebuah kontrak mengelompokkan kapabilitas yang tersedia secara individual ke dalam grup bernama, sebuah grup dirujuk dengan menambahkan nama grup ke alias kontrak, yang dipisahkan oleh tanda tilde: api-win-core-samplefeature~AdvancedOperations.
Nama-nama samplefeature yang digunakan di sini adalah nama ilustrasi untuk komponen Windows fiktif.
Prefiks api- dan ext-
Prefiks merupakan konvensi penamaan. Awalnya dimaksudkan untuk membedakan kontrak yang ada pada setiap edisi kualifikasi (api-) dari kontrak yang mungkin tidak ada (ext-). Perbedaan itu tidak diterapkan secara konsisten, dan peran kontrak dapat berubah dari waktu ke waktu tanpa kontrak diganti namanya.
Loader tidak memberikan makna khusus pada prefiks; ia menyelesaikan nama api- dan ext- dengan aturan yang sama. Jangan menyimpulkan ketersediaan dari awalan. Lakukan kueri sebagai gantinya—lihat Mendeteksi ketersediaan kumpulan API.
Menggunakan nama kontrak
Ada dua jenis operasi berbeda yang menggunakan nama kontrak.
Operasi loader—seperti LoadLibrary atau P/Invoke—ambil nama kontrak di tempat yang sama di mana nama modul DLL biasanya muncul. Penambahan .dll merupakan konvensi dalam konteks tersebut, tetapi tidak diwajibkan oleh proses resolusi nama kumpulan API dan bukan merupakan bagian dari nama kontrak. Gunakan nama kontrak alih-alih nama modul DLL fisik untuk memastikan rute yang benar ke implementasi di mana pun API benar-benar diterapkan pada perangkat saat ini. Tidak perlu ada file dengan nama kontrak tersebut pada disk.
Contoh kueri ketersediaan secara konvensional menghilangkan akhiran .dll dan menggunakan formulir yang cocok dengan cara API ditangani:
| Cakupan API | Formulir kueri | Example |
|---|---|---|
| Grup bernama | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| Grup bawaan | Alias kontrak, tanpa ~Default |
api-win-core-samplefeature |
| Kontrak berversi | Nama kontrak berversi lengkap | ext-ms-win-core-samplefeature-l1-1-0 |
Nama grup tidak dapat dikombinasikan dengan nama kontrak versi.
Mengidentifikasi kumpulan API untuk API Win32
Untuk mengidentifikasi apakah API Win32 tertentu milik set API, tinjau tabel persyaratan dalam dokumentasi referensi untuk API. Jika API milik set API, tabel persyaratan dalam artikel mencantumkan nama set API dan versi Windows tempat API pertama kali diperkenalkan ke set API. Untuk contoh API yang termasuk dalam set API, lihat artikel berikut:
Jika header API menyediakan fungsi pembantu Is<APIName>Present, sebaiknya gunakan fungsi tersebut saat memeriksa ketersediaan. Ini sudah berisi nama yang benar untuk kumpulan API atau grup yang memuat API tersebut. Untuk informasi selengkapnya, lihat Mendeteksi ketersediaan set API.