New MAPI function to access native body (839560)

MORE INFORMATION

Function definition

HRESULT __stdcall WrapCompressedRTFStreamEx(
  LPSTREAM              lpCompressedRTFStream,
  CONST RTF_WCSINFO *   pWCSInfo,
  LPSTREAM *            lppUncompressedRTFStream,
  RTF_WCSRETINFO *      pRetInfo
);

Parameters

lpCompressedRTFStream
[in] This is a pointer to a stream that is opened on the PR_RTF_COMPRESSED property of a message.

pWCSInfo
[in] This is a pointer to a RTF_WCSINFO structure that contains options for the function. See the "New flags and structures" section for additional details about this structure.

lppUncompressedRTFStream
[out] This is a pointer to the location where the WrapCompressedRTFStream function returns a stream for the decompressed RTF.

pRetInfo
[out] This is a pointer to a RTF_WCSRETINFO structure that contains information about the format of the returned decompressed stream. See the "New flags and structures" section for additional details about this structure.

Return Values

S_OK	The call succeeded and returned the expected value or values.
MAPI_E_INVALID_PARAMETER	This is returned if the MAPI_NATIVE_BODY flag is combined with the MAPI_MODIFY flag in ulFlags.

Remarks

To use the WrapCompressedRTFStreamEx function, you must load Msmapi32.dll by using the LoadLibrary function. Then, retrieve a function pointer to the WrapCompressedRTFStreamEx function by using the GetProcAddress function.

Because the MAPI_NATIVE_BODY flag cannot be combined with the MAPI_MODIFY flag, you can only access the native body stream in read-only mode.

To access the native body stream in read/write mode, we recommend that you use the WrapCompressedRTFStream function.

For additional information about the WrapCompressedRTFStream function, visit the following Microsoft Developer Network (MSDN) Web site:

New flags and structures

The WrapCompressedRTFStreamEx function uses the following new flags that are not defined in the current version of Mapidefs.h:

#define MAPI_NATIVE_BODY 0x00010000

#define MAPI_NATIVE_BODY_TYPE_RTF 0x00000001
#define MAPI_NATIVE_BODY_TYPE_HTML 0x00000002
#define MAPI_NATIVE_BODY_TYPE_PLAINTEXT 0x00000004

RTF_WCSINFO structure

The RTF_WCSINFO structure is defined as follows:

typedef struct {
    ULONG       size;
    ULONG       ulFlags;
    ULONG       ulInCodePage;
    ULONG       ulOutCodePage;
} RTF_WCSINFO;

Members

size
This is the size of the RTF_WCSINFO structure.

ulFlags
This is the bitmask of option flags for the function. The following flags can be set:

MAPI_MODIFY	This indicates whether the client intends to read or to write the wrapped stream interface that is returned.
STORE_UNCOMPRESSED_RTF	This indicates whether the decompressed RTF is supposed to be written to the stream that is pointed to by the lpCompressedRTFStream pointer.
MAPI_ NATIVE_BODY	This indicates whether the decompressed stream is additionally converted to the native body before returning the stream. Important This cannot be combined with the MAPI_MODIFY flag.

ulInCodePage
This is the code page value of the message. Typically, this value is obtained from the PR_INTERNET_CPID property on the message. This value is only used when the MAPI_NATIVE_BODY flag is passed in ulFlags. Otherwise, this value is ignored.

ulOutCodePage
This is the code page value of the returned decompressed stream that you want. If this is set to a non-zero value, the WrapCompressedRTFStreamEx function converts the stream to the specified code page. If this is set to a zero value, MAPI decides which code page to use. This value is only used when the MAPI_NATIVE_BODY flag is passed in ulFlags, and the body format is not RTF. Otherwise, this value is ignored.

RTF_WCSRETINFO structure

The RTF_WCSRETINFO structure is defined as follows:

typedef struct {
    ULONG       size;   
    ULONG       ulStreamFlags;
} RTF_WCSRETINFO;

Members
size
This is the size of the RTF_WCSRETINFO structure.

