Microsoft Corporation
November 1997
Microsoft Corporation recognizes that developers need an object library providing greater functionality than that available in the Active Messaging 1.1 library, which shipped with Microsoft® Exchange 5.0. Developers need objects that support capabilities beyond simple messaging and into the areas of calendaring, collaboration, and workflow. Such capabilities can simplify the development of heavy-duty resource-scheduling applications requiring information to be displayed through a calendar.
In response, Microsoft has replaced its Active Messaging objects with Collaboration Data Objects (CDOs). These CDOs are available in a library known as CDO 1.2, which replaces the Active Messaging object library version 1.1 and ships with Exchange 5.5. One of the library’s key features is that applications created with Active Messaging 1.1 can run unchanged in a CDO 1.2 environment. Also available, for developers working in the Internet Information Server 4.0 environment, is a subset library of CDO 1.2 known as Collaboration Data Objects for Microsoft Windows NT® Server.
CDO 1.2 is a scripting-object library that developers can use to design collaborative applications on both the client and server side. It’s an in-process, self-registered COM server and is language-independent, compatible with Microsoft Visual Basic® Scripting Edition (VBScript), ECMAScript, Java, C/C++, Visual Basic, Visual Basic for Applications, and other languages. CDO 1.2 is also 100 percent compatible with existing applications developed against Active Messaging 1.1.
CDO 1.2 is tuned for a highly scalable, high-performance server environment. It is thread-safe, it supports multiple code pages for applications that require multiple languages, and it supports roughly 1,000 concurrent users per server. Also like Exchange 5.5, CDO 1.2 supports caching, which helps make it two to three times faster than Active Messaging 1.1.
For performance reasons, rather than having its own user interface, CDO 1.2 is accessed through Exchange 5.5. This means CDO 1.2 does not display its own dialog boxes, logon screen, or error messages.
Figure 1. CDO 1.2 is organized as a logon session consisting of two primary collections of objects: InfoStores and AddressLists. Under each, there are other objects, collections of objects, properties, and methods.
CDO 1.2 is used for streamlining the design of client applications, Web applications, and Exchange-server applications such as mailbox agents and server-event scripts, design-time controls, ActiveX® run-time controls, and others. On the client side, for example, developers have used CDO 1.2 in the design of Microsoft Outlook™ Web Access. On the server side, developers are using it for mailbox agents, which automatically process messages as they arrive at a given mailbox. Developers also are using CDO 1.2 to write server-event scripts, which provide automatic scripting when messages are deposited to or deleted from public folders.
Design-time controls provide one of the easiest ways for developers to add collaborative functionality to current Web applications. With the design-time controls available in the Microsoft Visual InterDev™ integrated Web application development system environment, developers of Web applications can add collaborative functionality without having to write any code.
For many applications, developers accustomed to working with extended MAPI (messaging application programming interface) might wonder whether they should use CDO 1.2 instead. The answer is: It depends. Extended MAPI is clearly the better choice for development in a service-provider environment; for message transport, directory, or store; or for complex, high-performance client applications. In these areas, developers would find extended MAPI the better choice because of its comprehensive functionality and performance. In contrast, for Web-based solutions and rapid applications, CDO 1.2 provides advantages unavailable in extended MAPI, such as automatic rendering of content to HTML and easy access from Visual Basic or Visual Basic for Applications.
As pointed out earlier, CDO 1.2 is compatible with all popular development environments. The only adjustment necessary is for Visual C++® development system set developers, who must use a wrapper with CDO 1.2, because it lacks dual interfaces.
CDO 1.2 provides developers two methods of access: anonymous and authenticated. Both methods provide support for Secure Sockets Layer (SSL), which is crucial for a Web development environment, because of its support for a secure session with encryption between server and client.
To support anonymous access, CDO 1.2 provides a directory object enabling developers to display a list of public folders that are available to an anonymous user. Both developers and administrators can set permissions allowing or disallowing such access to these folders. This capability is particularly useful, for example, in building Web sites to which users log on anonymously and want fast and easy access to collections of folders.
With authenticated access, users can open an Exchange mailbox using either Basic (clear text) or Windows NT Challenge Response authentication. They then are authenticated against their Windows NT user name and password before being allowed access to their Exchange server. Authenticated access enables developers to leverage Exchange and Windows NT security settings in their applications. (For more information on Internet Information Server and Active Server Pages, please visit http://www.microsoft.com/iis/.)
One important capability that is available in CDO 1.2 but not in extended MAPI is the dynamic creation of new-user profiles. Typically, new users of client-side applications have a MAPI profile stored locally, but for their server-based applications they have none. For such applications, CDO 1.2 supports the dynamic creation of a new-user profile with information obtained through prompting for user name and password. This feature is important in Web-based or roaming-user applications where MAPI profiles cannot be guaranteed to be available on the local machine.
Through its support for multiple concurrent sessions, CDO 1.2 can handle a large number of users, whether an application is a desktop-based solution developed with the Visual Basic development system or a sophisticated Web-based solution. A related CDO 1.2 feature is its ability to use existing mail client sessions. For example, client-side applications developed with CDO 1.2 can piggyback on Outlook sessions, eliminating the need for users to activate a separate logon or provide profile information.
CDO 1.2 supports file attachments in much the same way as its predecessor, Active Messaging 1.1, did. With CDO 1.2, developers can take a message and attach to it a file, a link to a file, an OLE object, or another message. They also can upload files using any RFC standard 1867 Web browser.
CDO 1.2 provides wide support for message response: the return of a new, unsent message object using Reply(), ReplyAll(), and Forward(). For example, by calling Reply (or ReplyAll) on a message object, developers are returned another message object, including the new recipient and the sender of the original message. Similarly, by calling Forward() on a message object, developers are returned a new message object, including attachments but excluding the name of a new recipient. This is the same functionality as you would expect from using forward and reply in the Outlook client.
For arranging meetings, CDO 1.2 provides a number of objects, methods, and properties. For example, to support the processing of meeting requests through a calendar, CDO 1.2 enables developers to create agents that “watch” for incoming meeting requests and automatically process them. CDO 1.2 also supports applications that use the normal Exchange mechanism of reminders to set up and process meeting requests.
CDO 1.2 distinguishes between appointments and meetings. For example, inside a calendar store are objects known as AppointmentItems, which are used for creating new appointments. When an AppointmentItem has recipients added to it, it changes into what’s known as a MeetingItem and appears in a user’s inbox as a request to attend a meeting. The user can open the message; mark it as accept, decline, or tentative; and return it to the originator. At this point, the object changes again into a MeetingResponse. Through a related method known as GetAssociatedAppointment, a user can obtain the AppointmentItem matching the MeetingItem.
Also in the CDO 1.2 calendar is the GetRecurrencePattern method, which indicates how frequently a meeting is set to occur. For a one-time meeting, a property called IsRecurring is set to false; for a recurring meeting, this property is set to true. Another property, the MeetingResponseStatus, indicates to the originator of a meeting request whether an individual has marked that request as accepted, declined, or tentative.
The MeetingItem has one method, GetAssociatedAppointment, and three properties: MeetingType, MeetingStatus, and Respond. The MeetingType property indicates whether the associated appointment is a meeting request or a meeting response. The MeetingStatus method indicates whether a meeting really is a meeting (or just an appointment), whether notice of it has been received by all invitees, and whether it has been scheduled or canceled.
The Respond method acts as kind of shortcut. That is, instead of having a MeetingItem call GetAssociatedAppointment and then respond, developers can call Respond to the MeetingItem. With this arrangement, users can respond to meeting requests programmatically.
Another major component of CDO is a set of rendering objects, which developers can use to display Exchange data in HTML format. Because they have been created in compiled MAPI c code, these objects provide a far more efficient way of coding than the alternative approach: loops created in Active Server Pages scripts. Using the CDO 1.2 rendering objects, developers can render an entire HTML page in just five lines of code—a small fraction of the code that would be required using Active Server Pages scripting.
The CDO 1.2 rendering objects also use the Active Server Response object, which renders data in the code page of the browser rather than that of the server. This makes the rendering objects crucial for developers who want to use international or foreign-language Exchange data in Web-based applications.
Figure 2. Rendering objects are central to the sophisticated workflow capabilities of CDO 1.2.
Two rendering objects constitute the CDO 1.2 rendering application: the ObjectRenderer and the ContainerRenderer. With the ObjectRenderer, developers can render individual objects, such as a Message, Folder, or AddressEntry. With the ContainerRenderer, developers can render a collection of such objects. In each case, CDO 1.2 provides formats and views to control the display of objects and information pertinent to them.
Applicable to both the ContainerRenderer and the ObjectRenderer are the DataSource property and the RenderHeadings, RenderProperty, RenderLink, and RenderPath methods. The DataSource property specifies the object to be rendered. RenderHeadings returns the column headings. RenderProperty renders HTML for a specified property by invoking the action and creating the HTML. RenderLink creates an HTML link to a particular object. RenderPath returns the path to a collection of folders or an address book.
The CDO 1.2 rendering application also supports substitution tokens that can be embedded into a string. In rendering, actual values replace the tokens. For example, to generate a link to a URL, developers can set the format of this URL and then, when it’s rendered, the values will be replaced.
Within CDO 1.2, each collection of objects has a set of views that determines how that collection is rendered to a user. For example, developers can set the DataSource property equal to a collection of folders, and CDO 1.2 will return views appropriate to folders. By default, a collection includes standard views, but also, while a user is logged on, can include custom views created dynamically using scripts. There are two classes of view objects: table view, which shows a rows and columns layout, and calendar view, which shows a daily or weekly calendar layout.
Figure 3. Using CDO 1.2 rendering objects, developers can create a dynamically generated view for an address book.
Figures 4, 5. Using CDO 1.2 rendering objects, developers can create a dynamically generated calendar view. Achieving the same end in using Active Server Pages would require many times the volume of code.
For calendar-based applications developers, CDO 1.2 provides a way to select both the month and the date through an HTML implementation of a Java applet known as the Date Navigator. CDO 1.2 also supports the automatic rendering of custom Outlook views to Web applications. With such support, developers can create rich views rapidly in the Microsoft Outlook Messaging and Information Client and make them available to their Web applications.
These scheduling and calendaring features constitute the main differences between CDO 1.2 and its predecessor, Active Messaging 1.1. Also included in the CDO 1.2 calendaring features is a single API for Outlook and Microsoft Schedule+ stores so that developers can support both products’ back ends. These objects also support recurrences, exceptions, and access to free/busy information. This means that developers can use CDO 1.2 to create virtually any application they want that users can use to schedule meetings with multiple recipients, review appointments already on a calendar, schedule new events, and so on.
Behind much of the scheduling and calendaring functionality of CDO 1.2 is an object known as the GetDefaultFolder method. This method provides developers direct access to a user’s inbox, outbox, calendar folder, task folder, contact folder, personal address book, and global address list.
While it’s important to understand the capabilities that are supported by CDO 1.2, it’s also important to understand what the library does not—or does not yet—support. In this release, CDO 1.2 does not support the following:
For developers wanting to create applications supporting fast, large-scale messaging—but not requiring advanced workflow, scheduling, calendaring, and collaborative capabilities—Microsoft provides a subset of CDO 1.2 known as CDO 1.2 for Windows NT Server. This library, which supports dual interfaces and runs in both Internet Information Server 4.0 and Exchange 5.5 environments, supports SMTP-based messaging even though it is not a full-blown mail server.
Designed for large applications such as bulk mailing and mail-enabling Web sites, Collaboration Data Objects for Microsoft Windows NT Server supports mail-based notification of events such as hard-drive space status, order/approval confirmation, reminders, system-status reporting, and Web-application integration. With such support, application users can trade mail quickly and easily with Web sites.
It’s important to understand that Collaboration Data Objects for Microsoft Windows NT Server does not conflict with existing CDO 1.2 applications. Applications created with Collaboration Data Objects for Microsoft Windows NT Server can coexist with those created with Active Messaging 1.1 or CDO 1.2. This is because Collaboration Data Objects for Microsoft Windows NT Server has no underlying MAPI infrastructure but, instead, works by itself on Internet Information Server or on a combination of Internet Information Server and Exchange. As a result, Collaboration Data Objects for Microsoft Windows NT Server is lightweight and fast and has a small footprint.
One area in which Collaboration Data Objects for Microsoft Windows NT Server differs from CDO 1.2 is anonymous messaging. Support for anonymous messaging in Collaboration Data Objects for Microsoft Windows NT Server extends to the sending of anonymous electronic mail (e-mail), while such support in CDO 1.2 stops at public folders. Collaboration Data Objects for Microsoft Windows NT Server supports anonymous e-mail through a system-wide “inbox” drop directory under Internet Information Server 4.0.
Like CDO 1.2, Collaboration Data Objects for Microsoft Windows NT Server supports plain text, HTML, and MHTML message content, UUEncoded or Base64 content and file-attachment encoding, and the creation of large bodies of text from files, URLs, or the IStream interface. For example, Collaboration Data Objects for Microsoft Windows NT Server would support an application users can use to send a message containing a Web page that looked exactly like the original, including hot links that automatically launch a browser. Through its IStream support, Collaboration Data Objects for Microsoft Windows NT Server developers can create Web-based applications that read message content directly from a hard drive.
Under Active Messaging 1.1, a minimum of 12 lines of code is required to send a message. Active Messaging 1.1 also requires developers to understand the definition of a message collection, a recipient’s collection, and an attachments collection. For many Web-page developers who want simply to design a way to send and receive simple messages, this is overly complex. Now, they can use a Collaboration Data Objects for Microsoft Windows NT Server object known as NewMail.
With the NewMail object, developers can create applications for sending a message using as little as four lines of code. Note that NewMail is specifically designed for sending a message quickly. For applications that process incoming mail, developers must enlist the wider Collaboration Data Objects for Microsoft Windows NT Server library.
Figure 6. With the NewMail object, only four lines of code are needed to send a message.
The differences between CDO 1.2 and Collaboration Data Objects for Microsoft Windows NT Server distinguish clearly the suitability of each for its respective tasks. Because it is designed specifically for Microsoft Exchange 5.5, CDO 1.2 is the better choice for doing what Exchange does best: complex messaging, conversation threading, calendaring, and other collaborative applications.
In contrast, Collaboration Data Objects for Microsoft Windows NT Server is the better choice for applications involving bulk distribution of lightweight mail or iteration through a collection of SMTP messages on Internet Information Server 4.0 or Exchange 5.5. Collaboration Data Objects for Microsoft Windows NT Server also is more suitable for processing message queues without a mail server or without hosting mailboxes. Here, the distinction between CDO 1.2 and Collaboration Data Objects for Microsoft Windows NT Server is that Exchange supports individual inboxes and Internet Information Server does not.
Note that applications developed using Collaboration Data Objects for Microsoft Windows NT Server can run as-is on a server that has been upgraded from Internet Information Server to Exchange 5.5 and that runs the SMTP ims wizard. That’s because the IMS wizard that comes with Exchange replaces the SMTP implementation of the Internet Information Server installation. Outgoing messaging also remains the same, because the code is fully compatible and it has the same functionality.
In a server that’s being upgraded from Internet Information Server 4.0 to Exchange 5.5, incoming mail is routed into a secure Exchange mailbox. As a result, administrators or developers must create mailboxes for each inbound mail address and assign Windows NT service-account permissions to those mailboxes. In addition, developers of server-based applications need to ensure that the server has the proper Windows NT permissions to open a mailbox.
Now shipping with Microsoft Exchange 5.5, CDO 1.2 provides developers an object library with far greater functionality than what is available in its predecessor, Active Messaging 1.1. With support for such capabilities as anonymous, and authenticated access, automatic generation of new-user profiles, multiple concurrent sessions and a comprehensive approach to attachment handling, message response, calendaring, and HTML rendering, CDO 1.2 can simplify the creation of sophisticated messaging, calendaring, and workflow solutions.
Collaboration Data Objects for Microsoft Windows NT Server, a subset library of CDO 1.2, provides similar capabilities for developers working in the Internet Information Server 4.0 environment. It ships with Microsoft Internet Information Server 4.0 and provides a subset of CDO 1.2 functionality.
For the latest information on Microsoft Exchange, check out our World Wide Web site at http://www.microsoft.com/exchange.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.