Conjuntos de API de Windows

  • Artículo

Importante

La información de este tema se aplica a todas las versiones de Windows 10 y versiones posteriores. Aquí se hace referencia 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 (SO) que se denominan 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 del host en el que se implementa una API win32 determinada y el contrato funcional al que pertenece la API. La 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 dispositivos Windows.

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

  • Aunque la amplitud completa de la API de Win32 es compatible con equipos, solo hay disponible un subconjunto de la API de Win32 en otros dispositivos Windows, 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.

¿Son los conjuntos de API y los archivos DLL lo mismo?

No: un nombre de conjunto de API es un alias virtual para un archivo físico .dll . Se trata de una técnica de ocultación de implementación, donde como autor de la llamada no tiene que saber exactamente qué módulo hospeda la información.

La técnica permite refactorizar los módulos (dividir, consolidar, cambiar el nombre, etc.) en diferentes versiones y ediciones de Windows. Y las aplicaciones todavía se vinculan y se enrutan al código correcto en tiempo de ejecución.

¿Por qué los conjuntos de API tienen .dll en sus nombres? El motivo es la forma en que se implementa el cargador de DLL . El cargador es la parte del sistema operativo que carga archivos DLL o resuelve las referencias a archivos DLL. Y en el front-end, el cargador requiere que cualquier cadena pasada a LoadLibrary finalice con ".dll". Pero después de ese front-end, el cargador puede quitar ese sufijo y consultar la base de datos del conjunto de API con la cadena resultante.

LoadLibrary (y la carga retrasada) se realiza correctamente con un nombre de conjunto de API (con el ".dll" en él); pero no hay necesariamente un archivo real con ese nombre en cualquier parte del equipo.

Vinculación de 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.

Para obtener más información, consulta Bibliotecas paraguas de Windows.

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 garantizan que existen en todas las versiones de Windows.
    • Los nombres que comienzan por ext - representan API que pueden no existir en todas las versiones de Windows.
  • El nombre debe terminar con la secuencia l-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 de 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 win32 determinada pertenece a un conjunto de API, revise la tabla de requisitos en 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