IBodyPart Interface

  • Article

 

IBodyPart Interface

The IBodyPart interface defines a set of methods and properties used to manipulate message body parts.

  • IID
    CD000021-8B95-11D1-82DB-00C04FB1625D
  • Extends
    IDispatch

Member Summary

Properties

Name Type Description

BodyParts

(Read-only)

IBodyParts

IBodyParts*

The BodyParts collection for this object.

Charset

String

BSTR

The character set for the text type body parts.

ContentClass

String

BSTR

The content class for the body part.

ContentClassName

String

BSTR

Deprecated (not used).

ContentMediaType

String

BSTR

The content type and subtype of the body part.

ContentTransferEncoding

String

BSTR

The encoding mechanism used to encode the content of the body part.

DataSource

(Read-only)

IDataSource

IDataSource*

The IDataSource interface on the object.

Fields

(Read-Only)

ADODB.Fields

Fields*

The Fields collection for the object.

FileName

(Read-only)

String

BSTR

The file name parameter attribute commonly used with the Content-Disposition header field.

Parent

(Read-only)

IBodyPart

IBodyPart*

The parent body part object for the object.

Methods

Name Description

AddBodyPart

Adds a BodyPart object to the BodyParts collection and returns a reference to the newly added object.

GetDecodedContentStream

Returns a Microsoft® Active X® Data Objects (ADO) Stream object (which exposes the _Stream interface) that contains the content of the body part in decoded format.

GetEncodedContentStream

Returns an ADO Stream object (which exposes the _Stream interface) containing the content of the body part in encoded format.

GetFieldParameter

Returns the specified parameter value for the specified Multipurpose Internet Mail Extensions (MIME) header field.

GetInterface

Returns the specified dual interface on the object.

GetStream

Returns an ADO Stream object (which exposes the _Stream interface) that contains the content of the body part.

SaveToFile

Saves the decoded content of the body part to a disk file.

Remarks

A message body that contains content other than plain US-ASCII text is subdivided into parts. Examples of body parts include text, attachments, inline Hypertext Markup Language (HTML) pages, alternative representations of HTML pages, and so on. The IBodyPart interface defines a set of abstract methods and properties that you can use to manipulate message body parts.

Body parts are arranged hierarchically in a message that is formatted in MIME; for example, a message that contains only text and attachments has a two-level hierarchy—the first level includes the message content and the second level contains each attachment. The IBodyPart interface supports such hierarchies by exposing the BodyParts property. Navigating down one level from an implementing object returns a collection of objects, each of which exposes the IBodyPart interface.

Each object that exposes the IBodyPart interface provides access to content in serialized format using the GetDecodedContentStream or GetEncodedContentStream methods. Both methods return an ADO Stream object (exposing a _Stream interface) that contains the content in decoded or encoded format, respectively. Content encoding depends on whether the message body is formatted using MIME or Uuencode. This operation is controlled at the Message object level using the IMessage.MIMEFormatted property.

You can also use the GetStream method to return the entire body part and all sub-parts in serialized, encoded format. For messages formatted in MIME, this stream contains the mail headers (such as Content-Type) and the content encoded using the mechanism specified by the IBodyPart.ContentTransferEncoding property.

For messages formatted in MIME, you must set the Content-Type and Content-Disposition header fields for each body part. Properties on the IBodyPart interface enable you to update these headers quickly. Such properties include the ContentMediaType property, which can be used to set the media-type portion of the Content-Type header. If the object contains a text MIME entity, you can use the Charset property to update the charset parameter that is used with the Content-Type header. Similarly, the ContentTransferEncoding property can be used to update the Content-Transfer-Encoding header for the body part; however, all of the header fields are contained in the IBodyPart.Fields collection. You can update any field or add new ones using this collection. The Fields collection returned by the IBodyPart.Fields property is a copy of the fields. To commit changes to the fields, you must call the Fields.Update method.

Example

