Lesson 1: CDO for Exchange 2000 Server

CDO for Exchange 2000 Server is a fundamental technology for messaging solutions based on the Web Storage System. You can manage folders, messages, and other items. CDOEX supports RFC 822, Multipurpose Internet Mail Extensions (MIME), iCalendar, and vCard formats. The new CDO is closely related to ADO. Their combination is the key to unfolding the full potential of Exchange 2000 Server.

This lesson compares CDO to ADO 2.5 and then introduces typical CDO features. This lesson provides small VBScript code examples that illustrate how to send messages, handle appointments and meeting requests, and deal with contact information.

---

At the end of this lesson, you will be able to:

• Decide when to use CDO and ADO in a business solution.
• Handle messaging, calendaring, and contact management via CDO.

Estimated time to complete this lesson: 60 minutes

---

ActiveX Data Objects Versus Collaboration Data Objects

Database developers that need to access Exchange 2000 Server will find ADO very convenient to use. ADO 2.5 works similarly in Exchange 2000 Server, Microsoft Access, or Microsoft SQL Server environments. You can access items in mailbox and public folders similar to discrete rows in database tables. ADO allows you to navigate through record sets, control individual records, save generic items, and so on. As a classic database interface, however, ADO does not provide explicit messaging functionality. You can read more about ADO in Chapter 23, "Microsoft Exchange 2000 Web Storage System."

CDO was designed specifically with messaging and collaboration in mind. It is a set of Component Object Model (COM)-based interfaces that allow you to perform actions such as sending messages, managing contacts, scheduling appointments, handling meeting requests, creating folders, and so on. CDO is the ideal choice to implement workflow and other collaborative applications.

It is advantageous to use both ADO and CDO in your applications where appropriate. CDO objects can be bound to ADO objects directly. Any changes made with CDO can be saved back to ADO. Only one session is required to work with both technologies. This helps minimize resource consumption and increase performance.

Consider using CDO instead of ADO in the following scenarios:

• To encode data using Internet standard transfer formats, such as MIME Base64 (which replaced the legacy Unix-to-Unix encoding method [UUENCODE]), and plain text, quoted-printable (which encodes data similar to US ASCII and results in human readable text).
• To implement business logic that is optimized for messaging and collaboration instead of structured databases.
• To implement calendars, appointments, meeting requests, and contact management.
• To simplify working with the raw data in item streams. CDO formats streams for messages, appointments, and contacts based on Internet standard formats automatically and recreates streams when item properties are changed. ADO does not synchronize message streams with item properties.

NOTE

---

You can use both CDO and ADO to access Exchange 2000 Server resources. Both technologies rely on ExOLEDB and use the features of the Web Storage System (see Figure 24.1).

Figure 24.1 Using ADO and CDO for messaging and collaboration

CDO for Exchange 2000 Server Object Model

CDO for Exchange 2000 Server is implemented in CDOEX.DLL, which can be found in the \Program Files\Common Files\Microsoft Shared\Cdo directory. The main interfaces that this component exports are used to form Folder and Message, Appointment, and Person CoClasses (see Figure 24.2). Detailed information about CDO objects is available in the Microsoft Exchange 2000 Server Platform Software Development Kit (SDK).

Figure 24.2 The CDO for Exchange 2000 Server Object Model

The Configuration COM Class

A central component in the CDOEX object model is the Configuration CoClass, which allows you to manage configuration settings used with most of the other CDOEX objects. The Configuration object holds specific information in its fields collection, which represents a set of ADO Field objects. The most important configuration fields are defined in the namespace: http://schemas.microsoft.com/cdo/configuration/.

NOTE

---

Namespaces do not correspond to Web sites.

An important field that you may want to set explicitly corresponds to the http://schemas.microsoft.com/cdo/configuration/sendusing/ property. It can be set to cdoSendUsingPickup (1), cdoSendUsingPort (2), or cdoSendUsingExchange (3). When you set it to cdoSendUsingPickup, new messages are placed in the local Simple Mail Transfer Protocol (SMTP) service's pickup directory. Specify cdoSendUsingPort if you want to connect to the SMTP service via TCP port 25 (if you overwrite the port by using the http://schemas.microsoft.com/cdo/configuration/smtpserverport/ property, you also need to identify the target SMTP host via http://schemas.microsoft.com/cdo/configuration/smtpserver/). The default value, however, is cdoSendUsingExchange, which causes CDO to pass new messages to the Information Store service.

NOTE

---

To send messages to recipients in your Exchange 2000 Server organization, use cdoSendUsingExchange (the default). When sending messages to Internet recipients, however, you may get better performance by using SMTP directly (cdoSendUsingPickup or cdoSendUsingPort). Sending messages through the SMTP service also allows you to specify a nonexisting sender address for anonymous messages.

