Podstawowe interfejsy API
Ważne
Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).
Środowisko uruchomieniowe aplikacji usługi Azure Sphere zawiera zestaw wspólnych bibliotek, które definiują podstawowe interfejsy API dostępne na potrzeby tworzenia aplikacji wysokiego poziomu: standardową bibliotekę języka C opartą na modelu POSIX, bibliotekę klienta HTTP opartą na programie curl oraz bibliotekę zestawu SDK języka C usługi Azure IoT.
W tym temacie opisano sposób określania, które podstawowe interfejsy API są zawarte w usłudze Azure Sphere i gdzie znaleźć dokumentację referencyjną dla podstawowych interfejsów API. Aby uzyskać informacje na temat interfejsów API specyficznych dla urządzenia, zobacz Interfejsy API usługi Applibs.
Nieobsługiwane funkcje
Ważne jest, aby używać tylko podstawowych funkcji interfejsu API, które są jawnie uwzględnione na powierzchni interfejsu API środowiska uruchomieniowego aplikacji usługi Azure Sphere. Aplikacje, które wywołują nieobsługiwane funkcje, mogą nie być zgodne z przyszłymi wersjami systemu operacyjnego usługi Azure Sphere i mogą powodować niestabilność urządzenia. Jeśli chcesz poprosić o pomoc techniczną dotyczącą dodatkowych funkcji, możesz użyć forum społeczności usługi Azure Sphere, aby wysłać żądanie.
Weryfikowanie funkcji
Aby określić, czy wywołanie funkcji jest obsługiwane, użyj funkcji autouzupełnianej z funkcją IntelliSense w programie Visual Studio lub sprawdź, czy znajduje się ona w plikach nagłówków zestawu SDK usługi Azure Sphere. Lokalizacje plików nagłówków dla każdej biblioteki są wymienione w poniższych sekcjach. Jeśli dodajemy lub modyfikujemy funkcje w tych bibliotekach, wyświetlimy je w tym temacie.
Standardowa biblioteka musl C
Usługa Azure Sphere jest dostarczana ze standardową biblioteką musl C (musl libc). Podobnie jak glibc, biblioteka musl libc jest standardową biblioteką C zgodną ze standardem POSIX. Różnice funkcjonalne między biblioteką musl libc i glibc są wymienione w witrynie typu wiki musl libc.
Spójność z zasadami zabezpieczeń i architekturą usługi Azure Sphere nie wszystkie funkcje POSIX są uwidocznione. Na przykład usługa Azure Sphere nie obsługuje funkcji open() ani fopen(). Cała obsługiwana powierzchnia interfejsu API biblioteki jest definiowana w plikach nagłówków zestawu SDK usługi Azure Sphere. Bieżąca implementacja może ulec zmianie w przyszłej wersji.
Dokumentacja interfejsu API: specyfikacja POSIX
Lokalizacja pliku nagłówka: Foldery Sysroots\API set\usr\include (system operacyjny Windows) lub Sysroots/API set/usr/include (system operacyjny Linux) katalogu instalacyjnego zestawu SDK usługi Azure Sphere.
Napiwek
Folder Sysroots\API set\usr\include\sys zawiera nagłówki dla interfejsów API niskiego poziomu, zależne od systemu, natomiast folder sysroots\API set\usr\include zawiera nagłówki dla ogólnych interfejsów API. Dotyczy to również systemu Linux. Zalecamy używanie ogólnych interfejsów API.
Najnowszą wersję zestawu SDK można pobrać tutaj.
Standardowe funkcje biblioteki języka C
Wykluczone są znaczące części następujących standardowych funkcji biblioteki języka C:
- Ścieżki systemu plików
- Obsługa terminalu
- Uwierzytelnianie i autoryzacja
- Funkcje Syscall
- System V (SysV)
fcntl
Cmd funkcji fcntl(int fd, int cmd, .../* arg */) funkcji uwidocznione i dostępne do użycia są następujące:
- F_GETFL — pobiera tryb dostępu do pliku i powiązane flagi stanu pliku.
- F_SETFL — ustawia flagi stanu pliku ustawione przez arg dla deskryptora plików.
- O_NONBLOCK — argument, który jest uwidoczniony specjalnie dla F_SETFL.
Aby uzyskać standardowe użycie funkcji fcntl(), zobacz bibliotekę MUSL.
Time_t typu C
W ramach przygotowań do przerzucania epoki UNIX w 2038 r. biblioteka musl libc w wersji 1.2 zawierała aktualizację z 32 bitów do 64 bitów, typu time_t C i wszystkich jej pochodnych. Aby uzyskać więcej informacji na temat tej aktualizacji, zobacz musl time64 Release Notes (Informacje o wersji musl time64).
Aplikacje skompilowane względem docelowego zestawu interfejsu API w wersji 20.10 (sysroot 7) i nowszego używają 64-bitowej time_twersji programu . Aplikacje utworzone przy użyciu wcześniejszych wersji zestawu SDK usługi Azure Sphere lub docelowego interfejsu API ustawionego 20.04 (sysroot 5) lub starszej wersji mogą nadal używać 32-bitowej definicji time_t. Nowe wersje systemu operacyjnego usługi Azure Sphere będą nadal zapewniać tym samym interfejsowi binarnemu aplikacji (ABI).
Nie ma to wpływu na kod aplikacji, który nie przyjmuje żadnych założeń dotyczących rozmiaru time_t wartości. Jednak kod aplikacji, który jawnie lub niejawnie zakłada, że time_t wartości są 32-bitowe (na przykład przez rzutowanie time_t wartości do uint32_t) muszą zostać przepisane, aby odzwierciedlić wersję 64-bitową.
Poniższy fragment kodu zakłada, że time_t jest to wartość 32-bitowa i spowoduje przepełnianie buforu w przypadku ponownego skompilowanego zestawu SDK 20.10 (sysroot 7) lub nowszego:
// 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
Poniższy poprawiony kod definiuje bufor tak samo jak time_t wartość, usuwając w ten sposób wszelkie założenia dotyczące rozmiaru time_telementu :
// 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));
Jeśli musisz nadal używać 32-bitowej wartości czasu, użyj time32_t typu w nowej wersji musl. Poniższy fragment kodu pokazuje, jak:
// 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));
biblioteka curl
Zestaw SDK usługi Azure Sphere zawiera podzbiór biblioteki transferu wielu protokołów libcurl. Za pomocą tego interfejsu API można przesyłać dane za pośrednictwem protokołu HTTP/HTTPS. Inne protokoły transferu nie są obsługiwane. Cała obsługiwana powierzchnia interfejsu API biblioteki jest definiowana w plikach nagłówków zestawu SDK usługi Azure Sphere.
Dokumentacja interfejsu API: witryna internetowa libcurl
Lokalizacja pliku nagłówka: Sysroots\API set\usr\include\curl (Windows OS) folder lub Sysroots/API set/usr/include/curl (Linux OS) katalogu instalacyjnego zestawu SDK usługi Azure Sphere.