Översikt över Azure Sphere-bas-API:er

Artikel
07/08/2024

Azure Sphere Application Runtime innehåller en uppsättning vanliga bibliotek som definierar de bas-API:er som är tillgängliga för programutveckling på hög nivå: ett POSIX-baserat C-standardbibliotek, ett curlbaserat HTTP-klientbibliotek och ett Azure IoT C SDK-bibliotek.

I det här avsnittet beskrivs hur du avgör vilka bas-API:er som ingår i Azure Sphere och var du hittar referensdokumentation för bas-API:erna. Information om enhetsspecifika API:er finns i Applibs-API:er.

Funktioner som inte stöds

Det är viktigt att endast använda grundläggande API-funktioner som uttryckligen ingår i API-ytan i Azure Sphere Application Runtime. Program som anropar funktioner som inte stöds kanske inte är kompatibla med framtida versioner av Azure Sphere-operativsystemet och kan orsaka instabilitet på enheten. Om du vill begära support för ytterligare funktioner kan du använda Azure Sphere Community-forumet för att göra begäran.

Verifiera funktioner

Om du vill avgöra om ett funktionsanrop stöds använder du komplettera automatiskt med IntelliSense i Visual Studio eller kontrollerar att det ingår i Azure Sphere SDK-huvudfilerna. Platserna för huvudfilerna för varje bibliotek visas i avsnitten nedan. Om vi lägger till eller ändrar funktioner i dessa bibliotek listar vi dem i det här avsnittet.

musl C-standardbibliotek

Azure Sphere levereras med standardbiblioteket musl C (musl libc). Liksom glibc är musl libc ett POSIX-kompatibelt standard C-bibliotek. Funktionella skillnader mellan musl libc och glibc visas i musl libc wiki.

I enlighet med Säkerhetsprincip och arkitektur för Azure Sphere exponeras inte alla POSIX-funktioner. Azure Sphere stöder till exempel inte funktionerna open() eller fopen(). Hela API-ytan som stöds i biblioteket definieras i Azure Sphere SDK-huvudfilerna. Den aktuella implementeringen kan ändras i en framtida version.

API-referens: POSIX-specifikation

Plats för rubrikfil: Sysroots\API set\usr\include (Windows OS) eller Sysroots/API set/usr/include (Linux OS) mappar i din Azure Sphere SDK-installationskatalog.

Dricks

Mappen Sysroots\API set\usr\include\sys innehåller rubriker för systemberoende API:er på låg nivå, medan mappen Sysroots\API set\usr\include innehåller rubriker för allmänna API:er. Detta gäller även för Linux. Vi rekommenderar att du använder de allmänna API:erna.

Du kan ladda ned den senaste SDK:en här.

C-standardbiblioteksfunktioner

Betydande delar av följande C-standardbiblioteksfunktioner undantas:

Sökvägar för filsystem
Terminalstöd
Autentisering och auktorisering
Syscall-funktioner
System V (SysV)

fcntl

Funktions-CMD :erna fcntl(int fd, int cmd, .../* arg */) som exponeras och är tillgängliga för användning är följande:

F_GETFL – Hämtar filåtkomstläget och de relaterade filstatusflaggorna.
F_SETFL – Anger filstatusflaggor, som anges av arg, för en filbeskrivning.
O_NONBLOCK – Argument som exponeras specifikt för F_SETFL.

Standardanvändning av funktionen fcntl() finns i MUSL-biblioteket.

C-typ time_t

Inför UNIX-epokens rollover 2038 inkluderade musl libc version 1.2 en uppdatering, från 32 bitar till 64 bitar, av C-typ time_t och alla dess derivat. Mer information om den här uppdateringen finns i viktig information om musl time64.

Program som kompilerats mot 20.10-mål-API:et (sysroot 7) och senare använder 64-bitarsversionen av time_t. Program som har skapats med tidigare versioner av Azure Sphere SDK eller mål-API:et 20.04 (sysroot 5) eller tidigare kan fortsätta att använda en 32-bitars definition av time_t. Nya versioner av Azure Sphere OS fortsätter att tillhandahålla samma programbinärt gränssnitt (ABI) till dessa program.

Programkod som inte gör några antaganden om värdets time_t storlek påverkas inte. Programkod som uttryckligen eller implicit förutsätter att time_t värden är 32-bitars (till exempel genom att konvertera ett time_t värde till en uint32_t) måste dock skrivas om för att återspegla 64-bitarsversionen.

Följande kodfragment förutsätter att det time_t är ett 32-bitarsvärde och orsakar en buffertöverskridning om det omkompileras med SDK:t 20.10 (sysroot 7) eller senare:

// 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

Följande korrigerade kod definierar bufferten till samma storlek som time_t värdet, vilket tar bort eventuella antaganden om storleken på 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));

Om du behöver fortsätta använda ett 32-bitars tidsvärde använder du time32_t typen i den nya versionen av musl. Följande kodfragment visar hur:

// 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));

curl-bibliotek

Azure Sphere SDK innehåller en delmängd av biblioteket för överföring av flera protokoll i libcurl. Du kan använda det här API:et för att överföra data via HTTP/HTTPS. De andra överföringsprotokollen stöds inte. Hela API-ytan som stöds i biblioteket definieras i Azure Sphere SDK-huvudfilerna.

API-referens: libcurl-webbplats

Plats för rubrikfil: Mappen Sysroots\API set\usr\include\curl (Windows OS) eller Sysroots/API set/usr/include/curl (Linux OS) i Installationskatalogen för Azure Sphere SDK.

Dela via