Ensembles d’API Windows

  • Article

Important

Les infos de cette rubrique s'appliquent à toutes les versions de Windows 10, et suivantes. Nous nous référerons ici à ces versions en tant que « Windows », en mentionnant les exceptions si nécessaire.

Toutes les versions de Windows partagent une base commune de composants du système d'exploitation (OS) appelée core OS (dans certains contextes, cette base commune est également appelée OneCore). Dans les composants centraux du système d'exploitation, les API Win32 sont organisées en groupes fonctionnels appelés Ensembles d'API.

L'objectif d'un ensemble d'API est de fournir une séparation architecturale entre la DLL hôte dans laquelle une API Win32 donnée est implémentée et le contrat fonctionnel auquel l'API appartient. Le découplage que les ensembles d'API permettent entre la mise en œuvre et les contrats offre de nombreux avantages techniques aux développeurs. En particulier, l'utilisation d'ensembles d'API dans votre code peut améliorer la compatibilité avec les appareils Windows.

Les ensembles d'API répondent spécifiquement aux scénarios suivants :

  • Bien que toute l'étendue de l'API Win32 soit prise en charge sur les PC, seul un sous-ensemble de l'API Win32 est disponible sur d'autres appareils Windows tels que HoloLens, Xbox et d'autres appareils. Le nom de l'ensemble d'API fournit un mécanisme de requête permettant de détecter proprement si une API est disponible sur un appareil donné.

  • Certaines implémentations d'API Win32 existent dans des DLL avec des noms différents sur différents appareils Windows. L'utilisation des noms des jeux d'API au lieu des noms des DLL lors de la détection de la disponibilité des API et du chargement différé des API fournit un itinéraire correct vers l'implémentation, quel que soit l'endroit où l'API est réellement implémentée.

Pour plus de détails, voir Fonctionnement du chargeur d'ensembles d'API et Détecter la disponibilité des ensembles d'API.

Les jeux d'API et les dll sont-ils la même chose ?

Non-un nom d'ensemble d'API est un alias virtuel pour un fichier physique .dll. Il s'agit d'une technique de dissimulation de l'implémentation, qui vous permet, en tant qu'appelant, de ne pas savoir exactement quel module héberge les informations.

Cette technique permet aux modules d'être remaniés (divisés, consolidés, renommés, etc.) sur différentes versions et éditions de Windows. Et vos applications restent liées, et sont toujours dirigées vers le bon code au moment de l'exécution.

Alors pourquoi les noms des ensembles d'API contiennent-ils .dll ? La raison en est la manière dont le chargeur de DLL est implémenté. Le chargeur est la partie du système d'exploitation qui charge les DLL et/ou résout les références aux DLL. Et à l'avant, le chargeur exige que toute chaîne passée à LoadLibrary se termine par « .dll ». Mais après cette partie frontale, le chargeur peut supprimer le suffixe et interroger la base de données de l'ensemble d'API avec la chaîne de caractères résultante.

LoadLibrary (et delay load) réussit avec un nom d'ensemble d'API (avec « .dll ») ; mais il n'y a pas nécessairement un fichier réel avec ce nom quelque part sur le PC.

Lier des bibliothèques parapluie

Pour faciliter la restriction de votre code aux API Win32 qui sont prises en charge dans le système d'exploitation principal, nous fournissons une série de bibliothèques parapluies. Par exemple, une bibliothèque parapluie nommée OneCore.lib fournit les exportations pour le sous-ensemble d'API Win32 qui sont communes à tous les appareils Windows.

Pour plus de détails, voir les bibliothèques Windows umbrella.

Noms de contrat des ensembles d'API

Les ensembles d'API sont identifiés par un nom de contrat fort qui suit les conventions standard reconnues par le chargeur de bibliothèques.

  • Le nom doit commencer par la chaîne api- ou ext-.
    • Les noms qui commencent par api- représentent des API qui existent sur toutes les éditions de Windows qui satisfont aux exigences de la version de l'API.
    • Les noms qui commencent par ext- représentent des API qui peuvent ne pas exister dans toutes les éditions de Windows.
  • Le nom doit se terminer par la séquence l<n>-<n>-<n>, où n est composé de chiffres décimaux.
  • Le corps du nom peut être constitué de caractères alphanumériques ou de tirets (-).
  • Le nom ne respecte pas la casse.

Voici quelques exemples de noms de contrats d'ensembles d'API :

  • 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

Vous pouvez utiliser un nom d'ensemble d'API dans le contexte d'une opération de chargement telle que LoadLibrary ou P/Invoke au lieu d'un nom de module DLL pour garantir un itinéraire correct vers l'implémentation, quel que soit l'endroit où l'API est réellement implémentée sur l'appareil actuel. Cependant, vous devez ajouter la chaîne .dll à la fin du nom du contrat. Il s'agit d'une exigence du chargeur pour qu'il fonctionne correctement et n'est pas considéré comme faisant partie du nom du contrat. Bien que les noms de contrat semblent similaires aux noms de DLL dans ce contexte, ils sont fondamentalement différents des noms de modules DLL et ne font pas directement référence à un fichier sur le disque.

À l'exception de l'ajout de la chaîne .dll dans les opérations de chargement, les noms de contrats d'ensembles d'API doivent être considérés comme un identifiant immuable correspondant à une version spécifique du contrat.

Identification des ensembles d'API pour les API Win32

Pour déterminer si une API Win32 particulière appartient à un ensemble d'API, consultez le tableau des exigences dans la documentation de référence de l'API. Si l'API appartient à un ensemble d'API, le tableau des exigences de l'article répertorie le nom de l'ensemble d'API et la version de Windows dans laquelle l'API a été introduite pour la première fois dans l'ensemble d'API. Pour des exemples d'API appartenant à un ensemble d'API, reportez-vous à ces articles :

Contenu de cette section