ITnef::FinishComponent

Platform SDK: MAPI

ITnef::FinishComponent

The ITnef::FinishComponent method processes individual components from a message one at a time into a TNEF stream.

Quick Info

HRESULT FinishComponent(
  ULONG ulFlags,                      
  ULONG ulComponentID,                
  LPSPropTagArray lpCustomPropList,   
  LPSPropValue lpCustomProps,         
  LPSPropTagArray lpPropList,         
  LPSTnefProblemArray FAR * lppProblems  
);

Parameters

ulFlags

[in] Bitmask of flags that controls which component will be finished. One or the other of the following flags must be set:

TNEF_COMPONENT_ATTACHMENT: Finish processing for an attachment object; the ulComponentID parameter contains the PR_ATTACH_NUM property of the attachment.
TNEF_COMPONENT_MESSAGE: Finish processing for a message object.

ulComponentID

[in] Zero to indicate processing for a message or the PR_ATTACH_NUM property of the attachment to be processed. If the TNEF_COMPONENT_MESSAGE flag is set in the ulFlags parameter, ulComponentID must be zero.

lpCustomPropList

[in] Pointer to an SPropTagArray structure that holds property tags identifying the properties passed in the lpCustomProps parameter. There must be a one-to-one correspondence between each property value in lpCustomProps and a property tag in the lpCustomPropList parameter.

lpCustomProps

[in] Pointer to an SPropValue structure containing property values for the properties to encode.

lpPropList

[in] Pointer to an SPropTagArray structure containing property tags for the properties to encode.

lppProblems

[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 lppProblems parameter, no property problem array is returned.

Return Values

S_OK: The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::FinishComponent method to perform TNEF processing for one component, either a message or an attachment, as indicated by the flag set in the ulFlags parameter.

For component processing to be enabled, the calling provider or gateway must have passed the TNEF_COMPONENT_ENCODING flag in ulFlags for the OpenTnefStream function or OpenTnefStreamEx function that opened the object to receive encoding.

Passing values in lpCustomPropList and lpCustomProps performs component encoding equivalent to that done by the ITnef::SetProps method. Passing a value in the lpPropList parameter performs component encoding equivalent to that done by the ITnef::AddProps method with the TNEF_PROP_INCLUDE flag set in ulFlags. Passing such values enables you to perform encodings with a single call rather than multiple calls.

The TNEF implementation reports TNEF stream encoding problems without halting the FinishComponent process. The STnefProblemArray structure returned in lppProblems 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 FinishComponent does not return a problem report were processed successfully.

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 lppProblems 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 by calling the MAPIFreeBuffer function.