Estrutura de códigos de erro COM

  • Artigo

A ilustração a seguir mostra o formato de um HRESULT (ou SCODE); os números indicam posições de bit:

Mostra o formato de um 'H RESULT' ou 'S CODE' com números que indicam posições de bit.

O bit de alta ordem no HRESULT ou SCODE indica se o valor retornado representa êxito ou falha. Se definido como 0, SEVERITY_SUCCESS, o valor indicará êxito. Se definido como 1, SEVERITY_ERROR, ele indicará falha.

Os bits R, C, N e r são reservados.

O campo de instalação indica o serviço do sistema responsável pelo erro. A Microsoft aloca novos códigos de instalação conforme eles se tornam necessários. A maioria dos valores SCODEs e HRESULT define o campo de instalação como FACILITY_ITF, indicando um erro de método de interface.

Os campos de instalação comuns são descritos na tabela a seguir.

Campo de Instalação Valor Descrição
FACILITY_DISPATCH
 2
 Para erros de interface IDispatch de associação tardia.
FACILITY_ITF
 4
 Para a maioria dos status códigos retornados de métodos de interface. O significado real do erro é definido pela interface . Ou seja, dois HRESULTscom exatamente o mesmo valor de 32 bits retornado de duas interfaces diferentes podem ter significados diferentes.
FACILITY_NULL
 0
 Para códigos de status comuns amplamente aplicáveis, como S_OK.
FACILITY_RPC
 1
 Para status códigos retornados de chamadas de procedimento remoto.
FACILITY_STORAGE
 3
 Para status códigos retornados de chamadas de método IStorage ou IStream relacionadas ao armazenamento estruturado. Códigos de status cujo valor de código (16 bits inferiores) está no intervalo de códigos de erro MS-DOS (ou seja, menos de 256) têm o mesmo significado que o erro MS-DOS correspondente.
FACILITY_WIN32
 7
 Usado para fornecer um meio de lidar com códigos de erro de funções na API do Windows como UM HRESULT. Códigos de erro no OLE de 16 bits que duplicaram códigos de erro do sistema também foram alterados para FACILITY_WIN32.
FACILITY_WINDOWS
 8
 Usado para códigos de erro adicionais de interfaces definidas pela Microsoft.

O campo de código é um número exclusivo atribuído para representar o erro ou o aviso.

Por convenção, os valores HRESULT geralmente têm nomes no seguinte formato: Facility_Severity_Reason.

A instalação é o nome da instalação ou algum outro identificador diferenciador; Severidade é uma única letra, S ou E, que indica se a chamada de função teve êxito (S) ou produziu um erro (E); e Reason é um identificador que descreve o significado do código. Por exemplo, o código status STG_E_FILENOTFOUND indica que ocorreu um erro relacionado ao armazenamento; especificamente, um arquivo solicitado não existe. Códigos de status de FACILITY_NULL omita o prefixo Facility_.

Os códigos de erro são definidos no contexto de uma implementação de interface. Depois de definidos, os códigos de êxito não podem ser alterados ou novos códigos de êxito adicionados. No entanto, novos códigos de falha podem ser gravados. A Microsoft reserva-se o direito de definir novos códigos de falha (mas não códigos de êxito) para as interfaces descritas em FACILITY_ITF ou em novas instalações.

Tratamento de erros no COM

Protocolos do Windows: HRESULT