Sady rozhraní API systému Windows

Důležitý

Informace v tomto tématu platí pro všechny verze Windows 10 a novější. Tyto verze zde budeme označovat jako „Windows“ a tam, kde to bude nutné, výslovně uvedeme případné výjimky.

Všechny verze Windows sdílejí společnou základnu součástí operačního systému (OS), které se nazývají základní operační systém (v některých kontextech se tato společná základna označuje také jako onecore). V základních komponentách operačního systému jsou rozhraní API Win32 uspořádaná do funkčních skupin, které se nazývají sady rozhraní API .

Účelem sady rozhraní API je poskytnout oddělení architektury mezi knihovnou DLL hostitele, ve které je implementované dané rozhraní API Win32, a funkční kontrakt, do kterého rozhraní API patří. Oddělení mezi implementací a kontrakty, které poskytují sady rozhraní API, nabízí vývojářům mnoho technických výhod. Konkrétně použití sad rozhraní API ve vašem kódu může zlepšit kompatibilitu se zařízeními s Windows.

Sady rozhraní API konkrétně řeší následující scénáře:

  • I když se na počítačích podporuje úplná šířka rozhraní API Win32, na jiných Windows zařízeních, jako jsou HoloLens, XBOX a další zařízení, je dostupná jenom podmnožina rozhraní API Win32. Název sady rozhraní API vám poskytne stabilní věc, na kterou se můžete zeptat, aby vaše aplikace zjistila za běhu, jestli je funkce dostupná na aktuálním zařízení. Samotný dotaz provádí funkce IsApiSetImplemented .

  • Některé implementace rozhraní API Win32 existují v knihovnách DLL s různými názvy na různých zařízeních s Windows. Použití názvů sady rozhraní API místo názvů DLL při zjišťování dostupnosti rozhraní API a zpoždění načítání rozhraní API poskytuje správnou trasu k implementaci bez ohledu na to, kde je rozhraní API skutečně implementováno.

Další informace naleznete v tématech Operace zavaděče sady API a Zjištění dostupnosti sady API.

Jsou sady rozhraní API a knihovny DLL stejné?

Ne – název sady rozhraní API identifikuje kontrakt, nikoli soubor. Za běhu zavaděč tento kontrakt přeloží podle schématu sady API na aktuálním zařízení a přesměruje odkaz na knihovnu DLL, která implementaci obsahuje. Jedná se o techniku skrývání implementace, kdy jako volající nemusí přesně vědět, který modul je hostitelem informací.

Tato technika umožňuje refaktoring modulů (rozdělit, konsolidovat, přejmenovat atd.) v různých verzích a edicích Windows. A vaše aplikace stále odkazují a za běhu aplikace jsou stále směrovány na správný kód.

Proč tedy sady rozhraní API mají ve svých názvech .dll? Důvodem je způsob, jakým je zavaděč DLL implementován. Zavaděč je součástí operačního systému, který načítá knihovny DLL a/nebo překládá odkazy na knihovny DLL, a identifikuje, co se má načíst podle názvu modulu, jak jsou názvy souborů napsané v tabulce importu. Názvy sady rozhraní API se řídí stejnou konvencí, aby se vešly na stejné místo.

Zavaděč rozpozná název, který začíná na api- nebo ext-, a předá jej do modulu runtime sady API, rozšíření zavaděče, které vyhodnocuje kontrakty podle schématu. Od tohoto okamžiku se název analyzuje pomocí pravidel pojmenování nastaveným rozhraním API, nikoli jako název souboru, takže .dll přípona není součástí překladu názvu kontraktu.

Funkci LoadLibrary můžete předat název sady API nebo ji použít jako cíl opožděného načítání. Operace bude úspěšná, když schéma na aktuálním zařízení namapuje tento kontrakt na použitelného hostitele; nikde v počítači přitom nemusí skutečně existovat soubor s tímto názvem. Pokud smlouva není na aktuálním zařízení namapována, přímé volání LoadLibrary selže. Odkaz načítaný se zpožděním se však chová jinak: proces se přesto načte a jeho nepřítomnost se projeví až později, při volání rozhraní API.

V každém případě úspěšné propojení nebo načtení samo o sobě není důkazem, že implementace existuje. Pokud to chcete zjistit, přečtěte si téma Detekce dostupnosti sady rozhraní API.

Propojení zastřešujících knihoven

