Базовые API
Внимание
Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).
Базовые интерфейсы API, предоставляемые средой выполнения приложений Azure Sphere, включают в себя набор общих библиотек, которые определяют базовые API, доступные для разработки высокоуровневых приложений: стандартную библиотеку C на основе POSIX, клиентскую библиотеку HTTP на основе curl и библиотеку пакета SDK Azure IoT для C.
В этом разделе описывается как определить, какие базовые API включены в Azure Sphere, и где найти справочную документацию для базовых API. Дополнительные сведения об API для конкретных устройств см. в разделе Applibs API.
Неподдерживаемые функции
Важно использовать только базовые функции API, которые явно включены в поверхность API среды выполнения приложений Azure Sphere. Приложения, которые вызывают неподдерживаемые функции, могут оказаться несовместимыми с будущими выпусками операционной системы Azure Sphere, что может привести к нестабильной работе устройств. Если вы хотите запросить поддержку дополнительных функций, вы можете использовать форум сообщества Azure Sphere для выполнения запроса.
Проверка функций
Чтобы определить, поддерживается ли вызов функции, используйте автозаполнение с помощью IntelliSense в Visual Studio или убедитесь, что эта функция включена в файлы заголовков пакета SDK для Azure Sphere. Расположение файлов заголовков для каждой библиотеки указано в следующих разделах. Если мы добавим или изменим функции в этих библиотеках, то укажем их в этом разделе.
стандартная библиотека musl C
Azure Sphere поставляется со стандартной библиотекой musl C (musl libc). Как и glibc, musl libc является стандартной библиотекой C, совместимой с POSIX. Функциональные различия между musl libc и glibc перечислены в вики-сайте musl libc.
В соответствии с политикой безопасности и архитектурой Azure Sphere предоставляются не все функции POSIX. Например, Azure Sphere не поддерживает функции open() или fopen(). Вся поддерживаемая поверхность API библиотеки определена в файлах заголовков пакета SDK для Azure Sphere. Текущая реализация может измениться в следующем выпуске.
Справочник по API: спецификация POSIX
Расположение файла заголовка: sysroots\API set\usr\include (Windows OS) или Sysroots/API set/usr/include (Linux OS) каталога установки пакета SDK Для Azure Sphere.
Совет
Папка Sysroots\API set\usr\include\sys содержит заголовки для низкоуровневых, зависимых от системы API, тогда как набор Sysroots\API set\usr\include содержит заголовки для общих API. Это аналогично для Linux. Рекомендуется использовать общие API.
Вы можете скачать последний пакет SDK здесь.
Функции стандартной библиотеки C
Значительная часть приведенных ниже функций стандартной библиотеки C исключена:
- Пути к файловой системе
- Поддержка терминала
- Проверка подлинности и авторизация
- Функции Syscall
- System V (SysV).
fcntl
Доступные и доступные для использования cmd функции fcntl(int fd, int cmd, .../* arg */) и доступные для использования:
- F_GETFL. Извлекает режим доступа к файлам и связанные флаги состояния файла.
- F_SETFL — задает флаги состояния файла, заданные arg, для дескриптора файла.
- O_NONBLOCK — аргумент, предоставляемый специально для F_SETFL.
Стандартное использование функции fcntl() см . в библиотеке MUSL.
Тип C time_t
В подготовке к переходу эпохи UNIX в 2038 году musl libc версии 1.2 включал обновление с 32-разрядных до 64-разрядных версий типа C time_t и всех его производных. Дополнительные сведения об этом обновлении см . в заметках о выпуске musl time64.
Приложения, скомпилированные в целевом наборе API 20.10 (sysroot 7), а затем используют 64-разрядную версию time_t. Приложения, созданные с использованием более ранних версий пакета SDK Azure Sphere или целевого API 20.04 (sysroot 5) или более ранних версий, могут продолжать использовать 32-разрядное определение time_t. Новые версии ОС Azure Sphere будут продолжать предоставлять тот же двоичный интерфейс приложения (ABI) для этих приложений.
Код приложения, который не предполагает размер time_t значения, не затрагивается. Однако код приложения, который явно или неявно предполагает, что time_t значения являются 32-разрядными (например, путем приведения time_t значения к uint32_t) необходимо переписать, чтобы отразить 64-разрядную версию.
В следующем фрагменте предполагается, что time_t это 32-разрядное значение и приведет к переполнению буфера при повторной компиляции с пакетом SDK 20.10 (sysroot 7) или более поздней версии:
// 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
Следующий исправленный код определяет буфер для того же размера, что time_t и значение, что позволяет удалить все предположения о размере 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));
Если вам нужно продолжать использовать 32-разрядное значение времени, используйте time32_t тип в новой версии musl. В следующем фрагменте кода показано, как:
// 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
Пакет SDK для Azure Sphere включает в себя подмножество компонентов библиотеки мультипротокольной передачи libcurl. Этот API можно использовать для передачи данных по протоколу HTTP/HTTPS. Другие протоколы передачи не поддерживаются. Вся поддерживаемая поверхность API библиотеки определена в файлах заголовков пакета SDK для Azure Sphere.
Справочные материалы по API: веб-сайт libcurl
Расположение файла заголовка: папка Sysroots\API set\usr\include\curl (Windows OS) или sysroots/API set/usr/include/curl (Linux OS) каталога установки пакета SDK Для Azure Sphere.