Descrição geral das APIs Base do Azure Sphere

  • Artigo

O Runtime de Aplicações do Azure Sphere inclui um conjunto de bibliotecas comuns que definem as APIs base que estão disponíveis para desenvolvimento de aplicações de alto nível: uma biblioteca padrão C baseada em POSIX, uma biblioteca de cliente HTTP baseada em curl e uma biblioteca do SDK C do Azure IoT.

Este tópico descreve como determinar que 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, veja APIs de Applibs.

Funções não suportadas

É importante utilizar apenas funções de API base que estão explicitamente incluídas na superfície da API do Runtime de Aplicações do Azure Sphere. As aplicações que chamam funções não suportadas podem não ser compatíveis com versões futuras do SO do Azure Sphere e podem causar instabilidade no dispositivo. Se quiser pedir suporte para funções adicionais, pode utilizar o fórum da Comunidade do Azure Sphere para fazer o pedido.

Verificar funções

Para determinar se uma chamada de função é suportada, utilize a conclusão automática com o IntelliSense no Visual Studio ou verifique se está incluída nos ficheiros de cabeçalho do SDK do Azure Sphere. As localizações dos ficheiros de cabeçalho de cada biblioteca estão listadas nas secções abaixo. Se adicionarmos ou modificarmos funções nestas 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). Tal como o glibc, o 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 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 suportada da biblioteca é definida nos ficheiros de cabeçalho do SDK do Azure Sphere. A implementação atual pode mudar numa versão futura.

Referência da API:especificação POSIX

Localização do ficheiro de cabeçalho: Sysroots\API set\usr\include (SO Windows) ou pastas Sysroots/API set/usr/include (SO Linux) do diretório de instalação do SDK do Azure Sphere.

Sugestão

A pasta Sysroots\API set\usr\include\sys contém cabeçalhos para APIs dependentes do sistema de baixo nível, enquanto a pasta principal Sysroots\API set\usr\include contém cabeçalhos para APIs gerais. Isto também se aplica ao Linux. Recomendamos que utilize as APIs gerais.

Pode transferir o SDK mais recente aqui.

Funcionalidades de biblioteca padrão C

Foram excluídas partes significativas das seguintes funcionalidades de biblioteca padrão C:

  • Caminhos do sistema de ficheiros
  • Suporte para terminais
  • Autenticação e autorização
  • Funções Syscall
  • System V (SysV)

fcntl

Os CMDs da função fcntl(int fd, int cmd, .../* arg */) expostos e disponíveis para utilização são os seguintes:

  • F_GETFL – obtém o modo de acesso a ficheiros e os sinalizadores de estado do ficheiro relacionados.
  • F_SETFL - Define os sinalizadores de estado do ficheiro, conforme definido pelo arg, para um descritor de ficheiros.
  • O_NONBLOCK - argumento que é exposto especificamente para F_SETFL.

Para obter a utilização padrão da função fcntl( ), veja a biblioteca MUSL.

Tipo C time_t

Em preparação para o rollover de época UNIX em 2038, musl libc versão 1.2 incluiu uma atualização, de 32 bits a 64 bits, do tipo time_t C e todos os seus derivados. Para obter mais informações sobre esta atualização, veja Musl time64 Release Notes (Notas de Versão musl time64).

As aplicações compiladas com o conjunto de API de destino 20.10 (sysroot 7) e posteriores utilizam a versão de 64 bits do time_t. As aplicações criadas com versões anteriores do SDK do Azure Sphere ou do conjunto de API de destino 20.04 (sysroot 5) ou anterior podem continuar a utilizar uma definição de 32 bits de time_t. As novas versões do SO do Azure Sphere continuarão a fornecer a mesma Interface Binária de Aplicação (ABI) a estas aplicações.

O código da aplicação que não faz suposições sobre o tamanho de um time_t valor não é afetado. No entanto, o código da aplicação que assume explicitamente ou implicitamente que time_t os valores são de 32 bits (por exemplo, ao converter um valor num time_t uint32_t) tem de ser reescrito para refletir a versão de 64 bits.

O fragmento seguinte pressupõe que time_t é um valor de 32 bits e causará uma ultrapassagem da memória intermédia se for recompilado com o SDK de 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 seguinte código corrigido define a memória intermédia para ter o mesmo tamanho que o time_t valor, removendo assim quaisquer pressupostos 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 precisar de continuar a utilizar um valor de tempo de 32 bits, utilize o time32_t tipo na nova versão do musl. O fragmento de código seguinte 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 de vários protocolos libcurl. Pode utilizar esta API para transferir dados através de HTTP/HTTPS. Os outros protocolos de transferência não são suportados. Toda a superfície de API suportada da biblioteca é definida nos ficheiros de cabeçalho do SDK do Azure Sphere.

Referência da API:site libcurl

Localização do ficheiro de cabeçalho: Pasta Sysroots\API set\usr\include\curl (SO Windows) ou pasta Sysroots/API set/usr/include/curl (SO Linux) do diretório de instalação do SDK do Azure Sphere.

Consulte também