Message CoClass

[This is preliminary documentation and subject to change.]

Defines an object that represents a complete message.

CLSID

CD000001-8B95-11D1-82DB-00C04FB1625D

ProgID

CDO.Message

Type Library

Microsoft CDO for Windows 2000 Library
Microsoft CDO for Microsoft Exchange Library

Inproc Server

CDOSYS.DLL
CDOEX.DLL

Threading Model

Both

Implemented Interfaces

IBodyPart

IDataSource

IMessage

IRow (See Microsoft Data Access 2.5 SDK Beta)

Supported IDataSource Bindings

Remarks

Instances of the Message COM class represent a complete message. The primary and default interface on Message objects is the IMessage interface. You can use this interface to access the messaging-specific functionality of the object, including addressing the message, adding content, sending, posting, or responding to the message.

Messages contain a set of message headers that contain information such; as to whom the message is to be sent, to whom carbon copies are to be sent, and so on. The most common message header fields are present as properties on the IMessage interface, but all of these fields are accessible using the Message object's Fields collection. All fields reside in some namespace, such as urn:schemas:mailheader, for the purpose of rendering them unique. In other words, when accessing the field in the Fields collection, you must use the fully qualified name of the field, such as urn:schemas:mailheader:subject for the message subject or urn:schemas:httpmail:textdescription for the text/plain part of the message. For a complete list of predefined message header fields used with the Message COM class, see the mailheader namespace fields and httpmail namespace fields section of the reference.

The IMessage interface provides a set of top-level methods and properties designed to make creating the most common message content straightforward and intuitive. Such methods include CreateMHTMLBody, AddBodyPart, and AddAttachment. Properties include TextBody and HTMLBody.

For MIME-formatted messages, the Message object acts as the root body part of the MIME body part hierarchy. This functionality is provided through the exposed IBodyPart interface on the object. The IMessage interface provides the BodyPart property that returns this interface on the object. You can use BodyPart, the GetInterface method, or standard mechanisms such as Set (in Visual Basic), QueryInterface (in C++), or Casting (in Java) to navigate to this interface.

To facilitate the easy transfer of message data to and from other objects, the Message object provides an implementation of the IDataSource interface. Using methods and properties on this interface, you can access embedded messages in other messages, and embed messages in other messages. The IMessage interface provides the DataSource property to aid navigating to the IDataSource interface on the object.

CDO Messaging Using Exchange

CDO Messaging has additional capabilities with Exchange 2000 Server. With CDO for Exchange, access to the IDataSource interface enables you to instantiate items in Exchange folders as message objects. Thereby, populating IMessage properties and header fields with the values of the folder item; this is done with IDataSource::Open interface.

Whenever a recipient is specified for the To property, an ADO.recordset is populated with the recipient's name, address, display name, type of recipient (such as bcc), the name of any distribution list URL, name resolution status, and information from schema fields. This record set is a rich resource of delivery and report correlation information that is saved as a special body part to a message. You can access this record set with the Addressee object, perform name checking, and access the Fields collection to access schema fields. CDO automatically synchronizes information specified for the To property with the record set.

When using CDO for Exchange Server and invoking the Send method on Message and CalendarMessage objects, the following routine occurs:

1. Using OLEDB, CDO creates a message item in the sender's outbox. CDO streams the message content into the new item, it uses OLEDB to move to the sender's outbox and pointes to a sendmail:// URL.
2. From the sender's entry in Directory Services, CDO determines the URL to the sender's outbox.
3. Exchange Server delivers the message to the Internet.
4. If so configured, a copy of the message is saved to the sender's Sent Items folder.

You can post to newsgroups on the Internet through NNTP and the drop directory or you can post to Exchange public folders. The enumeration value cdoPostUsingExchange is the default.

When posting to Exchange public folders, you must specify the URL to the public folder in the To property. The Newsgroups property has no meaning in this case. You can also post to multiple public folders by specifying their URLs in a CrossPostList property accessible in the Fields collection. Multiple posting enables you to save only one item to the Web store, but have it appear in multiple folders.

Note   that there is a difference between saving to a folder and posting to a folder. Posting Sets property values such as the post date and performs validations. You can examine the X-Unsent schema field to determine if a particular item is a post.

Example

Visual Basic

Dim Msg as new CDO.Message
Dim Bp as CDO.IBodyPart

' We use the Fields collection on IMessage below
' to clarify the process.
' Each of these fields is a property
' on the IMessage interface.
' There are module constants
' in the type library for the field name strings

Dim Flds as ADODB.Fields
Set Flds = Msg.Fields
With Flds
  .Item("urn:schemas:mailheader:to")     = "someone@microsoft.com"
  .Item("urn:schemas:mailheader:from")   = "me@microsoft.com,another@microsoft.com"
  .Item("urn:schemas:mailheader:sender") = "me@microsoft.com"
  .Item("urn:schemas:mailheader:subject")= "Check this stuff out."
  .Update

  ' The Item property is the default on the Fields interface.
  ' The Value property is the default on the Field interface.
  ' That's why the above lines work.
  '  Fully expanded, it would be
  '  .Item("urn:schemas:mailheader:sender").Value = "me@microsoft.com"

End With

With Msg
  .AddAttachment("c:\somefile.ext")
  .AddAttachment("c:\anotherfile.ext2")
  .CreateMHTMLBody "http://myserver/mypage.html"
  .Send
End With
  

C++

#import "c:\program files\common files\system\ado\msado15.dll" no_namespace raw_interfaces_only
#import "c:\winnt\system32\cdosys.dll" no_namespace raw_interfaces_only
#include <cdosysstr.h>  // string constants in this file
#include <iostream.h>
#include <assert.h>

main(){
  CoInitialize(NULL);  // single-threaded apartment
  IMessage* pMsg = NULL;
  /* 
  ** Create an instance of the Message COM class
  */
  HRESULT hr = CoCreateInstance(__uuidof(Message),
                                NULL,
                                CLSCTX_INPROC_SERVER,
                                __uuidof(IMessage),
                                reinterpret_cast<void**>(&pMsg));
  assert(SUCCEEDED(hr));

  Fields* pFlds = NULL;
  pMsg->get_Fields(&pFlds);

  Field* pFld   = NULL;
  pFlds->get_Item(_variant_t("urn:schemas:mailheader:to"),&pFld);
  pFld->put_Value(_variant_t("someone@microsoft.com"));
  pFld->Release();

  pFlds->get_Item(_variant_t("urn:schemas:mailheader:from"),&pFld);
  pFld->put_Value(_variant_t("me@microsoft.com,another@micfosoft.com"));
  pFld->Release();

  pFlds->get_Item(_variant_t("urn:schemas:mailheader:sender"),&pFld);
  pFld->put_Value(_variant_t("me@microsoft.com"));
  pFld->Release();

  pFlds->get_Item(_variant_t("urn:schemas:mailheader:subject"),&pFld);
  pFld->put_Value(_variant_t("Check this stuff out"));
  pFld->Release();

  pFlds->Update();
  pFlds->Release();

  IBodyPart* pBP = NULL;
  pMsg->AddAttachment(L"c:\somefile.ext",&pBP);
  pBP->Release();
  pBP = NULL;
  
  pMsg->AddAttachment(L"c:\anotherfile.ext2",&pBP);
  pBP->Release();
  pBP = NULL;
  
  pMsg->CreateMHTMLBody(L"http://myserver/mypage.html");

  pMsg->Send();  
  pMsg->Release();
  CoUninitialize();
  return 0;
}