Estrutura dos 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 bits:

Shows the format of an 'H RESULT' or 'S CODE' with numbers indicating bit positions.

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

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

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

Os campos de recurso comum são descritos na tabela a seguir.

Campo de Instalações Valor Descrição
FACILITY_DISPATCH
 2
 Para erros de interface IDispatch de vinculação tardia.
FACILITY_ITF
 4
 Para a maioria dos códigos de status retornados de métodos de interface. O significado real do erro é definido pela interface. Ou seja, dois HRESULTs com 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 códigos de status retornados de chamadas de procedimento remoto.
FACILITY_STORAGE
 3
 Para códigos de status retornados de chamadas de método IStorage ou IStream relacionadas ao armazenamento estruturado. Códigos de status cujo valor de código (menor 16 bits) está no intervalo de códigos de erro do MS-DOS (ou seja, menos de 256) têm o mesmo significado que o erro correspondente do MS-DOS.
FACILITY_WIN32
 7
 Usado para fornecer um meio de manipular 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 aviso.

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

Recurso é o nome do recurso ou algum outro identificador distintivo; Severidade é uma única letra, S ou E, que indica se a chamada de função foi bem-sucedida (S) ou produziu um erro (E), e Reason é um identificador que descreve o significado do código. Por exemplo, o código de status STG_E_FILENOTFOUND indica que ocorreu um erro relacionado ao armazenamento; Especificamente, um arquivo solicitado não existe. Os códigos de status de FACILITY_NULL omitem o prefixo Facility_.

Os códigos de erro são definidos no contexto de uma implementação de interface. Uma vez definidos, os códigos de sucesso não podem ser alterados ou novos códigos de sucesso 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 erro em COM

Protocolos do Windows: HRESULT