| Platform SDK: Exchange 2000 Server |
[This is preliminary documentation and subject to change.]
Defines an object used to manipulate a body part of a message.
BodyPart objects make up the hierarchy of content and structural units for a message. Each BodyPart object can contain some part of a Message object's content, whether it is an attachment or a part of a MIME hierarchy of content. BodyPart objects can also act as structural units for a MIME-formatted message.
In a uuencode-formatted message, each Message object attachment is contained within a BodyPart object, in the Message object's IBodyPart::BodyParts collection. In a MIME-formatted message, BodyPart objects act as the structural units of the MIME hierarchy, with the top-level Message object acting as the root. The BodyPart object may not necessarily contain content, such as when it acts as a MIME structural unit with Content-Type set to “multipart/alternative”. In this case, it simply contains other BodyPart objects in its IBodyPart::BodyParts collection, where each object contains the alternative representations of the content.
Each BodyPart object can contain header fields located in the IBodyPart::Fields collection. For objects that make up a MIME-formatted message, the Fields collection contains fields used to define the MIME headers for the part, such as Content-Type, Content-Disposition. Each of these fields resides in the urn:schemas:mailheader namespace (for example, urn:schemas:mailheader:content-type and urn:schemas:mailheader:content-disposition). When accessing these fields in the collection, you must use the fully qualified names to avoid possible ambiguity. A set of string constants is provided for use when accessing fields by name in the Fields collection.
In many cases, the BodyPart object contains a unit of content for a message, whether it be an attachment, an MHTML body part, simple ASCII text, or an inline image file. To access the content contained in a BodyPart object in either encoded or decoded format, you use the IBodyPart::GetDecodedContentStream and IBodyPart::GetEncodedContentStream methods, respectively. The encoding format used is defined with the urn:schemas:mailheader:content-transfer-encoding header field.
Instances of the BodyPart COM class cannot be created directly. They are always returned by instances of the Message COM class for manipulation of a particular body part.
For messages with a single text body part, use the fields collection on the Message object to set values such as character set and encoding type. Do not use the fields collection on the BodyPart object.
The IBodyPart::DataSource property is not implemented by the BodyPart COM class provided by the CDO for Microsoft® Windows® 2000 COM library. This is because there is no exposed IDataSource interface provided by the class. Similarly, the IBodyPart::GetInterface method can only return the same IBodyPart interface that was used to call the method, and therefore performs no function on instances of the BodyPart object provided by CDO for Windows 2000.
The following code demonstrates using BodyPart objects to create a MIME-formatted message. In this case, it creates a two-part multipart/mixed message, where the first part is a multipart/alternative entity and the second is an image/gif entity. The multipart/alternative entity contains two subparts: a text/HTML subpart and a text/plain subpart.
Dim iMsg As New CDO.Message
Dim iBp As CDO.IBodyPart
Dim iBp1 As CDO.IBodyPart
Dim iBp2 As CDO.IBodyPart
Dim iFlds as ADODB.Fields
Dim iStrm as ADODB.Stream
Set iBp = iMsg ' get IBodyPart on Message object
Set iFlds = iBp.Fields
iFlds("urn:schemas:mailheader:content-type") = "multipart/mixed"
iFlds.Update
Set iBp1 = iBp.AddBodyPart ' Add a BodyPart object to the hierarchy
Set iBp2 = iBp1.AddBodyPart ' text/plain
Set iFlds = iBp2.Fields
iFlds("urn:schemas:mailheader:content-type") = "text/plain"
iFlds("urn:schemas:mailheader:content-transfer-encoding") = _
"quoted-printable"
iFlds.Update
Set iStrm = iBp2.GetDecodedContentStream
iStrm.WriteText "This is a message"
iStrm.Flush
Set iBp2 = iBp1.AddBodyPart ' text/html
Set iFlds = iBp2.Fields
iFlds("urn:schemas:mailheader:content-type") = "text/html"
iFlds("urn:schemas:mailheader:content-transfer-encoding") = _
"quoted-printable"
iFlds.Update
Set iStrm = iBp2.GetDecodedContentStream
iStrm.WriteText "<html><h1>This is a message</h1></html>"
iStrm.Flush
' This may appear out of order, but we have to _reset_ the
' content-type for the "multipart/alternative" body part after adding
' the two representations. If we set it before, it will be switched
' to "multipart/mixed" when we call the AddBodyPart() method on the
' object.
Set iFlds = iBp1.Fields
iFlds("urn:schemas:mailheader:content-type") = "multipart/alternative"
iFlds.Update
Set iBp1 = iBp.AddBodyPart ' image/gif
Set iFlds = iBp1.Fields
iFlds("urn:schemas:mailheader:content-type") = "image/gif"
iFlds("urn:schemas:mailheader:content-transfer-encoding") = "base64"
Set iStrm = iBp1.GetDecodedContentStream
iStrm.LoadFromFile "c:\images\myimage.gif"
iStrm.Flush
/*****
BuildMessageStreamAndSaveToFile()
This routine demonstrates the use
of the BodyPart object when constructing
a Message object.
Assume
%CommonProgramFiles%\system\ado
%HomeDriver%\Exchsrvr\bin
are in the include path.
Import the type libraries into the project:
#import <msado15.dll> no_namespace
#import <cdoex.dll> no_namespace
*****/
void BuildMessageStreamAndSaveToFile()
{
IMessagePtr iMsg(__uuidof(Message));
IBodyPartPtr iBp;
IBodyPartPtr iBp1;
IBodyPartPtr iBp2;
FieldsPtr Flds;
_StreamPtr Stm;
/*
** multipart/mixed (root)
*/
iBp = iMsg;
Flds = iBp->Fields;
Flds->Item["urn:schemas:mailheader:content-type"]->Value =
_bstr_t("multipart/mixed");
Flds->Update();
/*
** multipart/alternative (child of root)
*/
iBp1 = iBp->AddBodyPart(-1); // multipart/altenative body part
/*
** text/plain
*/
iBp2 = iBp1->AddBodyPart(-1); // text/plain body part
Flds = iBp2->Fields;
Flds->Item["urn:schemas:mailheader:content-type"]->Value =
_bstr_t("text/plain");
Flds->Item["urn:schemas:mailheader:content-transfer-encoding"]->Value =
_bstr_t("quoted-printable");
Flds->Update();
Stm = iBp2->GetDecodedContentStream();
Stm->WriteText(_bstr_t("text version of message"),stWriteChar);
Stm->Flush();
/*
** text/html
*/
iBp2 = iBp1->AddBodyPart(-1); // text/html body part
Flds = iBp2->Fields;
Flds->Item["urn:schemas:mailheader:content-type"]->Value =
_bstr_t("text/html");
Flds->Item["urn:schemas:mailheader:content-transfer-encoding"]->Value =
_bstr_t("quoted-printable");
Flds->Update();
Stm = iBp2->GetDecodedContentStream();
Stm->WriteText(_bstr_t("<html><p><em>html</em> version of message</p></html>"),stWriteChar);
Stm->Flush();
/*
** set multipart/alternative header
*/
Flds = iBp1->Fields;
Flds->Item["urn:schemas:mailheader:content-type"]->Value =
_bstr_t("multipart/alternative");
Flds->Update();
/*
** image/gif (child of root multipart/mixed)
*/
iBp1 = iBp->AddBodyPart(-1);
Flds = iBp1->Fields;
Flds->Item["urn:schemas:mailheader:content-type"]->Value =
_bstr_t("image/gif");
Flds->Item["urn:schemas:mailheader:content-transfer-encoding"]->Value =
_bstr_t("base64");
Flds->Update();
Stm = iBp1->GetDecodedContentStream();
try
{
Stm->LoadFromFile(_bstr_t("..\\misc\\myimage.gif"));
Stm->Flush();
}
catch(_com_error error)
{
cerr << "Error loading GIF file" << endl;
cerr << _bstr_t(error.Description()) << endl;
throw error;
}
/*
** Save message stream to disk
*/
Stm = iMsg->GetStream();
try {
Stm->SaveToFile(_bstr_t("message.eml"),adSaveCreateOverWrite);
}
catch(_com_error error) {
cerr << "Error Saving file" << endl;
cerr << _bstr_t(error.Description()) << endl;
throw error;
}
}