ensembles d’API Windows

Important

les informations de cette rubrique s’appliquent à toutes les versions de Windows 10 et Windows 11. nous faisons référence à ces versions ici en tant que « Windows », en appelant les exceptions si nécessaire.

toutes les versions de Windows partagent une base commune de composants du système d’exploitation appelée système d’exploitation principal (dans certains contextes, cette base commune est également appelée OneCore). Dans les composants du système d’exploitation de base, 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 à partir de la DLL hôte dans laquelle une API Win32 donnée est implémentée et le contrat fonctionnel auquel appartient l’API. Le découplage que les ensembles d’API offrent entre les implémentations 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 concernent spécifiquement les scénarios suivants :

  • bien que la totalité de l’api win32 soit prise en charge sur les pc, seul un sous-ensemble de l’api win32 est disponible sur d’autres Windows 10 et/ou Windows 11 appareils tels que les HoloLens, la 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 de l’API Win32 existent dans des dll avec des noms différents sur différents appareils Windows. Le fait d’utiliser des noms d’ensemble d’API au lieu de noms de DLL lors de la détection des API de disponibilité et de chargement différé fournit un itinéraire correct à l’implémentation, quel que soit l’endroit où l’API est implémentée.

Pour plus d’informations, consultez API Set Loader Operation et Detect API Set Availability.

Liaison à des bibliothèques de parapluie

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

Les API d’une bibliothèque de parapluie peuvent être implémentées dans une plage de modules. la bibliothèque parapluie résume ces détails en dehors de vous, ce qui rend votre code plus portable sur les versions et les appareils Windows. Au lieu de créer des liens vers des bibliothèques telles que kernel32. lib et advapi32. lib, il vous suffit de lier votre application de bureau ou pilote à la bibliothèque parapluie qui contient l’ensemble des API de système d’exploitation principales qui vous intéressent.

pour plus d’informations, consultez Windows bibliothèques de parapluie.

Noms de contrat de l’ensemble d’API

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

  • Le nom doit commencer par l' API de chaîne ou ext-.
    • les noms qui commencent par api- représentent des api qui sont garanties d’exister sur toutes les versions de Windows.
    • les noms qui commencent par ext- représentent des api qui peuvent ne pas exister sur toutes les versions de Windows.
  • Le nom doit se terminer par la séquence <n> - <n> - <n> l, où n est constitué 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 contrat 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 chargement comme LoadLibrary ou P/Invoke à la place 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, lorsque vous effectuez cette opération, vous devez ajouter la chaîne .dll à la fin du nom du contrat. Il s’agit d’une condition requise du chargeur pour fonctionner correctement et n’est pas considérée comme faisant partie du nom de contrat. Bien que les noms de contrats apparaissent comme les noms de DLL dans ce contexte, ils sont fondamentalement différents des noms de module de 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 du chargeur, les noms de contrat de l’ensemble 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 de l’article répertorie le nom de l’ensemble 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 appartenant à un ensemble d’API, consultez les articles suivants :

Contenu de cette section