Visão geral das APIs do Azure Sphere Base
O Azure Sphere Application Runtime inclui um conjunto de bibliotecas comuns que definem as APIs base que estão disponíveis para o desenvolvimento de aplicativos de alto nível: uma biblioteca padrão C baseada em POSIX, uma biblioteca de cliente HTTP baseada em curl e uma biblioteca Azure IoT C SDK.
Este tópico descreve como determinar quais APIs base estão incluídas no Azure Sphere e onde encontrar a documentação de referência para as APIs base. Para obter informações sobre APIs específicas do dispositivo, consulte Applibs APIs.
Funções não suportadas
É importante usar apenas funções de API base que estão explicitamente incluídas na superfície da API do Azure Sphere Application Runtime. Os aplicativos que chamam funções sem suporte podem não ser compatíveis com versões futuras do sistema operacional Azure Sphere e podem causar instabilidade no dispositivo. Se quiser solicitar suporte para funções adicionais, você pode usar o fórum da Comunidade do Azure Sphere para fazer a solicitação.
Verificar funções
Para determinar se uma chamada de função é suportada, use o preenchimento automático com o IntelliSense no Visual Studio ou verifique se ela está incluída 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 abaixo. Se adicionarmos ou modificarmos funções nessas bibliotecas, iremos listá-las 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 suporta as funções open() ou fopen(). Toda a superfície de API com suporte da biblioteca é definida nos arquivos de cabeçalho do SDK do Azure Sphere. A implementação atual pode mudar em uma versão futura.
Referência API: especificação POSIX
Local do arquivo de cabeçalho: pastas Sysroots\API set\usr\include (Windows OS) ou Sysroots/API set/usr/include (Linux OS) do diretório de instalação do SDK do Azure Sphere.
Gorjeta
A pasta Sysroots\API set\usr\include\sys contém cabeçalhos para APIs de baixo nível dependentes do sistema, 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.
Recursos da biblioteca padrão C
Partes significativas dos seguintes recursos de biblioteca padrão C são excluídas:
- Caminhos do sistema de arquivos
- Suporte de terminal
- Autenticação e autorização
- Funções Syscall
- Sistema V (SysV)
FCNTL
A função fcntl(int fd, int cmd, .../* arg */) CMDs expostos e disponíveis para uso são os seguintes:
- F_GETFL - Recupera o modo de acesso ao arquivo e os sinalizadores de status do arquivo relacionados.
- F_SETFL - Define sinalizadores de status de arquivo, conforme definido pelo arg, para um descritor de arquivo.
- O_NONBLOCK - Argumento que é exposto especificamente para F_SETFL.
Para o uso padrão da função fcntl(), consulte a biblioteca MUSL.
C tipo time_t
Em preparação para o rollover da é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 esta atualização, consulte musl time64 Release Notes.
Os aplicativos compilados em relação ao 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 anteriores podem continuar a usar uma definição de 32 bits de time_t. As novas versões do SO Azure Sphere continuarão a fornecer a mesma Interface Binária de Aplicação (ABI) a estas aplicações.
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 para um uint32_t) deve ser reescrito para refletir a versão de 64 bits.
O trecho a seguir assume 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 sendo do 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 trecho 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 multiprotocolo libcurl. Você pode usar essa API para transferir dados por HTTP/HTTPS. Os outros protocolos de transferência não são suportados. Toda a superfície de API com suporte da biblioteca é definida nos arquivos de cabeçalho do SDK do Azure Sphere.
Referência API: site libcurl
Local do arquivo de cabeçalho: pasta Sysroots\API set\usr\include\curl (Windows OS) ou pasta Sysroots/API set/usr/include/curl (Linux OS) do diretório de instalação do SDK do Azure Sphere.