The following example demonstrates how to manually construct the MIME structure for a message that contains two alternate representations of the message along with an attachment. You can also create the same message structure using only the IMessage.HTMLBody property and the IMessage.AddAttachment method.

  1. Create a Message object.
  2. Add two BodyPart objects to the Message object's BodyParts collection. The first has its content type set to multipart/alternative and contains the two representations of the message. The second contains the attachment.
  3. Add two BodyPart objects to the multipart/alternative BodyPart. Each contains a given representation of the message: in this case the representations are text/plain and text/html.
  4. Create a third BodyPart object at the first level and add an image (.gif) file to it. This body part contains the attachment for the message.

These steps result in the following hierarchy of MIME entities:

Message (multipart/mixed)
    BodyPart 1 (multipart/alternative)
        BodyPart 1.1 (text/plain)
        BodyPart 1.2 (text/html)
    BodyPart 2 (image/gif)
               (Content-Disposition: attachment)
' Reference to Microsoft ActiveX Data Objects 2.5 Library
' Reference to Microsoft CDO for Windows 2000 Library
Dim iMsg As New CDO.Message
Dim iBp1 As CDO.IBodyPart
Dim iBp2 As CDO.IBodyPart
Dim iBp3 as CDO.IBodyPart
Dim Stm As ADODB.Stream

With iMsg
   .From    = "example@example.com"
   .To      = "example@example.com, example2@example.com"
   .Subject = "A html and text message with attachment."
End With

''''''''''''''''''''''''''''''''
' Level 1: multipart/mixed (root)
''''''''''''''''''''''''''''''''
Set iBp = iMsg         ' returns IBodyPart on object
iBp.ContentMediaType = "multipart/mixed"


''''''''''''''''''''''''''''''''
' Level 2: multipart/alternative
''''''''''''''''''''''''''''''''
Set iBp2 = iBp.AddBodyPart
iBp2.ContentMediaType = "multipart/alternative"


''''''''''''''''''''''''''
' Level 3: text/plain
''''''''''''''''''''''''''
Set iBp3 = iBp2.AddBodyPart
With iBp3
   .ContentMediaType        = "text/plain"
   .ContentTransferEncoding = "7bit"
   Set Stm = .GetDecodedContentStream
   Stm.WriteText "Here is the plain text version of the message"
   Stm.Flush
End With


''''''''''''''''''''''''''
' Level 3: text/html
''''''''''''''''''''''''''
Set iBp3 = iBp2.AddBodyPart
With iBp3
   .ContentMediaType        = "text/html"
   .ContentTransferEncoding = "quoted-printable"
   Set Stm = .GetDecodedContentStream
   Stm.WriteText "<html><body><p>Here is the plain text version of the message</p></body></html>"
   Stm.Flush
End With


'''''''''''''''''''''''''''''
' Level 2: image/gif
'''''''''''''''''''''''''''''
Dim Flds as ADODB.Fields
Set iBp2 = iBp.AddBodyPart
With iBp2
   .ContentMediaType = "image/gif"
   .ContentTransferEncoding = "base64"
   Set Flds = iBp2.Fields
   Flds("urn:schemas:mailheader:content-disposition") = _
             "attachment; filename=""myimage.gif"""
   Flds.Update
   Set Stm = .GetDecodedContentStream
   Stm.LoadFromFile "c:\somewhere\myimage.gif"
   Stm.Flush
End With

Debug.Print iMsg.GetStream.ReadText
#import "c:\program files\common files\system\ado\msado15.dll" no_namespace
#import <cdosys.dll> no_namespace
#include <iostream.h>

