Retrieving MAPI Properties
Applies to: Office 2010 | Outlook 2010 | Visual Studio
When a client or service provider retrieves a property from an object, the object makes available the property's value, type, and identifier.
Clients and service providers can retrieve an object's properties by calling one of the following:
The GetProps method is used to retrieve one or more properties that do not need a specialized or alternate interface for access. This implies that the properties available with GetProps are small, such as integers and Boolean values.
To retrieve multiple properties
Allocate an SPropTagArray structure large enough to hold the number of properties to be retrieved.
Set the cValues member of the SPropTagArray structure to the number of properties to be retrieved and set each aulPropTag member to the identifier and type, if possible, of one of the target properties. If the type is unknown, set it to PT_UNSPECIFIED. If both the type and the identifier are unknown, locate this information by calling IMAPIProp::GetPropList. GetPropList returns a property tag array with all of the object's supported properties. If only a property name is available, call IMAPIProp::GetIDsFromNames to access the associated identifier.
Call IMAPIProp::GetProps to open the property or properties.
The OpenProperty method is used to open larger properties that require an alternate interface such as IStream or IMAPITable for access. OpenProperty is typically used to open large character string, binary, and object properties and can only open one property at a time. Callers pass in the identifier of the additional interface that is required as one of the input parameters.
Some of the common uses of OpenProperty include opening PR_BODY (PidTagBody), the property that holds the body of a text-based message, PR_ATTACH_DATA_OBJ (PidTagAttachDataObject), the property that holds an OLE object or message attachment, and PR_CONTAINER_CONTENTS (PidTagContainerContents), the property that holds a folder or address book container contents table.
Depending on the property, a different interface is requested from OpenProperty. IStream, an interface that allows property data to be read and written as a stream of bytes, is typically used to access PR_BODY. Either IMessage or IStream can be used to access PR_ATTACH_DATA_OBJ. Embedded message attachments that are standard messages use IMessage whereas messages in the TNEF format use IStream. Because PR_CONTAINER_CONTENTS is a table object, it is accessed with IMAPITable.
To retrieve an attachment's PR_ATTACH_DATA_BIN property
Call the OpenStreamOnFile function to open a stream for the file.
Call the message's IMAPIProp::OpenProperty method to retrieve the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property with the IStream interface. Set both the MAPI_MODIFY and MAPI_CREATE flags.
Allocate a STATSTG structure and pass it in a call to the file stream's IStream::Stat method to determine its size. Another way to determine stream size is to call IStream::Seek with the flag STREAM_SEEK_END.
Call the stream's IStream::CopyTo method to copy the data from the file's stream into the attachment stream.
When the copy operation is finished, release both streams by calling their IUnknown::Release methods.
When IStream is used for property access, some service providers automatically send the size of the property back with the stream. Calling OpenProperty with the MAPI_DEFERRED_ERRORS flag can delay the opening of the property and the return of the stream size. If IStream::Stat is called to retrieve this size after OpenProperty with the MAPI_DEFERRED_ERRORS flag set, performance will be impacted because this sequence of calls forces an extra remote procedure call. To avoid the performance hit, clients can call any MAPI method between the calls to OpenProperty and to Stat.
The HrGetOneProp function, like OpenProperty, opens one property at a time. HrGetOneProp should only be used when the target object exists on the local machine. When the target object is not locally available, using HrGetOneProp repeatedly can result in multiple remote procedure calls and a performance degradation.
Callers that need several properties can either call HrGetOneProp or OpenProperty in a loop or make one call to GetProps. Calling GetProps once is more efficient.
Note
Secure properties are not automatically available with other properties in a GetProps, HrGetOneProp, or GetPropList call. Secure properties must be explicitly requested using their property identifiers.