終了コード

Azure Sphere の高度なアプリケーションでは、終了コードを使用して、エラーが発生したコード内の場所と発生した理由に関連する情報を返すことができます。 終了コードは、0 ~ 255 の値に対応します。0 は成功を示します。

アプリで終了コードを定義して使用する

次のガイドラインに従って、アプリで終了コードを定義して使用します。

• 終了コード変数を作成し、アプリケーションの開始時に成功 (0) に初期化します。
• エラーが原因でアプリケーションが終了した関数から終了コードを返します。 関数の終了コードは、操作エラーに関する詳細情報を提供できます。 たとえば、IoT Central アプリケーションにメッセージを送信する関数は、エラーが発生した場所に関する詳細を提供するエラー コードを返す場合があります。メッセージの構築、IoT 接続、メッセージ送信などです。 周辺機器の初期化を担当する別の関数は、特定の周辺機器でエラーを示す一意の終了コードを返します。
• エラー終了コード (0 以外) が関数によって設定または返された場合は、 main 関数が返されるようにすぐに反映されるようにします。 これにより、アプリケーションは特定の終了コードで終了します。 Azure Sphere OS は、(接続された開発ボードでデバッガーを使用していた場合を除き) アプリケーションを直ちに再起動します。また、エラー レポートを使用して、終了が発生した理由を診断できます。

エラー レポート

高度なアプリケーションが終了すると、Azure Sphere OS によってアプリケーションによって返された終了コードがログに記録され、その後、この情報を含むエラー レポートが Azure Sphere Security Service に毎日アップロードされます。 エラー レポートの終了コードを、アプリケーションで定義されている終了コードと比較することで、多くの場合、エラーの場所と原因を特定できます。 詳細については、 Interpret AppExits を参照してください。

RTApps は、エラー データを Azure Sphere Security Service に直接返すことはできません。 RTApp でエラー追跡を実装する場合は、コア間通信メカニズムを使用して、RTApp から高レベルアプリにエラー データを通信する必要があります。 詳細については、 高度なアプリケーションを使用したcommunicate およびリアルタイム対応アプリケーションでの Communicate に関するページを参照してください。

終了コードの実装例

次のスニペットは、高度なアプリケーションに終了コードを組み込む方法のサンプルを示しています。

まず、特定の終了コード値をすべて定義するために使用できる 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 列挙型を返す必要があります。 アプリケーションを終了するエラー ケースに達した場合は、そのケースに対して定義した特定の終了コードを返します。 次の例では、led とボタンを初期化する InitPeripheralsAndHandlers 関数が定義されています。 いずれかの初期化に失敗した場合は、上記で定義した対応する 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;
}