Abychom usnadnili omezení kódu na rozhraní API Win32 podporovaná v základním operačním systému, poskytujeme řadu zastřešujících knihoven. Zastřešující knihovna umožňuje propojit jednu knihovnu místo toho, abyste identifikovali jednotlivé knihovny importu pro každé rozhraní API, které voláte.

Další informace a výběr zastřešující knihovny, která odpovídá cílové platformě, najdete v tématu Zastřešující knihovny Windows.

Názvy kontraktů sady rozhraní API

Sady API se identifikují podle názvu kontraktu, který odpovídá konvencím rozpoznávaným zavaděčem knihovny.

Všechny názvy kontraktů sdílejí tyto konvence:

  • Název začíná buď řetězcem api, nebo ext-.
  • Text názvu může být alfanumerické znaky nebo pomlčky (-). Vlnovka (~) se zobrazí pouze jako oddělovač před názvem skupiny.
  • Název nerozlišuje velikost písmen.

Používají se dvě formy názvu kontraktu a můžete narazit na jednu z nich.

Název kontraktu s verzí končí sekvencí l<n>->n>-<n<, kde n se skládá z desetinných číslic — například ext-ms-win-core-samplefeature-l1-1-0. Koncová čísla identifikují jednu konkrétní verzi kontraktu a název v tomto formuláři by se měl považovat za neměnný identifikátor této verze.

Alias kontraktu nemá verzi — například api-win-core-samplefeature. Identifikuje kontrakt sám, nikoli jednu jeho verzi. Když kontrakt uspořádá své individuálně dostupné funkce do pojmenovaných skupin, skupina je adresována připojením názvu skupiny k aliasu kontraktu oddělené vlnovkou: api-win-core-samplefeature~AdvancedOperations.

Zde samplefeature použité názvy jsou ilustrativní názvy fiktivní Windows komponenty.

Předpony api a ext-

Předpona je konvence vytváření názvů. Původně bylo zamýšleno rozlišovat kontrakty, které jsou přítomné na všech opravňujících edicích (api-) od kontraktů, které můžou chybět (ext-). Tento rozdíl nebyl konzistentně použit a role kontraktu se může v průběhu času měnit bez přejmenování kontraktu.

Zavaděč nepřikládá prefixu žádný význam; názvy api- a ext- rozpoznává podle stejných pravidel. Neodvozujte dostupnost z předpony. Místo toho se na něj dotazujte – viz Zjištění dostupnosti sady rozhraní API.

Použití názvu kontraktu

Dva různé typy operací používají název kontraktu.

Operace zavaděče – například LoadLibrary nebo P/Invoke – používají název kontraktu na stejném místě, kde se běžně uvádí název modulu DLL. Připojený .dll je v daném kontextu obvyklý, ale při překladu názvu sady API není vyžadován a není součástí názvu kontraktu. Místo názvu fyzického modulu DLL použijte název kontraktu, abyste zajistili správnou trasu k implementaci bez ohledu na to, kde je rozhraní API skutečně implementováno na aktuálním zařízení. Na disku nemusí být soubor s tímto názvem kontraktu.

Příklady dotazů na dostupnost obvykle vynechávají příponu .dll a používají tvar, který odpovídá způsobu, jakým je rozhraní API adresováno:

Plocha rozhraní API Formulář dotazu Example
Pojmenovaná skupina <contract>~<group> api-win-core-samplefeature~AdvancedOperations
Výchozí skupina Alias smlouvy, bez ~Default api-win-core-samplefeature
Verzovaná smlouva Úplný název verzované smlouvy ext-ms-win-core-samplefeature-l1-1-0

Název skupiny nelze kombinovat s názvem smlouvy s uvedenou verzí.

Určení sad API pro Win32

Pokud chcete zjistit, jestli konkrétní rozhraní API Win32 patří do sady rozhraní API, projděte si tabulku požadavků v referenční dokumentaci k rozhraní API. Pokud rozhraní API patří do sady rozhraní API, uvádí tabulka požadavků v článku název sady rozhraní API a verzi Windows, ve které bylo rozhraní API poprvé zavedeno do sady rozhraní API. Příklady rozhraní API, která patří do sady rozhraní API, najdete v těchto článcích:

Pokud hlavička rozhraní API poskytuje pomocnou Is<APIName>Present funkci, při testování dostupnosti upřednostňujte tuto pomocnou rutinu. Obsahuje již správný název sady rozhraní API nebo skupiny, která toto rozhraní API přenáší. Další informace najdete v tématu Detekce dostupnosti sady rozhraní API.

V této části

  • Last updated on