API Changes in Exchange Server 2003 Service Pack 2

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Thom Randolph, Microsoft Corporation

October, 2005

Summary

This technical article describes the changes in API functionality in Microsoft , and how those changes might affect your applications.

Applies To

Exchange Server 2003 SP2

Exchange Server 2003 SP2 API Changes

Changes to How Calendar Items Are Processed

Change to How Recipients Are Enumerated in Event Sinks

Change to How Invalid Content-Transfer-Encoding Values Are Handled

RTF-Encoded Messages No Longer Delete Meeting Recurrence Information

Encoding HTML Message Bodies with JIS Instead of UTF-8

Added Limitation to WebDAV XML Attributes

Introduction

Exchange Server 2003 SP2 includes new DLLs for several key APIs, and includes some key changes in behavior. While Exchange Server 2003 SP2 does not include any changes to the objects, classes, and interfaces, it does introduce key differences in how some of the APIs work.

The following API libraries that ship with Exchange Server 2003 or with Microsoft Outlook 2003 have been updated in Exchange Server 2003 SP2:

• Collaboration Data Objects for Exchange 2000 Server (CDOEX)   CDOEX ships as part of Exchange Server 2003, and must be run on the computer running Exchange Server 2003. The version of CDOEX.DLL that contains this change is 6.5.7638.2.
• Collaboration Data Objects (CDO) version 1.2.1   CDO 1.2.1 is installed by Outlook 2003 and by Exchange Server 2003. CDO 1.2.1 is not redistributable, and must be run only on computers on which Outlook 2003 or Exchange Server 2003 is installed. The version of CDO.DLL that contains this change is 6.5.7638.2.
• Exchange OLE DB (ExOLEDB) Provider   The ExOLEDB provider ships as part of Exchange Server 2003, and must be run on the computer running Exchange Server 2003. The version of the ExOLEDB provider DLL that contains this change is 6.5.7638.2.

Exchange Server 2003 SP2 API Changes

The following API libraries that ship with Exchange Server 2003 or with Microsoft Outlook 2003 have been updated in Exchange Server 2003 SP2:

• Collaboration Data Objects for Exchange 2000 Server (CDOEX)   CDOEX ships as part of Exchange Server 2003, and must be run on the computer running Exchange Server 2003. The version of CDOEX.DLL that contains this change is 6.5.7638.2.
• Collaboration Data Objects (CDO) version 1.2.1   CDO 1.2.1 is installed by Outlook 2003 and by Exchange Server 2003. CDO 1.2.1 is not redistributable, and must be run only on computers on which Outlook 2003 or Exchange Server 2003 is installed. The version of CDO.DLL that contains this change is 6.5.7638.2.
• Exchange OLE DB (ExOLEDB) Provider   The ExOLEDB provider ships as part of Exchange Server 2003, and must be run on the computer running Exchange Server 2003. The version of the ExOLEDB provider DLL that contains this change is 6.5.7638.2.

Changes to How Calendar Items Are Processed

In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, the actions taken by the Exchange server and Outlook 2003 in cached mode sometimes cause calendar items to be unexpectedly deleted. This occurs most often when a user uses multiple cached-mode e-mail clients to access a mailbox. Accepted meetings are sometimes deleted from the calendars of users running Outlook 2003 in cached mode on multiple computers, or users running a mixture of cached-mode Outlook 2003, Outlook Mobile, or mobile devices using Exchange Server ActiveSync.

This behavior occurs when one or more clients are offline when another client accepts a meeting request. For example, the following sequence of events causes a calendar item to be unintentionally deleted:

1. A user opens Outlook on a desktop computer and synchronizes the locally cached inbox, which includes a new meeting request.
2. The user closes Outlook on the desktop computer.
3. The user opens Microsoft Outlook Mobile Access on a handheld computer that is running Windows Mobile™ 2003 Software for Pocket PC and synchronizes the locally cached Inbox, retrieving another copy of the meeting request.
4. Using the handheld computer, the user accepts the meeting request. The handheld computer first creates a copy of the meeting request in the local Calendar folder, and then deletes the original request from the local Inbox folder.
5. When the handheld computer next synchronizes with the Exchange server, it transmits the copy and delete operations, which are then performed by the Exchange server on the stored mailbox.
6. The user then starts Outlook on the desktop computer, and Outlook synchronizes the mailbox with its locally cached content.
7. The first item-level synchronization operation copies the original meeting request to the calendar folder.
8. The next item-level operation deletes the meeting request. Because the Entry IDs are the same, both the Calendar and Inbox folder items are deleted.
9. Outlook acknowledges the item deletions back to the Exchange server.
10. The next time the handheld computer synchronizes with the Exchange server, the Exchange server instructs it to delete the item from the locally cached calendar.

After the synchronizations take place, all the items are deleted from the clients as well as from the Exchange server.

This problem occurs when the Exchange server and the client attempt to reconcile changes made to the locally stored copy of the initial meeting request. When multiple cached-mode clients are used to access a single mailbox, local copies of the content are stored on each client.

In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, when a user accepts a calendar item, the item is copied into the user’s Calendar folder, and then the original item is deleted from the Inbox folder. The Exchange server and the client use the Entry ID property to identify the item. If the meeting is accepted while another e-mail client is offline, the Exchange server retains the copy and delete operations so that the other clients can properly synchronize. When those other clients reconnect to the Exchange server and attempt to synchronize the user’s mailbox on the device, the system first adds the item to the user's Calendar folder, and then deletes the item. However, because both the original request (stored in the locally cached Inbox folder) and the accepted calendar item (newly added to the locally cached Calendar folder) have the same Entry ID property, the Exchange server and the client delete both items. When the original client synchronizes again, it also deletes the item from the Calendar folder.

