Handling MAPI property errors
Applies to: Outlook 2013 | Outlook 2016
Instead of complete failure or success, the following IMAPIProp methods report partial success:
GetProps reports partial success when it can retrieve at least one of the requested properties for an object. GetProps indicates partial success by returning the warning MAPI_W_ERRORS_RETURNED and placing information about the unavailable properties in the property value array pointed to by the lppPropArray parameter. An unavailable property's entry in this array contains PT_ERROR for the property type in the ulPropTag member and MAPI_E_NOT_FOUND or another appropriate error value for the Value member. For example, if a client calls a folder's GetProps method to retrieve three properties and the third is unavailable, the message store provider places PT_ERROR in the third property type in the property value array and MAPI_E_NOT_FOUND in the third property value.
The other IMAPIProp methods report partial success differently. These methods report partial success by returning S_OK and placing error information in an SPropProblemArray structure. Unlike the property value array in GetProps that contains data regardless of whether the method succeeded or failed, the property problem array in these methods exists only if there are errors and only if the caller has registered interest in learning about the errors. Callers must specify a valid SPropProblemArray pointer to register for error information.
When an error value is returned from SetProps, DeleteProps, CopyTo, or CopyProps, this indicates failure instead of partial success. The property problem array, if available, is not valid. Clients should not try to access data held in the structure nor should they try to free the structure itself. The appropriate response is to call IMAPIProp::GetLastError.
GetLastError is similar to the function of the same name provided in the Windows SDK. Both provide more detailed information about an error than is available with the return value. They both return information about the previous error that has occurred. The difference is that the Win32 GetLastError function reports on an error generated by the calling thread and the IMAPIProp::GetLastError method reports on an error generated by the current object. That is, if a client calls DeleteProps on a message and MAPI_E_NO_ACCESS is returned to indicate that the message is read-only, GetLastError returns data provided by the message.