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:

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.

Simple MAPI return value MAPI return value
MAPI_E_NOT_SUPPORTED MAPI_E_NO_SUPPORT
MAPI_E_INTERFACE_NOT_SUPPORTED
MAPI_E_INVALID_PARAMETER
MAPI_E_VERSION
MAPI_E_DISK_FULL MAPI_E_NOT_ENOUGH_DISK
MAPI_E_NETWORK_FAILURE MAPI_E_NETWORK_ERROR
MAPI_E_USER_ABORT MAPI_E_USER_CANCEL
MAPI_E_ACCESS_DENIED MAPI_E_NO_ACCESS
MAPI_E_AMBIGUOUS_RECIPIENT MAPI_E_AMBIGUOUS_RECIP