Visão geral das APIs base do Azure Sphere
O Tempo de Execução do Aplicativo do Azure Sphere inclui um conjunto de bibliotecas comuns que definem as APIs de base disponíveis para o desenvolvimento de aplicativos de alto nível: uma biblioteca padrão C baseada em POSIX, uma biblioteca de cliente HTTP com base em curl e uma biblioteca do SDK C do Azure IoT.
Este tópico descreve como determinar quais APIs de base estão incluídas no Azure Sphere e onde encontrar a documentação de referência para as APIs de base. Para obter informações sobre APIs específicas do dispositivo, confira APIs do Applibs.
Funções sem suporte
É importante utilizar somente funções da API base que estão explicitamente incluídas na superfície de API do runtime de aplicativo do Azure Sphere. Os aplicativos que chamam funções sem suporte podem não ser compatíveis com versões futuras do sistema operacional do Azure Sphere e podem causar instabilidade no dispositivo. Se você quiser solicitar suporte para funções adicionais, poderá usar o fórum da Comunidade do Azure Sphere para fazer a solicitação.
Verifique as funções
Para determinar se uma chamada de função tem suporte, usar o preenchimento automático com o IntelliSense no Visual Studio ou verificar se ele está incluído nos arquivos de cabeçalho do SDK do Azure Sphere. Os locais dos arquivos de cabeçalho para cada biblioteca estão listados nas seções a seguir. Se podemos adicionar ou modificar funções dessas bibliotecas, vamos listá-los neste tópico.
biblioteca padrão musl C
O Azure Sphere é fornecido com a biblioteca padrão musl C (musl libc). Como a glibc, musl libc é uma biblioteca C padrão compatível com POSIX. As diferenças funcionais entre musl libc e glibc estão listadas no wiki musl libc.
Consistente com a política e a arquitetura de segurança do Azure Sphere, nem todas as funções POSIX são expostas. Por exemplo, o Azure Sphere não dá suporte às funções open() ou fopen(). A superfície de API com suporte inteira da biblioteca é definida nos arquivos de cabeçalho do SDK do Azure Sphere. A implementação atual poderá ser alterada em uma versão futura.
Referência API: especificação POSIX
Local do arquivo de cabeçalho: pastas Sysroots\API set\usr\include (sistema operacional Windows) ou Sysroots/API set/usr/include (sistema operacional Linux) do diretório de instalação do SDK do Azure Sphere.
Dica
A pasta Sysroots\API set\usr\include\sys contém cabeçalhos para APIs dependentes do sistema de baixo nível, enquanto a pasta pai Sysroots\API set\usr\include contém cabeçalhos para APIs gerais. Isso também é verdade para o Linux. Recomendamos que você use as APIs gerais.
Você pode baixar o SDK mais recente aqui.
Uma biblioteca C padrão inclui
Partes significativas dos recursos de biblioteca padrão C a seguir são excluídas:
- Caminhos do sistema de arquivos
- Suporte de terminal
- Autenticação e autorização
- Funções de syscall
- Sistema V (SysV)
maldito
Os cmds da função fcntl(int fd, int cmd, .../* arg */) expostos e disponíveis para uso são os seguintes:
- F_GETFL - Recupera o modo de acesso ao arquivo e os sinalizadores de status de arquivo relacionados.
- F_SETFL - Define sinalizadores de status de arquivo, conforme definido pelo arg, para um descritor de arquivo.
- O_NONBLOCK - Argumento exposto especificamente para F_SETFL.
Para uso padrão da função fcntl(), consulte a biblioteca MUSL.
C tipo time_t
Em preparação para a mudança de época do UNIX em 2038, a versão 1.2 do musl libc incluiu uma atualização, de 32 bits para 64 bits, do tipo time_t C e todos os seus derivados. Para obter mais informações sobre essa atualização, consulte as Notas de versão do musl time64.
Os aplicativos compilados no conjunto de APIs de destino 20.10 (sysroot 7) e posteriores usam a versão de 64 bits do time_t. Os aplicativos que foram criados usando versões anteriores do SDK do Azure Sphere ou do conjunto de APIs de destino 20.04 (sysroot 5) ou anterior podem continuar a usar uma definição de 32 bits de time_t. Novas versões do sistema operacional do Azure Sphere continuarão a fornecer a mesma ABI (Interface Binária de Aplicativo) para esses aplicativos.
O código do aplicativo que não faz suposições sobre o tamanho de um time_t valor não é afetado. No entanto, o código do aplicativo que assume explícita ou implicitamente que time_t os valores são de 32 bits (por exemplo, convertendo um time_t valor em um uint32_t) deve ser reescrito para refletir a versão de 64 bits.
O snippet a seguir pressupõe que time_t é um valor de 32 bits e causará uma saturação de buffer se recompilado com o SDK 20.10 (sysroot 7) ou posterior:
// Incorrect code that assumes a 32-bit time_t value
time_t t = time(NULL);
char buffer[4];
memcpy(buffer, &t, sizeof(t)); // <-- buffer overrun when time_t is 64 bits
O código corrigido a seguir define o buffer como tendo o mesmo tamanho que o time_t valor, removendo assim quaisquer suposições sobre o tamanho de time_t:
// Corrected version of the code. It does not hard-code the size of time_t
time_t t; // time_t represents the 64-bit struct.
char buffer[sizeof(time_t)]; // Buffer size is based on the actual size of time_t
memcpy(buffer, &t, sizeof(t));
Se você precisar continuar usando um valor de tempo de 32 bits, use o time32_t tipo na nova versão do musl. O snippet de código a seguir mostra como:
// Corrected version of the code for cases where 32-bit time_t is needed
time32_t t = /* ... initialize 32-bit value ... */;
char buffer[sizeof(time32_t)];
memcpy(buffer, &t, sizeof(t));
biblioteca curl
O SDK do Azure Sphere inclui um subconjunto da biblioteca de transferência do protocolo de vários libcurl. Você pode usar essa API para transferir dados por HTTP/HTTPS. Não há suporte para outros protocolos de transferência. A superfície de API com suporte inteira da biblioteca é definida nos arquivos de cabeçalho do SDK do Azure Sphere.
Referência da API: site do libcurl
Local do arquivo de cabeçalho: pasta Sysroots\API set\usr\include\curl (sistema operacional Windows) ou pasta Sysroots/API set/usr/include/curl (sistema operacional Linux) do diretório de instalação do SDK do Azure Sphere.