Visão geral das APIs base do Azure Sphere

  • Artigo

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

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 APIs do Applibs.

Funções sem suporte

É importante usar apenas funções de API base que estão explicitamente incluídas na superfície da API do Azure Sphere Application Runtime. 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 Azure Sphere Community para fazer a solicitação.

Verificar funções

Para determinar se há suporte para uma chamada de função, use a conclusão automática 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, as listaremos neste tópico.

biblioteca padrão musl C

O Azure Sphere é enviado com a biblioteca padrão musl C (musl libc). Assim como o glibc, o musl libc é uma biblioteca C padrão compatível com POSIX. As diferenças funcionais entre o libc musl e o glibc são listadas no wiki musl libc.

Consistente com a política de segurança e a arquitetura 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(). 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 ser alterada em uma versão futura.

Referência da API:especificação POSIX

Local do arquivo de cabeçalho: 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.

Ponta

A pasta Sysroots\API set\usr\include\sys contém cabeçalhos para APIs dependentes do sistema de baixo nível, enquanto a pasta Sysroots\API set\usr\include contém cabeçalhos para APIs gerais. Isso também é verdadeiro 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 da biblioteca padrão C são excluídas:

  • Caminhos do sistema de arquivos
  • Suporte ao terminal
  • Autenticação e autorização
  • Funções Syscall
  • Sistema V (SysV)

Fcntl

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 o arquivo relacionado status sinalizadores.
  • 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 uso padrão da função fcntl(), consulte a biblioteca MUSL.

Time_t de tipo C

Em preparação para a distribuição da época unix em 2038, o 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 essa atualização, confira Notas de versão do musl time64.

Os aplicativos compilados em relação ao conjunto de API de destino 20.10 (sysroot 7) e posteriormente usam a versão de 64 bits do time_t. Aplicativos criados usando versões anteriores do SDK do Azure Sphere ou do conjunto de API de destino 20.04 (sysroot 5) ou anteriores podem continuar a usar uma definição de 32 bits de time_t. Novas versões do sistema operacional do Azure Sphere continuarão fornecendo 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 será afetado. No entanto, o código do aplicativo que pressupõe explicitamente ou implicitamente que time_t os valores são de 32 bits (por exemplo, lançando um time_t valor para um uint32_t) deve ser reescrito para refletir a versão de 64 bits.

O snippet a seguir pressupõe que time_t seja um valor de 32 bits e causará uma sobrecarga 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 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 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 de vários protocolos libcurl. Você pode usar essa API para transferir dados por HTTP/HTTPS. Os outros protocolos de transferência não têm suporte. Toda a superfície de API com suporte da biblioteca é definida nos arquivos de cabeçalho do SDK do Azure Sphere.

Referência da API:site libcurl

Local do arquivo de cabeçalho: Pasta Sysroots\API set\usr\include\curl (Sistema Operacional Windows) ou Sysroots/API set/usr/include/curl (sistema operacional Linux) do diretório de instalação do SDK do Azure Sphere.

Consulte também