基本 API

项目
09/27/2024

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure Sphere 应用程序运行时包括一组公共库，用于定义可用于高级应用程序开发的基本 API：基于 POSIX 的 C 标准库、基于 curl 的 HTTP 客户端库和 Azure IoT C SDK 库。

本主题介绍如何确定 Azure Sphere 中包含的基本 API，以及可以在何处找到基本 API 的参考文档。有关特定于设备的 API 的信息，请参见 Applibs API。

不支持的函数

请务必仅使用 Azure Sphere 应用程序运行时的 API 接口中明确包含的基本 API 函数。调用不受支持的函数的应用程序可能与后续版本的 Azure Sphere OS 不兼容，并可能导致设备不稳定。如果想要请求对其他函数的支持，可以使用 Azure Sphere 社区论坛发出请求。

验证函数

若要确定是否支持某个函数调用，请在 Visual Studio 中结合使用“自动完成”和 IntelliSense 或验证它是否包含在 Azure Sphere SDK 头文件中。每个库的头文件位置在以下部分中列出。如果我们在这些库中添加或修改函数，我们将在本主题中将其列出。

musl C 标准库

Azure Sphere 附带 musl C 标准库（musl libc）。与 glibc 一样，musl libc 是符合 POSIX 的标准 C 库。 musl libc 和 glibc 之间的功能差异列在 musl libc wiki 中。

与 Azure Sphere 安全策略和体系结构一致，并非所有 POSIX 函数都公开。例如，Azure Sphere 不支持 open（）或 fopen（）函数。库的整个受支持的 API 接口是在 Azure Sphere SDK 头文件中定义的。当前实现在将来的版本中可能发生变化。

API 参考：POSIX 规范

头文件位置： Azure Sphere SDK 安装目录的 Sysroots\API set\usr\include （Windows OS）或 Sysroots/API set/usr/include （Linux OS）文件夹。

提示

Sysroots\API set\usr\include\sys 文件夹包含低级别依赖系统 API 的标头，而 Sysroots\API set\usr\include 父文件夹包含常规 API 的标头。这同样适用于 Linux。建议使用常规 API。

可以在此处下载最新的 SDK。

C 标准库功能

不包含以下 C 标准库功能的重要部分：

文件系统路径
终端支持
身份验证和授权
Syscall 函数
系统 V (SysV)

fcntl

公开并可供使用的 fcntl（int fd、int cmd、.../* arg */） 函数 CMD 如下：

F_GETFL - 检索文件访问模式和相关文件状态标志。
F_SETFL - 设置文件描述符的文件状态标志（按 arg 设置）。
O_NONBLOCK - 专门为F_SETFL公开的参数。

有关 fcntl（） 函数的标准用法，请参阅 MUSL 库。

C 类型time_t

为准备 2038 年 UNIX 时代滚动更新， musl libc 版本 1.2 包括更新，从 32 位到 64 位，C 类型 time_t 及其所有派生。有关此更新的详细信息，请参阅 musl time64 发行说明。

针对 20.10 目标 API 集（sysroot 7）编译的应用程序使用 64 位版本的应用程序 time_t。使用早期版本的 Azure Sphere SDK 或目标 API 集 20.04（sysroot 5）或更早版本生成的应用程序可以继续使用 32 位time_t定义。 Azure Sphere OS 的新版本将继续向这些应用程序提供相同的应用程序二进制接口（ABI）。

不对值大小 time_t 做出任何假设的应用程序代码不受影响。但是，显式或隐式假定 time_t 值为 32 位（例如，通过将值强制转换为 time_t uint32_t）的应用程序代码必须重写以反映 64 位版本。

以下代码片段假定 time_t 为 32 位值，如果使用 20.10 SDK （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 库

Azure Sphere SDK 包括 libcurl 多协议传输库的子集。可以使用此 API 通过 HTTP/HTTPS 传输数据。不支持其他传输协议。库的整个受支持的 API 接口是在 Azure Sphere SDK 头文件中定义的。

API 参考：libcurl 网站

头文件位置： Azure Sphere SDK 安装目录的 Sysroots\API set\usr\include\curl（Windows OS）文件夹或 Sysroots/API set/usr/include/curl （Linux OS）文件夹。

通过