Windows API-sets

Alle versies van Windows delen een gemeenschappelijke basis van onderdelen van het besturingssysteem (OS) die het kernbesturingssysteem worden genoemd (in sommige contexten wordt deze algemene basis ook wel OneCoregenoemd). In kernonderdelen van het besturingssysteem worden Win32-API's ingedeeld in functionele groepen met de naam API-sets.

Het doel van een API-set is om een architectuurscheiding te bieden tussen de host-DLL waarin een bepaalde Win32-API wordt geïmplementeerd en het functionele contract waartoe de API behoort. De ontkoppeling die API-sets bieden tussen implementatie en contracten biedt veel technische voordelen voor ontwikkelaars. Met name het gebruik van API-sets in uw code kan de compatibiliteit met Windows-apparaten verbeteren.

API-sets hebben specifiek betrekking op de volgende scenario's:

• Hoewel de volledige breedte van de Win32-API wordt ondersteund op pc's, is er slechts een subset van de Win32-API beschikbaar op andere Windows apparaten, zoals HoloLens, XBOX en andere apparaten. Een API-setnaam geeft u een stabiele vraag, zodat uw app tijdens runtime kan detecteren of een mogelijkheid beschikbaar is op het huidige apparaat. De query zelf wordt uitgevoerd door de functie IsApiSetImplemented .

• Sommige Win32 API-implementaties bestaan in DLL's met verschillende namen op verschillende Windows-apparaten. Het gebruik van API-setnamen in plaats van DLL-namen bij het detecteren van API-beschikbaarheid en het vertragen van het laden van API's biedt een juiste route naar de implementatie, ongeacht waar de API daadwerkelijk wordt geïmplementeerd.

Zie de werking van de API-setloader en de beschikbaarheid van API-sets detecteren voor meer informatie.

Zijn API-sets en DLL's hetzelfde?

Nee: een naam van een API-set identificeert een contract, niet een bestand. Tijdens runtime lost de loader dat contract op aan de hand van het API-setschema op het huidige apparaat en wordt de verwijzing doorgestuurd naar de DLL waarin de implementatie wordt gehost. Het is een techniek voor het verbergen van implementaties, waarbij u als aanroeper niet precies hoeft te weten welke module de informatie host.

Met de techniek kunnen modules worden geherstructureerd (gesplitst, geconsolideerd, hernoemd, enzovoort) in verschillende Windows-versies en -edities. En je apps verwijzen nog steeds naar en worden tijdens de uitvoering nog steeds naar de juiste code geleid.

Waarom hebben API-sets .dll in hun namen? De reden hiervoor is de manier waarop het DLL-laadprogramma wordt geïmplementeerd. De loader is het onderdeel van het besturingssysteem dat DLL's laadt en/of verwijzingen naar DLL's oplost, en bepaalt wat moet worden geladen aan de hand van een modulenaam die in een importtabel wordt gespeld zoals bestandsnamen worden gespeld. Namen van API-sets volgen dezelfde conventie, zodat ze op dezelfde plaats passen.

Het laadprogramma herkent een naam die begint met api- of ext- die doorstuurt naar de API set-runtime, een uitbreiding van het laadprogramma dat contracten via het schema oplost. Vanaf dat moment wordt de naam volgens de naamgevingsregels van de API-set geïnterpreteerd in plaats van als een bestandsnaam, dus maakt het achtervoegsel .dll geen deel uit van de contractnaam die wordt opgelost.

U kunt een API-setnaam doorgeven aan LoadLibrary of deze gebruiken als doel voor vertragingsbelasting. De bewerking slaagt wanneer het schema op het huidige apparaat dat contract toewijst aan een bruikbare host; het hoeft niet zo te zijn dat er ergens op de pc daadwerkelijk een bestand met die naam bestaat. Als het contract niet aan het huidige apparaat is gekoppeld, mislukt een directe LoadLibrary. Een verwijzing met vertraagd laden gedraagt zich anders: het proces wordt nog altijd geladen en het ontbreken ervan blijkt pas later, wanneer de API wordt aangeroepen.

Hoe dan ook, succesvol linken of laden is op zichzelf nog geen bewijs dat er een implementatie beschikbaar is. Zie Beschikbaarheid van de Detect-API-set om dit te bepalen.

Paraplubibliotheken koppelen

Om het eenvoudiger te maken om uw code te beperken tot Win32-API's die worden ondersteund in het kernbesturingssystemen, bieden we een reeks paraplubibliotheken. Met een paraplubibliotheek kunt u één bibliotheek koppelen in plaats van de afzonderlijke importbibliotheek te identificeren voor elke API die u aanroept.