void main()
{
  CoInitialize(NULL);
  {
    IMessagePtr iMsg(__uuidof(Message));
    IBodyPartPtr iBp;
    IBodyPartPtr iBp2;
    IBodyPartPtr iBp3;
    _StreamPtr   Stm;

    iMsg->From    = "example@example.com";
    iMsg->To      = "example@example.com, example2@example.com";
    iMsg->Subject = "A html and text message with attachment.";

    /*''''''''''''''''''''''''''''''''
    ' Level 1: multipart/mixed (root)
    ''''''''''''''''''''''''''''''''*/
    iBp = iMsg;
    iBp->ContentMediaType = "multipart/mixed";


    /*''''''''''''''''''''''''''''''
    ' Level 2: multipart/alternative
    ''''''''''''''''''''''''''''''''*/
    iBp2 = iBp->AddBodyPart(-1);
    iBp2->ContentMediaType = "multipart/alternative";


    /*'''''''''''''''''''''''''
    ' Level 3: text/plain
    ''''''''''''''''''''''''''*/
    iBp3 = iBp2->AddBodyPart(-1);
    iBp3->ContentMediaType        = "text/plain";
    iBp3->ContentTransferEncoding = "7bit";
    Set Stm = iBp3->GetDecodedContentStream();
    Stm->WriteText(
                   "Here is the plain text version of the message",
                   adWriteChar
                  );
    Stm->Flush();


    /*'''''''''''''''''''''''''
    ' Level 3: text/html
    '''''''''''''''''''''''''*/
    iBp3 = iBp2->AddBodyPart(-1);
    iBp3->ContentMediaType        = "text/html";
    iBp3->ContentTransferEncoding = "quoted-printable";
    Stm = iBp3->GetDecodedContentStream();
    Stm->WriteText(
                   "<html><body><p>Here is the plain text version of the message</p></body></html>",
                   adWriteChar
                  );
    Stm->Flush();


    /*''''''''''''''''''''''''''''
    ' Level 2: image/gif
    '''''''''''''''''''''''''''''*/
    iBp2 = iBp->AddBodyPart(-1);
    iBp2->ContentMediaType = "image/gif";
    iBp2->ContentTransferEncoding = "base64";
    Stm = iBp2->GetDecodedContentStream();
    Stm->LoadFromFile("c:\somewhere\myimage.gif");
    Stm->Flush();

    // print message stream
    cout << iMsg->GetStream()->ReadText(-1) << endl;
  }
  CoUninitialize();
}
Dim iMsg
Dim iBp1
Dim iBp2
Dim iBp3
Dim Stm

Set iMsg = CreateObject("CDO.Message")

With iMsg
   .From    = "example@example.com"
   .To      = "example@example.com, example2@example.com"
   .Subject = "A html and text message with attachment."
End With

''''''''''''''''''''''''''''''''
' Level 1: multipart/mixed (root)
''''''''''''''''''''''''''''''''
Set iBp = iMsg.BodyPart
iBp.ContentMediaType = "multipart/mixed"


''''''''''''''''''''''''''''''''
' Level 2: multipart/alternative
''''''''''''''''''''''''''''''''
Set iBp2 = iBp.AddBodyPart
iBp2.ContentMediaType = "multipart/alternative"


''''''''''''''''''''''''''
' Level 3: text/plain
''''''''''''''''''''''''''
Set iBp3 = iBp2.AddBodyPart
With iBp3
   .ContentMediaType        = "text/plain"
   .ContentTransferEncoding = "7bit"
   Set Stm = .GetDecodedContentStream
   Stm.WriteText "Here is the plain text version of the message"
   Stm.Flush
End With


''''''''''''''''''''''''''
' Level 3: text/html
''''''''''''''''''''''''''
Set iBp3 = iBp2.AddBodyPart
With iBp3
   .ContentMediaType        = "text/html"
   .ContentTransferEncoding = "quoted-printable"
   Set Stm = .GetDecodedContentStream
   Stm.WriteText "<html><body><p>Here is the plain text version of the message</p></body></html>"
   Stm.Flush
End With


'''''''''''''''''''''''''''''
' Level 2: image/gif
'''''''''''''''''''''''''''''
Dim Flds
Set iBp2 = iBp.AddBodyPart
With iBp2
   .ContentMediaType = "image/gif"
   .ContentTransferEncoding = "base64"
   Set Flds = iBp2.Fields
   Flds("urn:schemas:mailheader:content-disposition") = "attachment; filename=""myimage.gif"""
   Flds.Update
   Set Stm = .GetDecodedContentStream
   Stm.LoadFromFile "c:\somewhere\myimage.gif"
   Stm.Flush
End With

Wscript.Echo iMsg.GetStream.ReadText

See Also

Reference

ADO Stream Object

Concepts

IMessage Interface
BodyPart CoClass
Message CoClass