Conjuntos de API de Windows

Importante

La información de este tema se aplica a todas las versiones de Windows 10 y Windows 11. Aquí nos referiremos a esas versiones como "Windows", llamando a las excepciones cuando sea necesario.

Todas las versiones de Windows comparten una base común de componentes del sistema operativo que se denomina sistema operativo principal (en algunos contextos, esta base común también se denomina OneCore). En los componentes principales del sistema operativo, las API de Win32 se organizan en grupos funcionales denominados conjuntos de API.

El propósito de un conjunto de API es proporcionar una separación arquitectónica del archivo DLL de host en el que se implementa una API win32 determinada y el contrato funcional al que pertenece la API. El desacoplamiento que proporcionan los conjuntos de API entre implementación y contratos ofrece muchas ventajas de ingeniería para los desarrolladores. En concreto, el uso de conjuntos de API en el código puede mejorar la compatibilidad con Windows dispositivos.

Los conjuntos de API abordan específicamente los siguientes escenarios:

  • Aunque la amplitud completa de la API de Win32 se admite en equipos, solo hay un subconjunto de la API de Win32 disponible en otros dispositivos Windows 10 o Windows 11, como HoloLens, Xbox y otros dispositivos. El nombre del conjunto de API proporciona un mecanismo de consulta para detectar limpiamente si una API está disponible en cualquier dispositivo determinado.

  • Algunas implementaciones de API de Win32 existen en archivos DLL con nombres diferentes en distintos dispositivos Windows. El uso de nombres de conjuntos de API en lugar de nombres DLL al detectar la disponibilidad de la API y retrasar la carga de las API proporciona una ruta correcta a la implementación, independientemente de dónde se implemente realmente la API.

Para más información, consulte Operación del cargador del conjunto de API y Detección de disponibilidad del conjunto de API.

Vinculación a bibliotecas paraguas

Para facilitar la restricción del código a las API de Win32 que se admiten en el sistema operativo principal, proporcionamos una serie de bibliotecas paraguas. Por ejemplo, una biblioteca paraguas denominada OneCore.lib proporciona las exportaciones para el subconjunto de API de Win32 que son comunes a todos los dispositivos Windows.

Las API de una biblioteca paraguas se pueden implementar en una variedad de módulos. La biblioteca paraguas abstrae esos detalles, lo que hace que el código sea más portátil en Windows versiones y dispositivos. En lugar de vincular a bibliotecas como kernel32.lib y advapi32.lib, basta con vincular la aplicación de escritorio o el controlador con la biblioteca paraguas que contiene el conjunto de API principales del sistema operativo que le interesan.

Para obtener más información, consulte Windows bibliotecas paraguas.

Nombres de contrato del conjunto de API

Los conjuntos de API se identifican mediante un nombre de contrato seguro que sigue estas convenciones estándar reconocidas por el cargador de biblioteca.

  • El nombre debe comenzar con la cadena api- o ext-.
    • Nombres que comienzan por api: representan las API que se garantiza que existen en todas las versiones de Windows.
    • Los nombres que comienzan por ext- representan las API que pueden no existir en todas las versiones de Windows.
  • El nombre debe terminar con la secuencia ln-n-n<<><>>, donde n consta de dígitos decimales.
  • El cuerpo del nombre puede ser caracteres alfanuméricos o guiones (-).
  • El nombre distingue mayúsculas de minúsculas.

Estos son algunos ejemplos de nombres de contrato del conjunto de 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

Puede usar un nombre de conjunto de API en el contexto de una operación del cargador, como LoadLibrary o P/Invoke , en lugar de un nombre de módulo DLL para garantizar una ruta correcta a la implementación, independientemente de dónde se implemente realmente la API en el dispositivo actual. Sin embargo, al hacerlo, debe anexar la cadena .dll al final del nombre del contrato. Este es un requisito del cargador para funcionar correctamente y no se considera realmente una parte del nombre del contrato. Aunque los nombres de contrato aparecen similares a los nombres de DLL en este contexto, son fundamentalmente diferentes de los nombres de módulo dll y no hacen referencia directamente a un archivo en el disco.

Excepto para anexar la cadena .dll en las operaciones del cargador, los nombres de contrato del conjunto de API deben considerarse un identificador inmutable que corresponde a una versión de contrato específica.

Identificación de conjuntos de API para las API de Win32

Para identificar si una API de Win32 determinada pertenece a un conjunto de API, revise la tabla de requisitos de la documentación de referencia de la API. Si la API pertenece a un conjunto de API, la tabla de requisitos del artículo enumera el nombre del conjunto de API y la versión de Windows en la que la API se introdujo por primera vez en el conjunto de API. Para obtener ejemplos de API que pertenecen a un conjunto de API, consulte estos artículos:

En esta sección