Strategies for Error Handling

Because interface methods are virtual, it is not possible to know, as a caller, the full set of values that can be returned from any one call. One implementation of a method might return five values; another might return eight. The reference entries in the MAPI Programmer's Reference list a few values that can be returned for each method; these are the values that your client or service provider can check for and handle because they have special meanings. Other values can be returned, but since they are not meaningful, special code to handle those is not necessary. A simple check for success or failure is adequate.

A few of the interface methods return warnings. If a method that your client or service provider calls can return a warning, use the HR_FAILED macro to test the return value rather than a check for zero or nonzero. Warnings, although nonzero, differ from error codes in that they do not have the high bit set. If your client or service provider does not use the macro, it is likely that a warning might be mistaken for a failure.

Although most interface methods and functions return HRESULT values, some functions, primarily those defined for Simple MAPI, return unsigned long values. Also, some methods used in the MAPI environment come from OLE and return OLE error values rather than MAPI error values. Keep in mind the following guidelines when making calls:

• Never rely on or use the return values from IUnknown::AddRef or IUnknown::Release. These return values are for diagnostic purposes only.
• IUnknown::QueryInterface always returns generic OLE errors where the facility is FACILITY_NULL or FACILITY_RPC, rather than MAPI errors.
• All other interface methods return MAPI interface errors with a facility of FACILITY_ITF, or FACILITY_RPC or FACILITY_NULL errors.
• Simple MAPI calls return Simple MAPI errors rather than SCODE or HRESULT values.
• CMC calls have their own defined set of error codes. CMC codes are unsigned long values.
• No MAPI call ever returns a Simple MAPI error value.

If your service provider works with clients that use both the Simple MAPI and MAPI client interfaces, be aware that although the underlying values for some of the errors are different, the constants defined for them are quite similar. For example, when a call is made to an unsupported feature in Simple MAPI, the error MAPI_E_NOT_SUPPORTED is returned. When the same type of call is made to a MAPI method, one of four possible errors can be returned:

MAPI_E_NO_SUPPORT

MAPI_E_INTERFACE_NOT_SUPPORTED

MAPI_E_INVALID_PARAMETER

MAPI_E_VERSION.

For this reason, avoid including the Simple MAPI header file, MAPI.H, in your client or service provider. The table below points out these similarities and differences.