Compartilhar via

Códigos de saída

  • Artigo

Importante

Esta é a documentação do Azure Sphere (herdado). O Azure Sphere (herdado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).

Um aplicativo de alto nível do Azure Sphere pode usar códigos de saída para retornar informações relacionadas a onde o erro ocorreu no código e por que ele ocorreu. Um código de saída corresponde a um valor entre 0 e 255, em que 0 indica êxito.

Definir e usar códigos de saída em um aplicativo

Siga estas diretrizes para definir e usar códigos de saída em um aplicativo:

  • Crie uma variável de código de saída e inicialize-a para êxito (0) no início do aplicativo.
  • Retorna um código de saída de qualquer função em que um erro tenha causado a saída do aplicativo. Os códigos de saída de função podem fornecer informações detalhadas sobre erros operacionais. Por exemplo, uma função que envia uma mensagem para um aplicativo do IoT Central pode retornar um código de erro que fornece detalhes sobre onde ocorreu a falha: na construção da mensagem, na conexão IoT, na transmissão da mensagem e assim por diante. Uma função diferente responsável pela inicialização de periféricos retornaria um código de saída exclusivo para indicar uma falha com um periférico específico.
  • Se um código de saída de falha (diferente de zero) for definido ou retornado por uma função, certifique-se de que ele seja imediatamente propagado de volta para que a função principal retorne. Isso fará com que o aplicativo saia com o código de saída fornecido. O sistema operacional do Azure Sphere reiniciará imediatamente seu aplicativo (a menos que você esteja usando o depurador com uma placa de desenvolvimento conectada) e você poderá usar relatórios de erros para diagnosticar o motivo da ocorrência de uma saída.

Relatórios de erros

Quando um aplicativo de alto nível é encerrado, o sistema operacional do Azure Sphere registra o código de saída retornado pelo aplicativo e, posteriormente, carrega um relatório de erros contendo essas informações para o Serviço de Segurança do Azure Sphere diariamente. Ao comparar o código de saída no relatório de erros com os códigos de saída definidos em seu aplicativo, muitas vezes você pode determinar o local e a causa do erro. Consulte Interpretar AppExits para obter mais informações.

Os RTApps não podem retornar dados de erro diretamente para o Serviço de Segurança do Azure Sphere. Se você quiser implementar o controle de erros em um RTApp, precisará comunicar os dados de erro do RTApp a um aplicativo de alto nível usando o mecanismo de comunicação entre núcleos. Consulte Comunicar-se com um aplicativo de alto nível e Comunicar-se com um aplicativo com capacidade em tempo real para obter detalhes.

Exemplo de implementação de código de saída

Os snippets a seguir mostram um exemplo de como você pode incorporar códigos de saída em um aplicativo de alto nível.

Primeiro, declare uma ExitCode enumeração em seu aplicativo que você pode usar para definir todos os seus valores de código de saída específicos. Em seguida, inicialize uma variável global exitCode para o estado de sucesso (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;

As funções que contêm casos de erro que devem encerrar o aplicativo devem retornar uma enumeração ExitCode. Se for atingido um caso de erro que deve encerrar o aplicativo, retorne o código de saída específico definido para esse caso. No exemplo abaixo, a InitPeripheralsAndHandlers função é definida, que inicializa um LED e um botão. Se a inicialização falhar, o valor correspondente ExitCode definido acima será retornado.

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

Após a inicialização, o aplicativo permanece no loop principal enquanto a variável global exitCode ainda receber o valor de sucesso inicial. Se qualquer parte da lógica do aplicativo principal definir a exitCode variável como um valor diferente de sucesso, o aplicativo sairá do loop principal e sairá com o conjunto exitCode. O sistema operacional do Azure Sphere capturará o evento de saída do aplicativo e o código de saída correspondente em um relatório de erros e, em seguida, reiniciará o aplicativo.

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