終了コード

  • [アーティクル]

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

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

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

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

エラー レポート

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

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

終了コードの実装のサンプル

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

まず、特定の終了コード値をすべて定義するために使用できる列挙型をアプリケーションで宣言 ExitCode します。 次に、成功状態 (0) にグローバル exitCode 変数を初期化します。

// 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;
}