Partilhar via

Códigos de saída

  • Artigo

Importante

Esta é a documentação do Azure Sphere (Legado). O Azure Sphere (Legado) 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 no código o erro ocorreu e por que ele ocorreu. Um código de saída corresponde a um valor entre 0 e 255, onde 0 indica sucesso.

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 com êxito (0) no início do aplicativo.
  • Retornar 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 da 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 de mensagens, conexão IoT, transmissão de mensagens 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 Azure Sphere reiniciará imediatamente seu aplicativo (a menos que você estivesse usando o depurador com uma placa de desenvolvimento conectada) e você pode usar relatórios de erros para diagnosticar o motivo pelo qual uma saída ocorreu.

Relatórios de erros

Quando um aplicativo de alto nível é encerrado, o sistema operacional Azure Sphere registra o código de saída retornado pelo seu 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.

O RTApps não pode 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 para um aplicativo de alto nível usando o mecanismo de comunicação entre núcleos. Consulte Comunicar com uma aplicação de alto nível e Comunicar com uma aplicação com capacidade em tempo real para obter detalhes.

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

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

Primeiro, declare um ExitCode enum em seu aplicativo que você pode usar para definir todos os seus valores específicos de código de saída. 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 um enum ExitCode. Se for atingido um caso de erro que deve encerrar o aplicativo, retorne o código de saída específico que você definiu para esse caso. No exemplo abaixo, a InitPeripheralsAndHandlers função é definida, que inicializa um LED e um botão. Se qualquer 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 para um valor diferente de sucesso, o aplicativo sairá do loop principal e sairá com o conjunto exitCode. O SO Azure Sphere irá capturar o evento de saída da aplicação e o código de saída correspondente num relatório de erros e, em seguida, reiniciar a aplicação.

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