ITnef::Finish

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Finishes processing for all Transport-Neutral Encapsulation Format (TNEF) operations that are queued and waiting.

HRESULT Finish(
  ULONG ulFlags,
  WORD FAR * lpKey,
  LPSTnefProblemArray FAR * lpProblem
);

Parameters

• ulFlags
  [in] Reserved; must be zero.

• lpKey
  [out] A pointer to the PR_ATTACH_NUM (PidTagAttachNumber) key property of an attachment. The TNEF encapsulation object uses this key to match an attachment to its attachment placement tag in a message. This key should be unique to each attachment.

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

Return Value

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

Remarks

Transport providers, message store providers, and gateways call the ITnef::Finish method to perform the encoding of all properties for which encoding was requested in calls to the ITnef::AddProps and ITnef::SetProps methods. If the TNEF object was opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function, the Finish method encodes the requested properties into the encapsulation stream passed to that object. If the TNEF object was opened with the TNEF_DECODE flag, the Finish method decodes the properties from the TNEF stream and writes them back to the message they belong to.

After the Finish call, the pointer to the encapsulation stream points to the end of the TNEF data. If the provider or gateway needs to use the TNEF stream data after the Finish call, it must reset the stream pointer to the beginning of the TNEF stream data.

The TNEF implementation reports TNEF stream encoding problems without stopping the Finish process. The STnefProblemArray structure returned in the lpProblem parameter 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 Finish 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 lpProblem; in this case, no problem array is returned.

The value returned in lpProblem 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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

ITnef::AddProps

MAPIFreeBuffer

OpenTnefStream

OpenTnefStreamEx

PidTagAttachNumber Canonical Property

STnefProblemArray

ITnef : IUnknown

Concepts

MFCMAPI as a Code Sample