Struktura kodów błędów COM
Poniższa ilustracja przedstawia format HRESULT (lub SCODE); liczby wskazują pozycje bitów:
Bit o wysokiej kolejności w HRESULT lub SCODE wskazuje, czy wartość zwracana reprezentuje powodzenie lub niepowodzenie. Jeśli ustawiono wartość 0, SEVERITY_SUCCESS, to oznacza powodzenie. Jeśli ustawiono wartość 1, SEVERITY_ERROR, oznacza to niepowodzenie.
Bity R, C, N i r są zarezerwowane.
Pole obiektu wskazuje usługę systemową odpowiedzialną za błąd. Firma Microsoft przydziela nowe kody obiektów w miarę ich potrzeb. Większość wartości SCODE i HRESULT ustawia pole struktury na FACILITY_ITF, co wskazuje na błąd metody interfejsu.
Ogólne pola udogodnień opisano w poniższej tabeli.
| Pole placówki | Wartość | Opis |
|---|---|---|
| ZARZĄDZANIE_OBIEKTEM |
2 |
W przypadku błędów interfejsu późnego wiązania IDispatch. |
| FACILITY_ITF |
4 |
W przypadku większości kodów stanu zwracanych z metod interfejsu. Rzeczywiste znaczenie błędu jest definiowane przez interfejs. Oznacza to, że dwie HRESULTs z dokładnie taką samą wartością 32-bitową zwróconą z dwóch różnych interfejsów mogą mieć różne znaczenie. |
| FACILITY_NULL |
0 |
W przypadku powszechnie stosowanych typowych kodów stanu, takich jak S_OK. |
| FACILITY_RPC |
1 |
W przypadku kodów stanu zwracanych z wywołań zdalnych procedur. |
| FACILITY_STORAGE |
3 |
W przypadku kodów stanu zwróconych w ramach wywołań metod IStorage lub IStream dotyczących magazynu strukturalnego. Kody stanu, których wartość kodu (niższe 16 bitów) znajduje się w zakresie kodów błędów MS-DOS (czyli mniejszych niż 256) ma takie samo znaczenie jak odpowiedni błąd MS-DOS. |
| FACILITY_WIN32 |
7 |
Używane do zapewnienia możliwości obsługi kodów błędów z funkcji w interfejsie API systemu Windows jako HRESULT. Kody błędów w 16-bitowym OLE, które zduplikowały kody błędów systemowych, również zmieniono na FACILITY_WIN32. |
| FACILITY_WINDOWS |
8 |
Służy do obsługi dodatkowych kodów błędów z interfejsów zdefiniowanych przez firmę Microsoft. |
Pole kodu jest unikatową liczbą przypisaną do reprezentowania błędu lub ostrzeżenia.
Zgodnie z konwencją wartości HRESULT mają zazwyczaj nazwy w następującym formacie: Facility_Ważność_Przyczyna.
Obiekt jest nazwą obiektu lub innym identyfikatorem wyróżniającym; Poziom istotności to pojedyncza litera, S lub E, która wskazuje, czy wywołanie funkcji powiodło się (S) lub wygenerowało błąd (E); Powód to identyfikator opisujący znaczenie kodu. Na przykład kod stanu STG_E_FILENOTFOUND wskazuje, że wystąpił błąd związany z magazynem; w szczególności żądany plik nie istnieje. Kody statusu z FACILITY_NULL pomijają prefiks Facility_.
Kody błędów są definiowane w kontekście implementacji interfejsu. Po zdefiniowaniu kodów powodzenia nie można zmienić ani dodać nowych kodów powodzenia. Można jednak zapisać nowe kody błędów. Firma Microsoft zastrzega sobie prawo do definiowania nowych kodów błędów (ale nie kodów powodzenia) dla interfejsów opisanych w FACILITY_ITF lub w nowych obiektach.