To solve this multiple-cache synchronization problem, Exchange Server 2003 SP2 now creates a new Entry ID value when the item is accepted, tentatively accepted, or declined. The new Entry ID value is assigned regardless of where the item is stored when the action is taken. Because all the items keep the same Calendar ID property, other actions taken on the item are properly synchronized by the other clients. The original meeting request does not receive a new Entry ID value. A new Entry ID value is only applied when the action sets the acceptance status of the item. Updates to other parts of the item do not generate a new Entry ID. For example, updates affecting only the message body or meeting location, but not the acceptance status, do not affect the Entry ID.

This change is included in the Exchange Server 2003 SP2 version of CDOEX, CDO 1.2.1, and the ExOLEDB provider. If your application uses another API to process meeting requests, be sure to thoroughly test your code to ensure that it properly handles or duplicates the new behavior. If your application does not provide the copied item with a different Entry ID value, you might experience the deletion of calendar items when cached-mode synchronization takes place.

If your application code uses the Entry ID from the original meeting request item to locate calendar items after they are processed, the application might be unable to locate that item in the Calendar folder, because the Entry ID is now different. When your application is running on Exchange Server 2003 SP2, the application code must use the Calendar ID property to locate the item, because processing the item does not change the Calendar ID.

If your application cannot be updated to locate calendar items by using the Calendar ID property, you can disable the new functionality by means of a registry entry. If the registry keys do not exist, the new behavior will be in effect.

The following registry key is used by the client-side version of CDO 1.2.1 that is installed by Outlook:

HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Outlook\Options\Calendar\

The following registry key is used by the server-side version of CDO 1.2.1 that is installed by Exchange Server 2003 SP2:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows Messaging Subsystem\CDO\

The DWORD value name for CDO 1.2.1 and for Outlook is "DisableMeetingRegeneration". Nonzero values disable the new behavior.

The versions of CDOEX and Microsoft Office Outlook Web Access that are installed by Exchange Server 2003 SP2 use a different pair of registry keys. If the registry keys do not exist the new behavior will be in effect.

The following server-side registry key is used by CDOEX and Outlook Web Access:

HKEY_LOCAL_MACHINE\Software\Microsoft\EXCDO\Parameters

The DWORD value name for CDOEX and Outlook Web Access is CDOCloneOnAccept. Setting this value to zero (0) disables the new behavior.

Change to How Recipients Are Enumerated in Event Sinks

In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, when an event sink requests the list of recipients for an e-mail using the recipientlist field (https://schemas.microsoft.com/cdo/smtpenvelope/recipientlist), CDOEX in some cases incorrectly reports zero recipients when the To field contains non-SMTP formatted addresses. For example, in a message in which the To field contains the address user1, and a Bcc field of user2@example.com, CDO reports that there were zero recipients. If the To field contains the addresses user3@example.com and user1", CDO might report the number of recipients as 1. With Exchange Server 2003 SP2, recipients are enumerated correctly regardless of the format of the address.

Change to How Invalid Content-Transfer-Encoding Values Are Handled

In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, event sinks that are created by means of the ExOLEDB provider sometimes fail when replying to messages that have invalid Content-Transfer-Encoding values. In addition, the Windows Application event log contains one or more 4786 errors. The invalid encoding values typically do not affect message handling. In Exchange Server 2003 SP2, CDOEX and the ExOLEDB provider do not produce this error when an invalid content transfer encoding value is detected. The following values are valid:

• 7bit
• 8bit
• base64
• binary
• mac-binhex40
• quoted-printable
• uuencode

Invalid Content-Transfer-Encoding values are treated as if they are binary. To prevent any additional problems with encoding values from affecting your event sink–based application, always verify the message Content-Transfer-Encoding and other properties before attempting to act on the message.

RTF-Encoded Messages No Longer Delete Meeting Recurrence Information

In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, recurring meeting requests or updates encoded as Rich Text Format (RTF) can lose the recurrence information. With Exchange Server 2003 SP2, recurrence information encoded as RTF is no longer deleted and your applications can successfully send recurring meeting requests encoded as RTF.

Encoding HTML Message Bodies with JIS Instead of UTF-8

Some applications require the ability to encode the HTML body content with Japanese Industrial Standard (JIS) instead of the default 8-bit Unicode transformation format (UTF-8). In versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2, UTF-8 is the only character encoding used by CDOEX and the ExOLEDB provider. With Exchange Server 2003 SP2, the default HTML body encoding can also be set to ISO-2022 (JIS) encoding.

To use JIS encoding, set the following DWORD registry value to a nonzero integer value:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeWEB\EXOLEDB\UseISO2022JISCodepage

When this registry value is zero, or when it does not exist, UTF-8 is used to encode HTML message bodies. If the registry value exists and has a nonzero value, JIS encoding is used. This change must be made on each server that the application uses to send JIS-encoded e-mail messages.

Added Limitation to WebDAV XML Attributes

To prevent problems with WebDAV returning successful status results when it receives excessive or invalid XML attributes, Exchange Server 2003 SP2 imposes a limit on the number of XML attributes in any element in a request. A maximum of 128 attributes can be submitted in a WebDAV XML request to Exchange Server 2003 SP2. In addition, Exchange Server 2003 SP2 WebDAV no longer reports success when it encounters invalid or excessive attributes. Versions of Exchange Server 2003 earlier than Exchange Server 2003 SP2 ignore the attribute processing errors, and continue as if the attributes were not transmitted.

Conclusion

Exchange Server 2003 SP2 introduces some important changes in how some APIs work. When developing applications for Exchange Server 2003 SP2, be sure to use the versions of APIs that are compatible with the environment in which you deploy your applications.

Additional Information

[Topic Last Modified: 02/21/2007]