ITnef::ExtractProps

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

Quick Info

See ITnef : IUnknown7_D1CK.

HRESULT ExtractProps(

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 STnefProblemArray1_H.24_ 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 OpenTnefStream2E24_J. 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.

Once decoding is done, the original message passed into OpenTnefStream is repopulated with the decoded properties. Subsequent ExtractProps calls go back to the message and extract the new list of properties.

Unlike the ITnef::AddProps4DFH_NX method, which queues requested actions until the ITnef::Finish method is called, properties are decoded when the ExtractProps call is made. 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 OpenTnefStreamEx2K9N79E function.

The TNEF implementation reports TNEF stream encoding problems without halting the ExtractProps process. The STnefProblemArray1_H.24_ 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 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 MAPIFreeBuffer16U06F function.

See Also