Bewerking van api-setlaadprogramma

API-sets zijn afhankelijk van besturingssysteemondersteuning in het bibliotheeklaadprogramma om een modulenaamruimteomleiding te introduceren in het bindingsproces van de bibliotheek. Een contractnaam voor een API-set heet geen bestand. De loader voert een runtime-omleiding van die contractnaam uit naar het binaire hostbestand dat de implementatie bevat.

Wanneer het laadprogramma een afhankelijkheid ondervindt van een API-set tijdens runtime, raadpleegt het configuratiegegevens in de installatiekopie om het binaire hostbestand voor die API-set te identificeren. Deze configuratiegegevens worden het schema API-set genoemd. Het schema wordt samengesteld als een eigenschap van het besturingssysteem en de toewijzing tussen API-sets en binaire bestanden kan verschillen, afhankelijk van welke binaire bestanden op een bepaald apparaat zijn opgenomen. Met het schema kan een geïmporteerde functie in één binair bestand correct worden gerouteerd op verschillende apparaten, zelfs wanneer de module die als host fungeert voor de implementatie, is hernoemd, gesplitst of geherstructureerd.

Hoe importen een implementatie bereiken

Een binair bestand kan op twee manieren een API-setimplementatie bereiken, die wordt bepaald door de naam in de importtabel:

• Direct API-set importeren. Het binaire bestand importeert de naam van een API-setcontract. De loader lost die naam op via het API-setschema op het binaire hostbestand op het huidige apparaat.
• Verouderde module importeren. Het binaire bestand importeert een verouderde Windows modulenaam, zoals samplefeature.dll. Op een editie die die module verzendt, bindt het laadprogramma er rechtstreeks aan. In een editie die deze heeft vervangen, leidt een omgekeerde doorstuurserver met dezelfde naam de import om naar een API-set, die vervolgens wordt omgezet via het schema.

Welke van deze namen in de importtabel terechtkomt, wordt meestal bepaald door de bibliotheek waarmee u een koppeling maakt in plaats van door de bron die u schrijft. Zie Windows paraplubibliotheken.

Geef de voorkeur aan de naam van het API-setcontract voor code die is gericht op de huidige versies van Windows. Het laadprogramma lost het rechtstreeks op de host op, zonder dat er tussendoor doorstuurservers zijn. Importeer de verouderde modulenaam wanneer u één binair bestand nodig hebt dat ook wordt uitgevoerd op Windows versies die zijn uitgebracht voordat de API-set bestond. Omgekeerd doorsturen houdt dat binair werken aan edities waar de verouderde module is vervangen.

Direct API-set importeren

Oplossing is een reeks van drie stappen:

1. Uw binaire bestand importeert een api-set contractnaam of geeft er een door aan LoadLibrary.
2. Het laadprogramma zoekt het contract op in het API-setschema op het huidige apparaat en zoekt het binaire hostbestand waaraan het schema is toegewezen.
3. Het laadprogramma laadt dat binaire host en verbindt de geïmporteerde functie aan de export van de host.

Omdat de toewijzing zich in het schema bevindt in plaats van in het bestandssysteem, kan dezelfde import worden omgezet in verschillende binaire bestanden op verschillende apparaten:

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

Het verbruikende binaire bestand weet niet aan welke host deze is gebonden. Dat is het punt van het mechanisme: het contract is stabiel, terwijl de module die het implementeert, vrij is om van het ene apparaat naar het volgende te veranderen.

Een import van een contractnaam wordt in één bewerking opgelost, zonder dat er een tussenliggende doorstuurmodule betrokken is. Dit is de meest efficiënte vorm en het normale pad voor code die is geschreven op basis van API-sets.

Api-setnamen en het achtervoegsel .dll

Omdat de toewijzingen in het schema worden bewaard in plaats van op schijf, verwijst een API-setnaam die eindigt op .dll niet naar een bestand met die naam verwijst. Het .dll onderdeel is slechts een naamconventie, die wordt overgedragen van de manier waarop modulenamen in een importtabel worden gespeld. De naam van de API-set lijkt meer op een alias of een virtuele naam voor een fysiek DLL-bestand.

Wanneer een laadprogramma een naam ontvangt die begint met api- of ext-, stuurt het laadprogramma deze naar de API-setruntime, een uitbreiding van het laadprogramma dat contracten via het schema oplost. De API-setruntime parseert de naam door naamgevingsregels voor API-set in plaats van als bestandsnaam, dus het achtervoegsel.dll maakt geen deel uit van de contractnaam die wordt omgezet. Neem het achtervoegsel op wanneer u vanuit een naam werkt zoals deze wordt weergegeven in een importtabel; anders kunt u het uitschakelen.

Het laadprogramma lost beide vormen van contractnaam, een versie van een contractnaam en een contractalias op via hetzelfde schema. Zie voor de conventies die deze namen bepalen, de contractnamen van de API-set.

Naamstabiliteit is niet hetzelfde als beschikbaarheid

Een API-setnaam is stabiel op Windows apparaten, in de zin dat dezelfde naam altijd hetzelfde contract identificeert waar het wordt herkend. Dat is een eigenschap van de naamruimte, geen garantie over een bepaald apparaat.

Een bepaald contract kan afwezig zijn van een apparaat of aanwezig zijn, maar niet toegewezen aan een host. Niets over de naam vertelt je wat. Als u wilt weten of de implementatie er daadwerkelijk is, raadpleegt u De beschikbaarheid van de Detect-API-set.

