Using Extended Errors

Implementers of interface methods can choose to simply return success (S_OK) and failure (MAPI_E_CALL_FAILED) or differentiate between error conditions, returning as many error values as make sense for the situation. Most situations can use one of the error values defined by MAPI in the MAPICODE.H header file. However, for situations that are not covered by a predefined value, the value MAPI_E_EXTENDED_ERROR can be used. MAPI_E_EXTENDED_ERROR indicates to the caller that more information about the error is available. The caller retrieves the additional information by calling the GetLastError method on the same object that returned MAPI_E_EXTENDED_ERROR.

GetLastError can be called to retrieve information about any error code, not only MAPI_E_EXTENDED_ERROR. Many MAPI objects implement interfaces that include the GetLastError method. GetLastError returns a single MAPIERROR structure that, in theory, includes a concatenation of all the errors generated by the previous method call. As a caller, it is wise not to depend on having this extra error information available because object implementers are not required to provide it. However, it is strongly recommended that whenever implementers return MAPI_E_EXTENDED_ERROR, they make it possible for callers to retrieve a MAPIERROR structure with useful information about the error.

Because GetLastError is also an API function that is part of the Platform SDK, it can be easy to forget that in MAPI, GetLastError is an interface method and can only be called on MAPI objects. Another easy mistake to make is calling GetLastError on the wrong object. GetLastError must be called on the object that generated the error. For example, if your client makes a session call, and MAPI forwards the call to a service provider to do the work, your client should not call GetLastError on the service provider object. IMAPISession::GetLastError is the correct call; GetLastError should be invoked on the session object.