When sending messages via Exchange 2000 Server (cdoSendUsingExchange), the following configuration information may also be important:

• http://schemas.microsoft.com/cdo/configuration/mailboxurl . Points to the URL of the user's mailbox, such as http://bluesky-srv1/Exchange/Administrator/. Setting this property explicitly increases performance. If it is not set, CDO must query the Active Directory directory service to locate the user's mailbox.
• http://schemas.microsoft.com/cdo/configuration/sendusername/. Identifies the mailbox-enabled user account to be used to send messages. The value of this property can have the form User@<Domain Name>, mailto:User@<Domain Name>, or <NT Domain Name>\User. Among other things, the sendusername is used to determine the user's mailbox URL if the mailboxurl configuration property was not specified.
• http://schemas.microsoft.com/cdo/configuration/activeconnection/. Enables you to increase the performance of CDO. You can bind an ADO connection object to the user's mailbox and specify it in the activeconnection configuration property. Otherwise, a new connection object must be created whenever you send messages, which is automatically destroyed afterward.
• http://schemas.microsoft.com/cdo/configuration/sendpassword. Allows you to specify the user's password for authentication with system services, such as Active Directory.

The following code snippet sets the important configuration properties for the Administrator account in the test environment of Blue Sky Airlines (SCRIPT1CH24.VBS):

 '*-*-* Definition of CDO constants for VBScript *-*-* const cdoSendUsingMethod = _   " http://schemas.microsoft.com/cdo/configuration/sendusing" const cdoSendUserName = _   "http://schemas.microsoft.com/cdo/configuration/sendusername" const cdoActiveConnection = _   "http://schemas.microsoft.com/cdo/configuration/activeconnection" const cdoSendPassword = _   "http://schemas.microsoft.com/cdo/configuration/sendpassword" const cdoMailboxURL = _   "http://schemas.microsoft.com/cdo/configuration/mailboxurl" const cdoSendUsingExchange = 3 '*-*-* Creation of an explicit ADO Connection *-*-* '*-*-* This object must point to the user's mailbox *-*-* Set oConn = CreateObject("ADODB.Connection") oConn.Provider = "ExOLEDB.DataSource" oConn.Open _ "file://./BackOfficeStorage/bluesky-inc-10.com/MBX/Administrator/" '*-*-* The actual CDO code *-*-* Set oConf = CreateObject("CDO.Configuration") Set oFlds = oConf.Fields oFlds (cdoSendUsingMethod) = cdoSendUsingExchange oFlds (cdoSendUserName) = "[e-mail]" oFlds (cdoActiveConnection) = oConn oFlds (cdoSendPassword) = "password" oFlds (cdoMailboxURL) = "http://bluesky-srv1/Exchange/Administrator/" oFlds.Update 

NOTE

---

CDO for Exchange 2000 Server can determine your current user information automatically when testing program code locally on the server. In this case, you do not have to specify configuration parameters explicitly.

Sending CDO Messages

It is remarkably easy to work with messages using the Message CoClass of CDOEX. The following code example creates and sends an outbound message with an attachment to Carl Titmouse. At a minimum, a recipient address and the originator address must be specified before you can invoke the Send method. Of course, it is also helpful to specify a subject and message text.

The following VBScript example creates and sends a message with an attachment to Carl Titmouse (SCRIPT2CH24.VBS):

 Set oMsg = CreateObject ("CDO.Message") oMsg.From = "[e-mail]" oMsg.To = "[e-mail]" oMsg.Subject = "CDO for Exchange 2000 Server" oMsg.TextBody = "It is remarkably easy to construct" _      & " and send messages using CDO for Exchange 2000 Server." oMsg.AddAttachment("c:\winnt\clock.avi") oMsg.Send 

NOTE

---

If you want to test this code snippet in a .vbs file, you need to log on as Administrator to BLUESKY-SRV1. Because a CDO Configuration object was not used, sender information will be obtained from the currently logged on user. If you want to test this code in conjunction with the Configuration object created in the previous snippet, insert the following line after Set oMsg = CreateObject ("CDO.Message"): Set oMsg.Configuration = oConf.

Sending messages involves the following tasks:

1. CDO creates a message item in the originator's Outbox using ExOLEDB.
2. The message content is streamed into the newly created item.
3. The Information Store is informed to transfer the message.
4. A copy of the message may be saved to the Sent Items folder.

CDO Calendaring

CDO for Exchange 2000 Server provides three objects that allow you to work with calendar information Appointment, CalendarMessage, and Addressee. Appointments are discrete items that you can create in private and public calendar folders. CalendarMessage works similar to a normal CDO message, with the exception that it contains a CalendarParts attachment, which provides information about the appointment. A more intuitive name for CalendarMessage would be meeting request. Addressee objects allow you to resolve address information into recipients, which in turn provide access to free/busy information.

