| Platform SDK: MAPI |
Success, warning, and error values are returned using a 32-bit number known as a result handle, or HRESULT. An HRESULT is really not a handle to anything; it is merely a 32-bit value with several fields encoded in the value. A zero result indicates success and a nonzero result indicates failure.
HRESULT values work differently depending on the platform your client or service provider is using. On 16-bit platforms, an HRESULT is generated from a 32-bit value known as a status code, or SCODE. On 32-bit platforms, an HRESULT is the same as an SCODE; they are synonymous data types. MAPI on 32-bit platforms works solely with HRESULT values.
SCODEs on 16-bit platforms are divided into four fields: a severity code, a context field, a facility field, and an error code. The format of an SCODE on a 16-bit platform is shown below; the numbers indicate bit positions.
HRESULTs on 32-bit platforms have the following format.
The severity code in the 16-bit SCODE and the high order bit in the HRESULT indicate whether the return value represents success or failure. If set to zero, the value indicates success. If set to 1, it indicates failure.
In the 16-bit version of the SCODE, the context field is reserved as are the R, C, N, and r bits in the HRESULT.
The facility field in both versions indicates the area of responsibility for the error. There are several facilities, but the vast majority of MAPI errors use FACILITY_ITF to represent interface errors. The most common facilities that are currently used are: FACILITY_NULL, FACILITY_ITF, FACILITY_DISPATCH, FACILITY_RPC, and FACILITY_STORAGE. If new facilities are necessary, Microsoft allocates them because they need to be unique. The following table describes the various facility fields.
| Facility | Description |
|---|---|
| FACILITY_NULL | For broadly applicable common status codes such as S_OK or E_OUTOF_MEMORY; the value is zero. |
| FACILITY_ITF | For most status codes returned from interface methods; the value is defined by the interface. That is, two SCODE or HRESULT values with exactly the same 32-bit value returned from two different interfaces might have different meanings. |
| FACILITY_DISPATCH | For late binding IDispatch interface errors. |
| FACILITY_RPC | For status codes returned from remote procedure calls. |
| FACILITY_STORAGE | For status codes returned from IStorage or IStream method calls relating to structured storage. Status codes with code (lower 16 bits) values in the range of MS-DOS error codes (that is, less than 256) have the same meaning as the corresponding MS-DOS errors. |
The code field is a unique number that is assigned to represent the error or warning.