Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Důležitý
Informace v tomto tématu platí pro všechny verze Windows 10 a novější. Na tyto verze se zde budeme odkazovat jako na "Windows", kde je to potřeba, vyvoláme případné výjimky.
Sady rozhraní API spoléhají na podporu operačního systému v zavaděčí knihovny k zavedení přesměrování oboru názvů modulu do procesu vazby knihovny. Název kontraktu sady rozhraní API nenázví soubor. Zavaděč provede přesměrování za běhu z názvu kontraktu na binární soubor hostitele, který obsahuje implementaci.
Když zavaděč v době běhu narazí na závislost na rozhraní API nastaveném za běhu, zkontroluje konfigurační data v imagi a identifikuje binární soubor hostitele pro danou sadu rozhraní API. Tato konfigurační data se nazývají schématu sady rozhraní API. Schéma se sestaví jako vlastnost operačního systému a mapování mezi sadami rozhraní API a binárními soubory se může lišit v závislosti na tom, které binární soubory jsou součástí daného zařízení. Schéma je to, co umožňuje správně směrovat importovanou funkci v jednom binárním souboru na různých zařízeních, i když byl modul, který hostuje implementaci, přejmenován, rozdělit nebo refaktorovat.
Jak se importy dostanou k implementaci
Binární soubor se může spojit s implementací sady rozhraní API dvěma způsoby, o které rozhoduje název v tabulce importu:
- Direct API set import. Binární soubor naimportuje název kontraktu sady rozhraní API. Zavaděč tento název přeloží prostřednictvím schématu sady rozhraní API na binární soubor hostitele na aktuálním zařízení.
- Import starší verze modulu Binární soubor importuje starší název modulu Windows, například samplefeature.dll. V edici, která tento modul dodává, naváže zavaděč přímo na něj. V edici, která ji nahradila, přesměruje zpětné předávání se stejným názvem import na sadu rozhraní API, kterou zavaděč pak přeloží prostřednictvím schématu.
Který z těchto názvů končí v tabulce importu, je obvykle určen knihovnou, se kterou propojíte, a nikoli zdrojem, se kterým píšete. Viz Windows zastřešující knihovny.
Upřednostněte název kontraktu sady rozhraní API pro kód, který cílí na aktuální verze Windows. Zavaděč ho přeloží přímo na hostitele bez předávání. Importujte starší název modulu, pokud potřebujete jeden binární soubor, který běží také na Windows verzích vydaných před tím, než sada rozhraní API existovala. Zpětné přeposílání udržuje binární práci na edicích, kde byl nahrazen starší modul.
Import přímé sady rozhraní API
Řešení je třístupňová posloupnost:
- Binární soubor naimportuje název kontraktu sady rozhraní API nebo ho předá službě LoadLibrary.
- Zavaděč vyhledá kontrakt ve schématu sady rozhraní API na aktuálním zařízení a najde binární soubor hostitele, na který ho schéma mapuje.
- Zavaděč načte binární soubor hostitele a vytvoří vazbu importované funkce na export hostitele.
Vzhledem k tomu, že mapování se nachází ve schématu, nikoli v systému souborů, může stejný import přeložit na různé binární soubory na různých zařízeních:
| Zařízení |
api-win-core-samplefeature mapuje na |
|---|---|
| Zařízení, které obsahuje funkci | samplefeature.dll |
| Zařízení, které dodává refaktorovanou implementaci | samplefeaturecore.dll |
| Zařízení, které funkci neobsahuje | Nenamapováno |
Zde samplefeature použité názvy jsou ilustrativní názvy fiktivní Windows komponenty.
Přijímající binární soubor neví, ke kterému hostiteli byl vázán. To je bod mechanismu: kontrakt je stabilní, zatímco modul, který implementuje, je zdarma změnit z jednoho zařízení na další.
Import názvu kontraktu se přeloží v rámci jedné operace bez modulu průběžného předávání. Je to nejúčinnější forma a normální cesta pro kód napsaný proti sadám rozhraní API.
Názvy sady rozhraní API a přípona .dll
Vzhledem k tomu, že mapování se uchovává ve schématu místo na disku, název sady rozhraní API, který končí .dll neodkazuje na soubor tohoto názvu. Součástí.dll je pouze konvence vytváření názvů, která se přenáší ze způsobu, jakým jsou názvy modulů napsané v tabulce importu. Název sady rozhraní API se podobá aliasu nebo virtuálnímu názvu fyzického souboru knihovny DLL.
Když operace zavaděče obdrží název, který začíná api- nebo ext-, zavaděč ho směruje do modulu runtime sady rozhraní API, rozšíření zavaděče, které překládá kontrakty prostřednictvím schématu. Modul runtime sady rozhraní API analyzuje název nastavením pravidel pojmenování, nikoli jako název souboru, takže přípona .dll není součástí názvu kontraktu, který se přeloží. Při práci s názvem, který se zobrazí v tabulce importu, zahrňte příponu. jinak ho můžete nechat vypnutý.
Zavaděč přeloží obě formy názvu kontraktu, název verze kontraktu a alias kontraktu prostřednictvím stejného schématu. Konvence, které tyto názvy řídí, najdete v tématu o nastavení názvů kontraktů rozhraní API.
Stabilita názvů není stejná jako dostupnost
Název sady rozhraní API je stabilní napříč Windows zařízeními v tom smyslu, že stejný název vždy identifikuje stejný kontrakt všude, kde je rozpoznán. To je vlastnost oboru názvů, nikoli záruka na žádné konkrétní zařízení.
Daný kontrakt může být v zařízení chybí nebo není namapován na hostitele. Nic o názvu vám nepovídá, které. Pokud chcete zjistit, jestli implementace skutečně existuje, přečtěte si téma Zjištění dostupnosti sady rozhraní API.
Co řešení vyžaduje
Pro volání prostřednictvím sady rozhraní API pro dosažení implementace musí být všechny následující:
- Kontrakt se nachází ve schématu na aktuálním zařízení.
- Schéma mapuje kontrakt na binární soubor hostitele a tento hostitel lze načíst.
- Hostitel exportuje konkrétní funkci, která binární soubor volá.
Pokud se některá z těchto možností neudrží, kde se zobrazí informace o selhání, závisí na tom, jak jste naimportovali sadu rozhraní API:
| Styl importu | Chování v případě, že kontrakt nejde vyřešit |
|---|---|
| Statický import | Proces se nepovede spustit. Zavaděč vyřeší statické importy před spuštěním jakéhokoli kódu. |
| Import načtený se zpožděním | Proces se spustí normálně. Řešení se odloží na první volání rozhraní API, kde váš kód zvládne selhání. |
Chybějící export se hlásí odděleně od chybějící smlouvy; Binární soubor, který importuje funkci, kterou hostitel neexportuje, selže s chybou chybějícího vstupního bodu.
Co vám úspěšné načtení neřekne
Řešení vytvoří vazbu kontraktu na hostitele. Nevyhodnocuje stav jednotlivých schopností v rámci kontraktu.
Kontrakt může uspořádat své individuálně dostupné funkce do pojmenovaných skupin. Skupina může být na zařízení nedostupná, i když se kontrakt, který ji přenese, vyřeší normálně, protože zavaděč se sváže s podrobnostmi kontraktu a při vytváření vazeb se nekonzultuje se stavem skupiny. To je záměrné: Odmítnutí vazby hostitele je závažná pro statický import, takže zavaděč vezme permisivní cestu a nechá dotaz na volajícího.
Důsledkem vašeho kódu je, že úspěšné načtení nebo úspěšné volání LoadLibrary není důkazem, že je k dispozici konkrétní funkce. Položte tuto otázku explicitně pomocí dotazu na dostupnost. Viz Zjištění dostupnosti sady rozhraní API.
Volitelné sady rozhraní API a zpoždění načítání
Pokud vaše aplikace volá sadu rozhraní API, která nemusí být k dispozici, není dostatečná kontrola dostupnosti: při statickém importu se proces nespustí, takže spuštění nikdy nedosáhne kontroly.
Pokud chcete zachovat dosažitelnou volitelnou cestu ke kódu, nakonfigurujte modul, který přenáší volitelné rozhraní API pro odložené načítání, nebo dynamicky přeložte cíl pomocí LoadLibrary a GetProcAddress po úspěšném dotazu na dostupnost. Podrobnosti o obou přístupech najdete v tématu Zjištění dostupnosti sady rozhraní API.
Zpětné přeposílání
I když názvy sady rozhraní API poskytují stabilní obor názvů pro moduly napříč zařízeními, není vždy praktické převést všechny binární soubory na tento systém. Aplikace může být často používána po mnoho let a rekompilování binárních souborů nemusí být proveditelné. Některé aplikace také musí běžet na systémech vytvořených před zavedením konkrétních sad rozhraní API.
Aby bylo možné zajistit, že edice, které nepřenášejí původní moduly, obsahují sadu reverzních služeb předávání: binární soubory kompatibility, které mají názvy modulů původně zavedené na Windows počítačích a které přesměrují jejich exporty do sad rozhraní API.
Úplná desktopová edice dodává původní moduly, takže import starší verze názvu modulu se sváže s modulem tak, jak je vždy k dispozici. V edici, která nahradila tento modul, přeposílací modul se stejným názvem pokrývá mezeru.
Operace zavaděče se chová takto:
- Zavaděč se zobrazí se závislostí na starším názvu modulu počítače Windows, který na zařízení není.
- Zavaděč vyhledá reverzní modul, který nese tento název modulu, a načte ho.
- Funkce zpětného předávání přesměruje importovanou funkci na sadu rozhraní API.
- Zavaděč přeloží toto rozhraní API nastavené prostřednictvím schématu, jak je popsáno výše v tomto tématu.
V koncepčním případě mapování vypadá takto:
Importovaná knihovna DLL: samplefeature.dll
- V edici, která má původní modul: samplefeature.dll
- V edici, která ho nahradila: samplefeature.dll zpětného předávání ->
api-win-core-samplefeature-samplefeaturecore.dll>
Limit pro tuto cestu je pokrytí exportu. Reverzní modul pro předávání nese pouze exporty, které mají nastavené ekvivalenty rozhraní API, takže nemusí nutně exportovat každou funkci, kterou původní modul provedl. Binární soubor, který importuje funkci, kterou nepřenáší zpětné předávání, se nepovede načíst s chybou chybějícího vstupního bodu.
Zpětné přeposílání je také důvodem, proč zacházet s úspěšným řešením jako s důkazem, že implementace existuje. Volání GetProcAddress proti názvu starší verze modulu může vrátit platný ukazatel funkce, který se přeloží na zástupný kód vracející chybu. Místo toho explicitně zadejte dotaz na dostupnost. Viz Zjištění dostupnosti sady rozhraní API.
Poznámka
Zpětné přeposílání pokrývá pouze podmnožinu povrchu rozhraní API Win32. Neumožňuje aplikacím, které cílí na desktopové verze Windows, běžet na všech Windows zařízeních. Pokud váš binární soubor cílí na aktuální verze Windows, název kontraktu sady rozhraní API je přímější volbou.