Share via

Ensembles d’API Windows

  • Article

Important

Les informations contenues dans cette rubrique s’appliquent à toutes les versions de Windows 10 et versions ultérieures. Nous ferons référence à ces versions ici en tant que « Windows », en appelant toutes les exceptions si nécessaire.

Toutes les versions de Windows partagent une base commune de composants de système d’exploitation appelée système d’exploitation principal (dans certains contextes, cette base commune est également appelée OneCore). Dans les principaux composants 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 de la DLL hôte dans laquelle une API Win32 donnée est implémentée et du contrat fonctionnel auquel appartient l’API. Le découplage que fournissent les ensembles d’API entre l’implémentation et les contrats offre de nombreux avantages en matière d’ingénierie pour les 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 l’étendue complète 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 pour détecter correctement 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 de noms d’ensembles d’API au lieu de noms de DLL lors de la détection de la disponibilité de l’API et du délai de chargement 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 d’informations, consultez Opération de chargeur d’ensemble d’API et Détecter la disponibilité d’un ensemble d’API.

Les ensembles d’API et les dll sont-ils identiques ?

Non : un nom de jeu d’API est un alias virtuel pour un fichier physique .dll . Il s’agit d’une technique de masquage d’implémentation, dans laquelle vous n’avez pas besoin de savoir exactement quel module héberge les informations.

La technique permet de refactoriser les modules (fractionnement, consolidation, renommage, etc.) sur différentes versions et éditions de Windows. De plus, vos applications sont toujours liées et sont toujours routées vers le code approprié au moment de l’exécution.

Pourquoi les ensembles d’API ont-ils .dll leur nom ? La raison en est la façon 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 au niveau du serveur frontal, le chargeur exige que toute chaîne passée à LoadLibrary se termine par « .dll ». Mais après ce front-end, le chargeur peut supprimer ce suffixe et interroger la base de données du jeu d’API avec la chaîne obtenue.

LoadLibrary (et retarder le chargement) réussit avec un nom d’ensemble d’API (avec le « .dll » dans celui-ci) ; mais il n’y a pas nécessairement de fichier avec ce nom n’importe où sur le PC.

Liaison de bibliothèques de parapluies

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

Pour plus d’informations, consultez Bibliothèques parapluies Windows.

Noms des contrats des ensembles d’API

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

  • Le nom doit commencer par la chaîne api- ou ext-.
    • Les noms qui commencent par api représentent des API qui sont garanties pour exister sur toutes les versions de Windows.
    • Les noms commençant par ext- représentent des API qui n’existent peut-être pas sur toutes les versions de Windows.
  • Le nom doit se terminer par la séquence l<n-n-n>><>,< où n se compose de chiffres décimaux.
  • Le corps du nom peut être des caractères alphanumériques ou des tirets (-).
  • Le nom ne respecte pas la casse.

Voici quelques exemples de noms de contrats d’ensemble 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 chargeur 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. Toutefois, dans ce cas, vous devez ajouter la chaîne .dll à la fin du nom du contrat. Il s’agit d’une exigence du chargeur pour fonctionner correctement et n’est pas considérée comme faisant partie du nom du contrat. Bien que les noms de contrats 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 disque.

À l’exception de l’ajout de la chaîne .dll dans les opérations du chargeur, les noms de contrats des ensembles d’API doivent être considérés comme un identificateur immuable qui correspond à une version de contrat spécifique.

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 dans l’article répertorie le nom du jeu d’API et la version Windows dans laquelle l’API a été introduite pour la première fois dans l’ensemble d’API. Pour obtenir des exemples d’API qui appartiennent à un ensemble d’API, consultez les articles suivants :

Contenu de cette section