Welke oplossing vereist

Voor een aanroep via een API-set om een implementatie te bereiken, moet u het volgende bewaren:

• Het contract is aanwezig in het schema op het huidige apparaat.
• Het schema wijst het contract toe aan een binair hostbestand en die host kan worden geladen.
• De host exporteert de specifieke functie die uw binaire bestand aanroept.

Wanneer een van deze niet beschikbaar is, is de fout afhankelijk van de wijze waarop u de API-set hebt geïmporteerd:

Een ontbrekende export wordt afzonderlijk van een ontbrekend contract gerapporteerd; een binair bestand dat een functie importeert die de host niet exporteert, mislukt met een ontbrekende invoerpuntfout.

Wat een geslaagde belasting u niet vertelt

Oplossing verbindt een contract met een host. De status van een afzonderlijke mogelijkheid binnen dat contract wordt niet geëvalueerd.

Een contract kan de afzonderlijke beschikbare mogelijkheden in benoemde groepen organiseren. Een groep kan niet beschikbaar zijn op een apparaat, ook al wordt het contract dat het draagt normaal opgelost, omdat het laadprogramma bij contractgranulariteit bindt en de groepsstatus niet raadpleegt wanneer het bindt. Dat is opzettelijk: het weigeren om een host te binden is fataal voor een statische import, dus de laadlader neemt het permissieve pad en laat de fijnere vraag aan de beller over.

Het gevolg van uw code is dat een geslaagde belasting of een geslaagde LoadLibrary-aanroep geen bewijs is dat een bepaalde mogelijkheid beschikbaar is. Stel die vraag expliciet met een beschikbaarheidsquery. Zie Beschikbaarheid van detect-API-set.

Optionele API-sets en vertraging bij het laden

Als uw toepassing een API-set aanroept die mogelijk niet aanwezig is, is een beschikbaarheidscontrole zelf niet voldoende: met een statische importbewerking kan het proces niet worden gestart, zodat de uitvoering de controle nooit bereikt.

Als u het optionele codepad bereikbaar wilt houden, configureert u de module die de optionele API voor het laden van vertraging draagt, of lost u het doel dynamisch op met LoadLibrary en GetProcAddress nadat een beschikbaarheidsquery is geslaagd. Zie Beschikbaarheid van de Detect-API-set voor meer informatie over beide benaderingen.

Doorsturen omkeren

Hoewel api-setnamen een stabiele naamruimte bieden voor modules op verschillende apparaten, is het niet altijd praktisch om elk binair bestand naar dit systeem te converteren. Een toepassing is mogelijk al vele jaren in gebruik en het opnieuw compileren van de binaire bestanden is mogelijk niet haalbaar. Sommige toepassingen moeten ook blijven werken op systemen die zijn gebouwd voordat specifieke API-sets werden geïntroduceerd.

Hiervoor bevatten edities die de oorspronkelijke modules niet bevatten een set reverse forwarders: binaire compatibiliteitsbestanden die de modulenamen bevatten die oorspronkelijk zijn geïntroduceerd op Windows pc's en die hun exports omleiden naar API-sets.

Een volledige desktopversie verzendt de oorspronkelijke modules, zodat een import van een verouderde modulenaam wordt gekoppeld aan de module, zoals altijd. Op een editie die die module heeft vervangen, bedekt de omgekeerde doorstuurserver met dezelfde naam de kloof.

De laadprogrammabewerking gedraagt zich als volgt:

1. Het laadprogramma krijgt een afhankelijkheid te zien van een verouderde Windows pc-modulenaam die niet aanwezig is op het apparaat.
2. Het laadprogramma zoekt een omgekeerde doorstuurserver die de naam van de module draagt en laadt deze.
3. De omgekeerde doorstuurserver leidt de geïmporteerde functie om naar een API-set.
4. Met het laadprogramma wordt die API die via het schema is ingesteld, opgelost, zoals eerder in dit onderwerp is beschreven.

Conceptueel ziet de toewijzing er als volgt uit:

Geïmporteerde DLL: samplefeature.dll

• Op een editie met de oorspronkelijke module: samplefeature.dll
• Op een editie die deze heeft vervangen: samplefeature.dll omgekeerde doorstuurserver ->api-win-core-samplefeature -samplefeaturecore.dll>

De limiet voor dit pad is de exportdekking. Een omgekeerde doorstuurserver bevat alleen de exports met API-set-equivalenten, dus het exporteert niet noodzakelijkerwijs elke functie die de oorspronkelijke module heeft uitgevoerd. Een binair bestand dat een functie importeert die de omgekeerde doorstuurserver niet kan laden met een ontbrekende invoerpuntfout.

Omgekeerd doorsturen is ook een reden om een geslaagde oplossing niet te behandelen als bewijs dat er een implementatie aanwezig is. Een GetProcAddress-aanroep op basis van een verouderde modulenaam kan een geldige functieaanwijzer retourneren die wordt omgezet in een stub die een fout retourneert. Query's expliciet uitvoeren op beschikbaarheid. Zie Beschikbaarheid van detect-API-set.

Zie ook

• WINDOWS API-sets
• Beschikbaarheid van API-set detecteren
• Windows paraplubibliotheken
• LoadLibrary, functie
• GetProcAddress, functie