Zie Windows paraplubibliotheken voor meer informatie en om de paraplubibliotheek te kiezen die overeenkomt met wat u wilt instellen.

Namen van API-setcontracten

API-sets worden geïdentificeerd door een contractnaam die volgt op conventies die worden herkend door het bibliotheeklaadprogramma.

Alle contractnamen delen deze conventies:

• De naam begint met de tekenreeks api- of ext-.
• De hoofdtekst van de naam kan alfanumerieke tekens of streepjes (-) zijn. Een tilde (~) wordt alleen weergegeven als het scheidingsteken voor een groepsnaam.
• De naam is niet hoofdlettergevoelig.

Er worden twee vormen van contractnaam gebruikt en u kunt een van beide tegenkomen.

Een geversiede contractnaam eindigt met de reeks l<n-n-n>><><, waarbij n bestaat uit decimale cijfers, bijvoorbeeld . ext-ms-win-core-samplefeature-l1-1-0 De volgnummers identificeren één specifieke versie van het contract en een naam in dit formulier moet worden beschouwd als een onveranderbare id voor die versie.

Een contractalias heeft geen versie, bijvoorbeeld api-win-core-samplefeature. Het identificeert het contract zelf in plaats van één versie ervan. Wanneer een contract de afzonderlijke beschikbare mogelijkheden in benoemde groepen organiseert, wordt een groep geadresseerd door de groepsnaam toe te voegen aan de contractalias, gescheiden door een tilde: api-win-core-samplefeature~AdvancedOperations.

De samplefeature namen die hier worden gebruikt, zijn illustratieve namen voor een fictief Windows onderdeel.

De API- en ext-voorvoegsels

Het voorvoegsel is een naamconventie. Het was oorspronkelijk bedoeld om contracten te onderscheiden die aanwezig zijn op elke in aanmerking komende editie (API-) van contracten die mogelijk afwezig zijn (ext-). Dat onderscheid is niet consistent toegepast en de rol van een contract kan na verloop van tijd veranderen zonder dat de naam van het contract wordt gewijzigd.

Het laadprogramma hecht geen betekenis aan het voorvoegsel; het resolveert api-- en ext-namen volgens dezelfde regels. De beschikbaarheid van het voorvoegsel niet afleiden. Voer in plaats daarvan een query uit: zie Beschikbaarheid van DE API-set detecteren.

Een contractnaam gebruiken

Twee verschillende soorten bewerkingen hebben een contractnaam.

Laadprogrammabewerkingen, zoals LoadLibrary of P/Invoke, nemen de contractnaam op dezelfde plaats als de naam van een DLL-module gewoonlijk wordt weergegeven. Een toegevoegde .dll is conventioneel in die context, maar is niet vereist voor de naamomzetting van de API-set en maakt geen deel uit van de contractnaam. Gebruik een contractnaam in plaats van een naam van een fysieke DLL-module om een juiste route naar de implementatie te garanderen, ongeacht waar de API daadwerkelijk op het huidige apparaat wordt geïmplementeerd. Er hoeft geen bestand te zijn met die contractnaam op schijf.

Voorbeelden van beschikbaarheidsquery laten het .dll achtervoegsel conventioneel weg en gebruiken het formulier dat overeenkomt met de manier waarop de API wordt aangepakt:

Een groepsnaam kan niet worden gecombineerd met een naam van een versie van een contract.

API-sets voor Win32-API's identificeren

Als u wilt bepalen of een bepaalde Win32-API deel uitmaakt van een API-set, raadpleegt u de vereistentabel in de referentiedocumentatie voor de API. Als de API deel uitmaakt van een API-set, worden in de vereistentabel in het artikel de naam van de API-set en de Windows-versie vermeld waarin de API voor het eerst is geïntroduceerd in de API-set. Zie de volgende artikelen voor voorbeelden van API's die deel uitmaken van een API-set:

• AllowSetForegroundWindow
• FindWindowEx
• GetClassFile

Als de header van de API een Is<APIName>Present helperfunctie levert, geeft u de voorkeur aan die helper wanneer u test op beschikbaarheid. Deze bevat al de juiste naam voor de API-set of -groep die de API draagt. Zie Beschikbaarheid van DE API-set detecteren voor meer informatie.

In deze sectie

• API set loader-bewerking
• Beschikbaarheid van API-set detecteren
• Windows-paraplubibliotheken