Conjuntos de API do Windows

Todas as versões do Windows compartilham uma base comum de componentes do sistema operacional (SO) que é chamada de do sistema operacional principal (em alguns contextos, essa base comum também é chamada de OneCore). Nos componentes principais do sistema operacional, as APIs do Win32 são organizadas em grupos funcionais chamados conjuntos de APIs.

O objetivo de um conjunto de APIs é fornecer uma separação arquitetônica da DLL do host na qual uma determinada API do Win32 é implementada e o contrato funcional ao qual a API pertence. O desacoplamento que os conjuntos de API fornecem entre implementação e contratos oferece muitas vantagens de engenharia para os desenvolvedores. Em particular, o uso de conjuntos de API em seu código pode melhorar a compatibilidade com dispositivos Windows.

Os conjuntos de API abordam especificamente os seguintes cenários:

• Embora toda a amplitude da API do Win32 seja suportada em PCs, apenas um subconjunto da API do Win32 está disponível em outros dispositivos Windows, como HoloLens, Xbox e outros dispositivos. O nome do conjunto de APIs fornece um mecanismo de consulta para detetar claramente se uma API está disponível em qualquer dispositivo.

• Algumas implementações de API do Win32 existem em DLLs com nomes diferentes em diferentes dispositivos Windows. O uso de nomes de conjuntos de API em vez de nomes de DLL ao detetar a disponibilidade da API e atrasar o carregamento de APIs fornece uma rota correta para a implementação, independentemente de onde a API é realmente implementada.

Para obter mais detalhes, consulte de operação do carregador de conjunto de API e Detetar disponibilidade do conjunto de APIs.

Conjuntos de API e dlls são a mesma coisa?

Não—um nome de conjunto de API é um alias virtual para um arquivo .dll físico. É uma técnica de ocultação de implementação, onde você, como chamador, não precisa saber exatamente qual módulo está hospedando as informações.

A técnica permite que os módulos sejam refatorados (separados, consolidados, renomeados e assim por diante) em diferentes versões e edições do Windows. E seus aplicativos ainda são vinculados e ainda são roteados para o código correto em tempo de execução.

Então, por que os conjuntos de API têm .dll em seus nomes? O motivo é a forma como o do carregador de DLL é implementado. O carregador é a parte do sistema operacional que carrega DLLs e/ou resolve referências a DLLs. E no front-end, o carregador requer que qualquer string passada para LoadLibrary seja encerrada com ".dll". Mas depois desse front-end, o carregador pode remover esse sufixo e consultar o banco de dados do conjunto de APIs com a cadeia de caracteres resultante.

LoadLibrary (e atrasar o carregamento) é bem-sucedido com um nome de conjunto de API (com o ".dll" nele); mas não há necessariamente um arquivo real com esse nome em qualquer lugar no PC.

Vinculando bibliotecas guarda-chuva

Para tornar mais fácil restringir seu código às APIs do Win32 que são suportadas no sistema operacional principal, fornecemos uma série de bibliotecas guarda-chuva. Por exemplo, uma biblioteca guarda-chuva chamada OneCore.lib fornece as exportações para o subconjunto de APIs do Win32 que são comuns a todos os dispositivos Windows.

Para obter mais detalhes, consulte bibliotecas guarda-chuva do Windows.

Nomes de contrato de conjunto de API

Os conjuntos de API são identificados por um nome de contrato forte que segue essas convenções padrão reconhecidas pelo carregador de biblioteca.

• O nome deve começar com a string api- ou ext-.
  • Os nomes que começam com api- representam APIs que existem em todas as edições do Windows que satisfazem os requisitos de versão da API.
  • Os nomes que começam com ext- representam APIs que podem não existir em todas as edições do Windows.
• O nome deve terminar com a sequência l<n>-<n>-<n>, onde n consiste em dígitos decimais.
• O corpo do nome pode ser caracteres alfanuméricos ou traços (-).
• O nome não diferencia maiúsculas de minúsculas.

Aqui estão alguns exemplos de nomes de contratos de conjunto de APIs:

• 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

Você pode usar um nome de conjunto de API no contexto de uma operação de carregador, como LoadLibrary ou P/Invoke em vez de um nome de módulo DLL para garantir uma rota correta para a implementação, independentemente de onde a API seja realmente implementada no dispositivo atual. No entanto, ao fazer isso, você deve acrescentar a cadeia de caracteres .dll no final do nome do contrato. Este é um requisito do carregador para funcionar corretamente, e não é considerado realmente uma parte do nome do contrato. Embora os nomes de contrato pareçam semelhantes aos nomes de DLL neste contexto, eles são fundamentalmente diferentes dos nomes de módulo DLL e não se referem diretamente a um arquivo no disco.

Exceto para anexar a cadeia de caracteres .dll em operações de carregador, os nomes de contrato do conjunto de API devem ser considerados um identificador imutável que corresponde a uma versão específica do contrato.

Identificando conjuntos de APIs para APIs do Win32

Para identificar se uma determinada API do Win32 pertence a um conjunto de APIs, examine a tabela de requisitos na documentação de referência da API. Se a API pertencer a um conjunto de APIs, a tabela de requisitos no artigo listará o nome do conjunto de APIs e a versão do Windows na qual a API foi introduzida pela primeira vez no conjunto de APIs. Para obter exemplos de APIs que pertencem a um conjunto de APIs, consulte estes artigos:

• AllowSetForegroundWindow
• FindWindowsEx
• GetClassFile

Nesta secção

• de operação do carregador de conjunto de API
• Detetar a disponibilidade do conjunto de APIs
• bibliotecas guarda-chuva do Windows