Windows-API-Sätze

  • Artikel

Wichtig

Die Informationen in diesem Thema gelten für alle Versionen von Windows 10 und höher. Wir bezeichnen diese Versionen hier als "Windows" und nennen alle Ausnahmen bei Bedarf.

Alle Versionen von Windows verwenden eine gemeinsame Basis von Betriebssystemkomponenten, die als Kernbetriebssystem bezeichnet wird (in einigen Kontexten wird diese gemeinsame Basis auch als OneCore bezeichnet). In kernigen Betriebssystemkomponenten sind Win32-APIs in Funktionsgruppen organisiert, die als API-Gruppen bezeichnet werden.

Der Zweck einer API-Gruppe besteht darin, eine Architekturtrennung von der Host-DLL bereitzustellen, in der eine bestimmte Win32-API implementiert ist, und dem Funktionsvertrag, zu dem die API gehört. Die Entkoppelung, die API-Sätze zwischen Implementierung und Verträgen bieten, bietet entwicklern viele Technische Vorteile. Insbesondere die Verwendung von API-Sätzen in Ihrem Code kann die Kompatibilität mit Windows-Geräten verbessern.

API-Gruppen behandeln insbesondere die folgenden Szenarien:

  • Obwohl die gesamte Breite der Win32-API auf PCs unterstützt wird, ist nur eine Teilmenge der Win32-API auf anderen Windows-Geräten wie HoloLens, Xbox und anderen Geräten verfügbar. Der Name des API-Satz stellt einen Abfragemechanismus bereit, um zu erkennen, ob eine API auf einem bestimmten Gerät verfügbar ist.

  • Einige Win32-API-Implementierungen sind in DLLs mit unterschiedlichen Namen auf verschiedenen Windows-Geräten vorhanden. Die Verwendung von API-Setnamen anstelle von DLL-Namen beim Erkennen der API-Verfügbarkeit und verzögern des Ladens von APIs bieten eine korrekte Route zur Implementierung, unabhängig davon, wo die API tatsächlich implementiert wird.

Weitere Informationen finden Sie unter API Set Loader-Vorgang und Erkennen der Verfügbarkeit von API-Satz.

Sind API-Sätze und DLLs identisch?

Nein: Ein API-Satzname ist ein virtueller Alias für eine physische .dll Datei. Es handelt sich um eine Methode zum Ausblenden der Implementierung, bei der Sie als Aufrufer nicht genau wissen müssen, welches Modul die Informationen hostet.

Die Technik ermöglicht es, Module in verschiedenen Windows-Versionen und Editionen umzugestalten (aufgeteilt, konsolidiert, umbenannt usw.). Und Ihre Apps verknüpfen weiterhin und werden trotzdem zur Laufzeit an den richtigen Code weitergeleitet.

Warum haben .dll API-Sätze also ihren Namen? Der Grund ist die Implementierung des DLL-Ladeprogramms . Der Ladevorgang ist der Teil des Betriebssystems, der DLLs lädt und/oder Verweise auf DLLs auflöst. Und am Front-End erfordert das Loader, dass jede an LoadLibrary übergebene Zeichenfolge mit ".dll" beendet wird. Nach diesem Front-End kann das Ladeprogramm dieses Suffix entfernen und die API set-Datenbank mit der resultierenden Zeichenfolge abfragen.

LoadLibrary (und verzögertes Laden) ist erfolgreich mit einem API-Setnamen (mit dem ".dll" darin); es gibt jedoch nicht unbedingt eine tatsächliche Datei mit diesem Namen an einer beliebigen Stelle auf dem PC.

Verknüpfen von Dachbibliotheken

Damit Sie Ihren Code auf Win32-APIs beschränken können, die im Kernbetriebssystem unterstützt werden, stellen wir eine Reihe von Übergeordneten Bibliotheken bereit. Eine Übergeordnete Bibliothek mit dem Namen OneCore.lib stellt beispielsweise die Exporte für die Teilmenge der Win32-APIs bereit, die allen Windows-Geräten gemeinsam sind.

Weitere Informationen finden Sie unter Windows-Dachbibliotheken.

Namen des API-Satzvertrags

API-Sätze werden durch einen starken Vertragsnamen identifiziert, der diesen vom Bibliotheksladeprogramm erkannten Standardkonventionen folgt.

  • Der Name muss entweder mit der Zeichenfolge api- oder ext- beginnen.
    • Namen, die mit api beginnen, stellen APIs dar, die garantiert in allen Windows-Versionen vorhanden sind.
    • Namen, die mit ext- beginnen, stellen APIs dar, die möglicherweise nicht in allen Windows-Versionen vorhanden sind.
  • Der Name muss mit der Sequenz l<n-n-n>><>< enden, wobei n aus Dezimalstellen besteht.
  • Der Text des Namens kann alphanumerische Zeichen oder Bindestriche (-) sein.
  • Für den Namen wird die Groß-/Kleinschreibung nicht beachtet.

Hier sind einige Beispiele für API-Satzvertragsnamen:

  • api-ms-win-core-ums-l1-1-0
  • ext-ms-win-com-ole32-l1-1-5
  • ext-ms-win-ntuser-window-l1-1-0
  • ext-ms-win-ntuser-window-l1-1-1

Sie können einen API-Satznamen im Kontext eines Ladevorgangs wie LoadLibrary oder P/Invoke anstelle eines DLL-Modulnamens verwenden, um eine korrekte Route zur Implementierung sicherzustellen, unabhängig davon, wo die API tatsächlich auf dem aktuellen Gerät implementiert ist. Wenn Sie dies jedoch tun, müssen Sie die Zeichenfolge .dll am Ende des Vertragsnamens anfügen. Dies ist eine Anforderung des Ladeprogramms, um ordnungsgemäß zu funktionieren, und wird nicht als Teil des Vertragsnamens betrachtet. Vertragsnamen ähneln in diesem Kontext zwar DLL-Namen, unterscheiden sich jedoch grundlegend von DLL-Modulnamen und beziehen sich nicht direkt auf eine Datei auf dem Datenträger.

Mit Ausnahme des Anfügens der Zeichenfolge .dll in Loader-Vorgängen sollten API-Satzvertragsnamen als unveränderlicher Bezeichner betrachtet werden, der einer bestimmten Vertragsversion entspricht.

Identifizieren von API-Sätzen für Win32-APIs

Um zu ermitteln, ob eine bestimmte Win32-API zu einer API-Gruppe gehört, lesen Sie die Anforderungstabelle in der Referenzdokumentation für die API. Wenn die API zu einem API-Satz gehört, werden in der Anforderungstabelle im Artikel der Name des API-Satz und die Windows-Version aufgeführt, in der die API zum ersten Mal in den API-Satz eingeführt wurde. Beispiele für APIs, die zu einer API-Gruppe gehören, finden Sie in den folgenden Artikeln:

In diesem Abschnitt