ITnef::Finish

The ITnef::Finish method finishes processing for all TNEF operations that are queued and waiting.

Quick Info

See ITnef : IUnknown.

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

Parameters

ulFlags

Reserved; must be zero.

lpKey

[out] Pointer to the PR_ATTACH_NUM key property of an attachment. The TNEF encapsulation object uses this key to match an attachment to its attachment placement tag within a message. This key should be unique to each attachment.

lpProblem

[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 lpProblem 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::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 halting the Finish process. The STnefProblemArray structure returned in lpProblem 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 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 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.

See Also

ITnef::AddProps, MAPIFreeBuffer, OpenTnefStream, OpenTnefStreamEx, PR_ATTACH_NUM, STnefProblemArray