Edit

ITnef::FinishComponent

  • Article

Applies to: Outlook 2013 | Outlook 2016

Processes individual components from a message one at a time into a Transport-Neutral Encapsulation Format (TNEF) stream.

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

Parameters

ulFlags

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

TNEF_COMPONENT_ATTACHMENT

Processing will be finished for an attachment object; the ulComponentID parameter contains the PR_ATTACH_NUM (PidTagAttachNumber) property of the attachment.

TNEF_COMPONENT_MESSAGE

Processing will be finished for a message object.

ulComponentID

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

lpCustomPropList

[in] A pointer to an SPropTagArray structure that contains property tags that identify 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] A pointer to an SPropValue structure that contains property values for the properties to encode.

lpPropList

[in] A pointer to an SPropTagArray structure that contains property tags for the properties to encode.

lppProblems

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

Return value

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 pass the TNEF_COMPONENT_ENCODING flag in ulFlags for the OpenTnefStream or OpenTnefStreamEx function that opened the object to receive encoding.

Passing values in the lpCustomPropList and lpCustomProps parameters 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 these values enables you to perform encodings with a single call instead of multiple calls.

The TNEF implementation reports TNEF stream encoding problems without stopping 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 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 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 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 by calling the MAPIFreeBuffer function.

See also

ITnef::AddProps
ITnef::SetProps
MAPIFreeBuffer
OpenTnefStream
OpenTnefStreamEx
SPropTagArray
STnefProblemArray
ITnef : IUnknown