ITnef::ExtractProps

The ITnef::ExtractProps method extracts the properties from a TNEF encapsulation.

Quick Info

HRESULT ExtractProps(
  ULONG ulFlags,                        
  LPSPropTagArray lpPropList,           
  LPSTnefProblemArray FAR * lpProblems  
);

Parameters

ulFlags

[in] Bitmask of flags that controls how properties are decoded. The following flags can be set:

TNEF_PROP_EXCLUDE: Decodes all properties not specified in the lpPropList parameter.
TNEF_PROP_INCLUDE: Decodes all properties specified in lpPropList.

lpPropList

[in] Pointer to the list of properties to include in or exclude from the decoding operation.

lpProblems

[out] Pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties were not encoded properly, if any. If NULL is passed in the lpProblems parameter, no property problem array is returned.

Return Values

S_OK: The call succeeded and has returned the expected value or values.
MAPI_E_CORRUPT_DATA: Data being decoded into a stream is corrupted.

Remarks

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 on any special handling attachments should be given.

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 only supported for objects opened with the TNEF_DECODE flag for the OpenTnefStream or OpenTnefStreamEx function.

The TNEF implementation reports TNEF stream encoding problems without halting 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 STnefProblemArray structure 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.

One exception is that if, during the decoding of a TNEF stream, a property in the MAPI encapsulation block cannot be processed and leaves the stream unreliable; then decoding of the encapsulation block is halted 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 lpProblems; in this case, no problem array is returned.

The value returned in lpProblems is only valid 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, then 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.