Conjuntos de API de Windows
Importante
La información de este tema se aplica a todas las versiones de Windows 10 y versiones posteriores. Aquí nos referiremos a esas versiones como "Windows", señalando las excepciones cada vez que sea necesario.
Todas las versiones de Windows tienen una base común de componentes del sistema operativo (SO) que se denomina sistema operativo principal (en algunos contextos, esta base común también se denomina OneCore). En los componentes del sistema operativo principal, las API de Win32 se organizan en grupos funcionales denominados conjuntos de API.
La finalidad de un conjunto de API es proporcionar una separación arquitectónica del archivo DLL host en el que se implementa una API de Win32 determinada y el contrato funcional al que pertenece la API. La desacoplamiento que ofrecen los conjuntos de API entre implementación y contratos ofrece muchas ventajas en el proceso 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 sirven específicamente en estos casos:
Aunque todo lo que ofrece la API de Win32 es compatible con equipos de sobremesa, solo hay un subconjunto de la API de Win32 disponible en otros dispositivos Windows, como HoloLens, Xbox y otros dispositivos. El nombre del conjunto de API aporta un mecanismo de consulta para detectar de forma limpia 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 con Windows. Si se usan nombres de conjuntos de API en lugar de nombres de DLL al detectar la disponibilidad de la API y retrasar la carga de API, se da una ruta correcta a la implementación, independientemente de dónde se implemente realmente la API.
Para obtener 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 DLL lo mismo?
No, un nombre de conjunto de API es el alias virtual de un archivo .dll físico. Es una técnica de ocultación de la implementación, donde usted como autor de la llamada no tiene que saber exactamente qué módulo hospeda la información.
La técnica permite refactorizar módulos (dividir, consolidar, cambiar el nombre, etc.) en diferentes versiones y ediciones de Windows. Las aplicaciones se siguen vinculando y enrutando en el código correcto en tiempo de ejecución.
¿Por qué en los conjuntos de API aparece .dll en sus nombres? La razón es la forma en que se implementa el cargador de DLL. El cargador es la parte del sistema operativo que carga los archivos DLL o resuelve las referencias a los archivos DLL. En el front-end, el cargador necesita que cualquier cadena pasada a LoadLibrary finalice con ".dll". Pero después del front-end, el cargador puede quitar el sufijo y consultar la base de datos del conjunto de API con la cadena final.
LoadLibrary (y el retraso de la carga) 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 ninguna parte del equipo.
Vinculación de bibliotecas paraguas
Para que sea más fácil restringir el código en las API de Win32 que se admiten en el sistema operativo principal, incluimos una serie de bibliotecas paraguas. Por ejemplo, una biblioteca paraguas denominada OneCore.lib genera las exportaciones para el subconjunto de API de Win32 que son comunes a todos los dispositivos Windows.
Para obtener más información, consulte Bibliotecas paraguas de Windows.
Nombres de contrato de conjuntos de API
Los conjuntos de API se identifican mediante un nombre de contrato seguro que sigue las convenciones estándar reconocidas por el cargador de la biblioteca.
- El nombre debe empezar por la cadena api- o ext-.
- Los nombres que empiezan por api- representan las API que existen en todas las ediciones de Windows que cumplen los requisitos de versión de la API.
- Los nombres que empiezan por ext- representan las API que pueden no existir en todas las ediciones de Windows.
- El nombre debe acabar con la secuencia l<n>-<n>-<n>, donde n consta de dígitos decimales.
- El cuerpo del nombre puede estar formado por caracteres alfanuméricos o guiones (-).
- El nombre distingue mayúsculas de minúsculas.
Estos son algunos ejemplos de nombres de contrato de conjuntos 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 para la implementación, sea donde sea que se implemente realmente la API en el dispositivo actual. Sin embargo, al hacerlo, debe incluir la cadena .dll al final del nombre del contrato. Este es un requisito del cargador para que funcione correctamente y no se considera realmente una parte del nombre de contrato. Aunque los nombres de contrato parecen similares a los nombres de DLL en este contexto, son fundamentalmente diferentes de los nombres de los módulos 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 de los conjuntos de API deben considerarse como un identificador inmutable que se corresponde con una versión de contrato específica.
Identificación de conjuntos de API para API de Win32
Para identificar si una API de Win32 determinada pertenece a un conjunto de API, consulte la tabla de requisitos en la documentación de referencia de la API. Si la API pertenece a un conjunto de API, en la tabla de requisitos del artículo aparecerá el nombre del conjunto de API y la versión de Windows en la que la API se integró por primera vez en el conjunto de API. Para ver ejemplos de API que pertenecen a un conjunto de API, consulte estos artículos: