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 é proporcionar uma separação arquitetónica entre a DLL do host em que uma dada API Win32 está 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 abrangência da API Win32 seja suportada em PCs, apenas um subconjunto da API Win32 está disponível noutros dispositivos Windows como HoloLens, XBOX e outros dispositivos. Um nome de conjunto de API dá-te uma informação estável para perguntar, para que a tua aplicação possa detetar em tempo de execução se existe uma funcionalidade disponível no dispositivo atual. A própria consulta é realizada pela função IsApiSetImplemented .

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

Para mais detalhes, consulte Funcionamento do carregador de conjuntos de APIs e Detetar a disponibilidade de conjuntos de APIs.

Os conjuntos de APIs e as DLLs são a mesma coisa?

Não—um nome de conjunto de API identifica um contrato, não um ficheiro. Em tempo de execução, o loader resolve esse contrato através do esquema do conjunto de APIs no dispositivo atual e encaminha a referência para a DLL que hospeda a implementação. É 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 as tuas aplicações continuam a ligar-se, e continuam a ser encaminhadas 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 carregador de DLL é implementado. O loader é a parte do sistema operativo que carrega DLLs e/ou resolve referências a DLLs, e identifica o que carregar por um nome de módulo escrito da mesma forma que os nomes dos ficheiros são escritos numa tabela de importação. Os nomes dos conjuntos de API seguem a mesma convenção para que se encaixem no mesmo lugar.

O carregador reconhece um nome que começa por api- ou ext- e encaminha-o para o ambiente de execução do conjunto de APIs, uma extensão do carregador que resolve contratos com base no esquema. A partir desse ponto, o nome é analisado por regras de nomenclatura definidas pela API em vez de um nome de ficheiro, por isso o .dll sufixo não faz parte do nome do contrato a ser resolvido.

Pode passar um nome de conjunto da API para LoadLibrary ou utilizá-lo como alvo de carregamento diferido. A operação é bem-sucedida quando o esquema no dispositivo atual mapeia esse contrato para um host válido; não existe necessariamente um ficheiro real com esse nome em qualquer parte do PC. Se o contrato não estiver mapeado no dispositivo atual, o carregamento direto com LoadLibrary falhará. Uma referência carregada por atraso comporta-se de forma diferente: o processo continua a carregar, e a ausência surge mais tarde, quando a API é chamada.

De qualquer forma, uma ligação ou carga bem-sucedida não é, por si só, prova de que existe uma implementação. Para determinar isso, veja Detetar disponibilidade de conjuntos de API.

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. Uma biblioteca guarda-chuva permite-lhe ligar uma única biblioteca em vez de identificar a biblioteca de importação individual para cada API que chama.

Para mais detalhes e para escolher a biblioteca guarda-chuva que corresponde ao que pretende, consulte bibliotecas guarda-chuva do Windows.

Nomes de contrato do conjunto de APIs

Os conjuntos de API são identificados por um nome de contrato que segue as convenções reconhecidas pelo carregador de bibliotecas.

Todos os nomes dos contratos partilham estas convenções:

• O nome começa com a string api- ou ext-.
• O corpo do nome pode conter caracteres alfanuméricos ou hífens (-). Uma tilde (~) aparece apenas como separador antes do nome de um grupo.
• O nome não faz distinção entre maiúsculas e minúsculas.

Existem duas formas de nome contratual em uso, e pode encontrar qualquer uma delas.

Um nome de contrato versionado termina com a sequência l<n-n-n<>><>, onde n consiste em dígitos decimais — por exemplo, ext-ms-win-core-samplefeature-l1-1-0. Os números finais identificam uma versão específica do contrato, e um nome nesta forma deve ser considerado um identificador imutável dessa versão.

Um alias contratual não tem versão—por exemplo, api-win-core-samplefeature. Identifica o contrato em si, em vez de uma única versão do mesmo. Quando um contrato organiza as suas capacidades individualmente disponíveis em grupos nomeados, um grupo é abordado acrescentando o nome do grupo ao alias do contrato, separado por uma tilde: api-win-core-samplefeature~AdvancedOperations.

Os samplefeature nomes usados aqui são nomes ilustrativos para um componente fictício do Windows.

Os prefixos API e ext-

O prefixo é uma convenção de nomenclatura. Originalmente, destinava-se a distinguir contratos presentes em todas as edições qualificatórias (api-) de contratos que possam estar ausentes (ext-). Essa distinção não foi aplicada de forma consistente, e o papel de um contrato pode mudar ao longo do tempo sem que o contrato seja renomeado.

O carregador não atribui qualquer significado ao prefixo; resolve nomes de api e ext pelas mesmas regras. Não infiras disponibilidade a partir do prefixo. Consulte-o em vez disso — veja Detetar a disponibilidade do conjunto de APIs.

Utilização de um nome contratual

Dois tipos diferentes de operação recebem um nome de contrato.

Operações de carregador — como LoadLibrary ou P/Invoke — assumem o nome do contrato no mesmo local onde normalmente aparece o nome do módulo DLL. Um anexo .dll é convencional nesse contexto, mas não é exigido pela resolução de nomes de conjunto da API nem faz parte do nome do contrato. Use um nome de contrato em vez de um nome físico de módulo DLL para garantir uma rota correta para a implementação, independentemente de onde a API esteja realmente implementada no dispositivo atual. Não precisa de haver um ficheiro com esse nome de contrato no disco.

Exemplos de consultas de disponibilidade omitem convencionalmente o sufixo.dll e usam o formulário que corresponde à forma como a API é endereçada:

Um nome de grupo não pode ser combinado com um nome de contrato versionado.

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
• FindWindowEx
• GetClassFile

Se o cabeçalho da API fornecer uma Is<APIName>Present função auxiliar, prefira esse auxiliar quando testar a disponibilidade. Já contém o nome correto para o conjunto ou grupo de APIs que transporta a API. Para mais informações, consulte Detetar disponibilidade de conjuntos de API.

Nesta secção

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