通过

退出代码

  • 项目

重要

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

Azure Sphere 高级应用程序可以使用退出代码返回与代码中发生错误的位置及其发生原因相关的信息。 退出代码对应于介于 0 和 255 之间的值，其中 0 表示成功。

在应用中定义和使用退出代码

按照以下准则在应用中定义和使用退出代码：

  • 创建一个退出代码变量，并在应用程序开始时将其初始化为成功（0）。
  • 从导致应用程序退出的任何函数返回退出代码。 函数退出代码可以提供有关操作错误的详细信息。 例如，向 IoT Central 应用程序发送消息的函数可能会返回错误代码，该错误代码提供有关故障发生位置的详细信息：在消息构造、IoT 连接、消息传输等中。 负责初始化外围设备的其他函数将返回唯一的退出代码，以指示具有特定外围设备的故障。
  • 如果函数设置或返回失败退出代码（非零），请确保立即传播回 主 函数返回。 这将导致应用程序使用给定的退出代码退出。 Azure Sphere OS 将立即重启应用程序（除非将调试器与连接的开发板配合使用），并且可以使用错误报告来诊断退出的原因。

错误报告

高级应用程序退出时，Azure Sphere OS 会记录应用程序返回的退出代码，稍后会每天将包含此信息的错误报告上传到 Azure Sphere 安全服务。 通过将错误报告中的退出代码与应用程序中定义的退出代码进行比较，通常可以确定错误的位置和原因。 有关详细信息，请参阅 Interpret AppExits 。

RTApps 无法直接向 Azure Sphere 安全服务返回错误数据。 如果要在 RTApp 中实现错误跟踪，则需要使用核心间通信机制将错误数据从 RTApp 传达到高级应用。 有关详细信息，请参阅 与高级应用程序 通信，并与 支持实时的应用程序 通信。

示例退出代码实现

以下代码片段演示了如何将退出代码合并到高级应用程序中的示例。

首先，在应用程序中声明一个 ExitCode 枚举，可用于定义所有特定的退出代码值。 然后，将全局 exitCode 变量初始化为成功状态（0）。

// Exit codes for this application.
typedef enum {
ExitCode_Success = 0;
ExitCode_Init_LED = 1;
ExitCode_Init_Button = 2;
} ExitCode;

// Initialize the termination state.
static volatile sig_atomic_t exitCode = ExitCode_Success;

包含应终止应用程序的错误事例的函数应返回 ExitCode 枚举。 如果达到应终止应用程序的错误案例，则返回为该案例定义的特定退出代码。 在下面的示例中， InitPeripheralsAndHandlers 定义了函数，该函数初始化 LED 和按钮。 如果任一初始化失败，将返回上面定义的相应 ExitCode 值。

// Initialize the peripherals and handlers. Return ExitCode_Success if all resources were allocated
// successfully; otherwise another ExitCode value which indicates a specific failure.
static ExitCode InitPeripheralsAndHandler(void)
{
	// Open SAMPLE_LED as output.
	led = GPIO_OpenAsOutput(SAMPLE_LED);
	if (led == -1) {
		return ExitCode_Init_LED;
	}

	// Open SAMPLE_BUTTON as input.
	button = GPIO_OpenAsInput(SAMPLE_BUTTON);
	if (button == -1) {
		return ExitCode_Init_Button;
	}
	return ExitCode_Success;
}

初始化后，只要全局 exitCode 变量仍分配初始成功值，应用程序就保留在主循环中。 如果主应用程序逻辑的任何部分将变量设置为 exitCode 非成功值，则应用程序将中断主循环，并使用集 exitCode退出。 Azure Sphere OS 将在错误报告中捕获应用退出事件和相应的退出代码，然后重启应用程序。

int main(int argc, char* argv[])
{
	exitCode = InitPeripheralsAndHandler();

	while (exitCode == ExitCode_Success) {
		// Run other application functions within this loop.
		// When a function encounters an error, set a corresponding exit code and return from that function.
		// This will break out of the while loop if the exit code is not ExitCode_Success.
	}

	return exitCode;
}