Published: July 16, 2012
Extracts the properties from a TNEF encapsulation.
Transport providers, message store providers, and gateways call the ITnef::ExtractProps method to extract (that is, decode) properties from the encapsulation of a message or an attachment that was passed to the OpenTnefStream function. The calling provider or gateway can specify a list of properties to decode. Providers and gateways can also use ExtractProps to provide information about any special handling for attachments.
ExtractProps populates the original message passed into OpenTnefStream with the decoded properties. Subsequent ExtractProps calls go back to the message and extract the new list of properties.
Unlike the ITnef::AddProps method, which queues requested actions until the ITnef::Finish method is called, the ExtractProps method decodes the encapsulated properties immediately when it is called. For that reason, the target message for encapsulation decoding should be relatively empty. Existing properties in the target message are overwritten by encapsulated properties.
ExtractProps is supported only for objects that are opened with the TNEF_DECODE flag for the OpenTnefStream or OpenTnefStreamEx function.
The TNEF implementation reports TNEF stream encoding problems without stopping the ExtractProps process. The STnefProblemArray structure returned in lpProblems indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the one of the STnefProblem structures contained in STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which ExtractProps does not return a problem report were processed successfully.
If a property in the MAPI encapsulation block cannot be processed and leaves the stream unreliable during the decoding of a TNEF stream, decoding of the encapsulation block is stopped and a problem is reported. The problem array for this type of problem contains 0L for the ulPropTag member, attMAPIProps or attAttachment for the ulAttribute member, and MAPI_E_UNABLE_TO_COMPLETE for the scode member. Note that the decoding of the stream is not halted, just the decoding of the MAPI encapsulation block. The stream decoding continues with the next attribute block.
If a provider or gateway does not work with problem arrays, it can pass NULL in lppProblems; in this case, no problem array is returned.
The value returned in lpProblems is valid only if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray structure by calling the MAPIFreeBuffer function.