It is important to note that CDO sends meeting requests in iCalendar format according to RFC 2445. This provides for highest interoperability between users who have different calendar applications. Exchange 2000 Server is able to convert iCalendar items to meeting requests in MAPI format. In addition, CDO places a plaintext version of the meeting request in the message body. You can overwrite the default text, however, using the TextBody property as demonstrated for a CDO.Message object in the previous code example.

The following VBScript example creates an appointment in the Administrator's Calendar folder and sends a meeting request for this appointment to Carl Titmouse (SCRIPT3CH24.VBS):

 '*-*-* Definition of CDO constants for VBScript *-*-* const cdoRequiredParticipant = 0 const cdoSendEmailAddress = _   "http://schemas.microsoft.com/cdo/configuration/sendemailaddress" '*-*-* Creating a Configuration object *-*-* Set oConf = CreateObject ("CDO.Configuration") oConf.Fields(cdoSendEmailAddress) = "[e-mail]" oConf.Fields.Update '*-*-* Creating the appointment *-*-* Set oAppt = CreateObject ("CDO.Appointment") Set oAppt.Configuration = oConf oAppt.StartTime = #12/31/2000 22:30:00 PM# oAppt.EndTime = #01/01/2001 2:30:00 AM# oAppt.Subject = "Happy New Year" oAppt.TextBody = "Our Annual New Year Party" '*-*-* Inviting additional users *-*-* Set oAttendee = oAppt.Attendees.Add oAttendee.Address = "[e-mail]" oAttendee.Role = cdoRequiredParticipant '*-*-* Sending a meeting request *-*-* Set oCalMsg = oAppt.Publish oCalMsg.Message.To = "[e-mail]" oCalMsg.Message.Subject = "New Year Party" oCalMsg.Message.TextBody = "Come to our annual New Year Party!" oCalMsg.Message.Send '*-*-* Saving the appointment in the Calendar folder *-*-* oAppt.DataSource.SaveToContainer _ "file://./BackOfficeStorage/bluesky-inc-10.com" _      & "/MBX/Administrator/calendar/" 

To successfully send meeting requests to attendees, you need to specify the default e-mail address of the message sender (cdoSendEmailAddress) in a Configuration object and add this object to the appointment. You should also ensure that the left half of the sender's SMTP address is specified in the file URL of SaveToContainer. This is not necessarily the user's Windows 2000 account name. For instance, if the Administrator account has an SMTP address of [e-mail], you need to specify a URL of "file://./BackOfficeStorage/bluesky-inc-10.com/MBX/Admin/calendar/". Otherwise, SaveToContainer may return CDO error &H80040E19.

Contact Management

The CDO Person object is also interesting. It enables you to create and manage contact information through the Web Storage System. You can also work with contact objects in Active Directory. The only difference is that you need to specify an LDAP URL that points to a directory object instead of a file URL that references an item in a mailbox or public store. Lesson 2 covers management of user-related directory information in greater detail.

The following VBScript example creates a contact object in the Administrator's Contacts folder (SCRIPT4CH24.VBS):

 '*-*-* Creating a CDO Person object *-*-* Set oPerson = CreateObject("CDO.Person") '*-*-* Specifying Person properties *-*-* oPerson.FirstName = "Phil" oPerson.LastName = "Pheasant" oPerson.WorkCity = "Miami" oPerson.WorkState = "Florida" oPerson.WorkPostalCode = "33120" oPerson.WorkStreet = "23415 SE 19th Street" oPerson.WorkPhone = "(305) 123456789" oPerson.WorkFax = "(305) 987654321" oPerson.Email = "[e-mail]" oPerson.Fields("objectClass").Value = "contact" oPerson.Fields.Update '*-*-* Saving the CDO Person object in the Contacts folder *-*-* oPerson.DataSource.SaveToContainer _ "  file://./BackOfficeStorage/bluesky-inc-10.com" _    & "/MBX/Administrator/Contacts/" 

For compatibility with third-party contact management applications, Person objects provide a GetVCardStream method, which gives you access to the contents in vCard-compliant MIME format.

The following VBScript example retrieves a vCard-compliant stream from the Administrator account and saves it to a file on the server's file system (SCRIPT5CH24.VBS):

 Set oPerson = CreateObject("CDO.Person") oPerson.DataSource.Open_ "LDAP://bluesky-srv1.BlueSky-inc-10.com/"_ &"CN=Administrator,CN=Users,DC=BlueSky-inc-10,DC=com" oPerson.GetVcardStream.SaveToFile "c:\adm_vcard.txt"