ulStreamFlags
This is a value that indicates the format of the native body. This value is only valid if the MAPI_NATIVE_BODY flag is passed in the ulFlags parameter of the RTF_WCSINFO structure that is passed to the WrapCompressedRTFStreamEx function. This can be one of the following values:

MAPI_NATIVE_BODY_TYPE_RTF	This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is RTF.
MAPI_NATIVE_BODY_TYPE_PLAIN_TEXT	This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is plain text format.
MAPI_NATIVE_BODY_TYPE_HTML	This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is HTML format.

Sample code

The following sample code shows you how to use the WrapCompressedRTFStreamEx function:

//These are definitions for the WrapCompressedRTFStreamEx function.
typedef HRESULT (STDMETHODCALLTYPE WRAPCOMPRESSEDRTFSTREAMEX) (
    LPSTREAM lpCompressedRTFStream, CONST RTF_WCSINFO * pWCSInfo, LPSTREAM * lppUncompressedRTFStream, RTF_WCSRETINFO * pRetInfo);
typedef WRAPCOMPRESSEDRTFSTREAMEX *LPWRAPCOMPRESSEDRTFSTREAMEX;

HRESULT TestWrapCompressedRTFStreamEx(LPMESSAGE lpMsg)
{
    HRESULT         hRes = S_OK;
    LPSTREAM        lpCompressed = NULL;
    LPSTREAM        lpUncompressed = NULL;
    char            szBody[1024] = {0};
    ULONG           ulRead = 0;
    RTF_WCSINFO     wcsinfo = {0};
    RTF_WCSRETINFO  retinfo = {0};
    LPSPropValue    lpPropCPID = NULL;

    retinfo.size = sizeof(RTF_WCSRETINFO);

    wcsinfo.size = sizeof(RTF_WCSINFO);
    wcsinfo.ulFlags = MAPI_NATIVE_BODY;
    wcsinfo.ulOutCodePage = 0;

    // Retrieve the value of the Internet code page.
    // Pass this value to the WrapCompressedRTFStreamEx function.
    // If the property is not found, the default is 0.
    if(SUCCEEDED(hRes = HrGetOneProp(lpMsg, PR_INTERNET_CPID, &lpPropCPID)))
    {
        wcsinfo.ulInCodePage = lpPropCPID->Value.l;
    }

    // Open the compressed RTF stream.
    if(SUCCEEDED(hRes = lpMsg->OpenProperty(PR_RTF_COMPRESSED,
                                         &IID_IStream,
                                         STGM_READ | STGM_DIRECT,
                                         0,
                                         (LPUNKNOWN*)&lpCompressed)))
    {

        // Notice that the WrapCompressedRTFStreamEx function has been loaded
        // by using the GetProcAddress function into pfnWrapEx.

        // Call the WrapCompressedRTFStreamEx function.
        if(SUCCEEDED(hRes = pfnWrapEx(lpCompressed,
                                   &wcsinfo,
                                   &lpUncompressed,
                                   &retinfo)))
        {

            printf("Body's native type is: ");

            // Check what the native body type is.
            switch(retinfo.ulStreamFlags)
            {
            case MAPI_NATIVE_BODY_TYPE_RTF:
                printf("MAPI_NATIVE_BODY_TYPE_RTF\n");
                break;
            case MAPI_NATIVE_BODY_TYPE_HTML:
                printf("MAPI_NATIVE_BODY_TYPE_HTML\n");
                break;
            case MAPI_NATIVE_BODY_TYPE_PLAINTEXT:
                printf("MAPI_NATIVE_BODY_TYPE_PLAINTEXT\n");
                break;
            default:
                printf("UNKNOWN\n");
            }

            // Read the first 1,000 characters out of the stream.
            if(SUCCEEDED(hRes = lpUncompressed->Read(szBody, 1024, &ulRead)))
            {
                printf("First %d characters of the native body stream:\n%s\n", ulRead, szBody);
            }
        }
    }

    MAPIFreeBuffer(lpPropCPID);
    if(lpUncompressed)lpUncompressed->Release();
    if(lpCompressed)lpCompressed->Release();

    return hRes;
}