Microsoft KB Archive/266353

= The support guidelines for client-side messaging development =

Article ID: 266353

Article Last Modified on 3/30/2007

-

APPLIES TO


 * Microsoft Messaging Application Programming Interface
 * Microsoft Office Outlook 2007
 * Microsoft Office Outlook 2003
 * Microsoft Outlook 2002 Standard Edition
 * Microsoft Outlook 2000 Standard Edition
 * Microsoft Outlook 98 Standard Edition
 * Microsoft Outlook 97 Standard Edition
 * Microsoft Collaboration Data Objects 1.21
 * Microsoft Outlook Express 5.0
 * Microsoft Outlook Express 5.5
 * Microsoft Outlook Express 6.0

-



This article was previously published under Q266353



INTRODUCTION
This article describes what is supported and what is not supported when you develop custom solutions that integrate with Microsoft-based messaging products or Microsoft technologies. This article also contains most of the key information to be aware of when you develop with Microsoft products and Microsoft technologies. However, this article does not cover all scenarios. Contact Microsoft Customer Support Services if you have any questions about whether a specific solution is supported.

This article also discusses specific technologies and specific scenarios to provide guidance to developers.



MORE INFORMATION
The term &quot;supported&quot; is used to describe whether Microsoft Customer Support Services or Microsoft Services can help you when you try to achieve something in a specific way. Typically, the term is also used in the context of whether a Microsoft product group will potentially fix an issue for a given scenario.

Because of the large matrix of products, technologies, and versions that require testing, we cannot say that all scenarios have been designed or tested. Therefore, we encourage you to use the following best practices when you design custom solutions:
 * Only use APIs that are documented by Microsoft. This avoids the increased risk that your solution will not function together with a newer version of a product or together with a service pack for a product. For example, you can use the Microsoft Win32 API to manipulate Microsoft Office Outlook windows. However, the Win32 API is not supported. Some solutions may be supported within the context of the specific API that you use. However, these solutions typically are not supported within the context of an Office application and when you create a custom solution by using that application. An exception would be a scenario that is documented by Microsoft.
 * Avoid mixing newer technologies and older technologies if you can do this. Mixing newer technologies and older technologies increases the possibility that the scenario was not tested and that the scenario is not supported.
 * When you work with Office applications, develop the solution by using the oldest version of Office that runs the solution.

Integrating with Outlook properties
Outlook, Microsoft Exchange Server, and other Microsoft products store data in MAPI stores, such as personal folders (.pst) files, Exchange mailbox stores, or Exchange public folder stores. Although some of this data is visible, various other data is not visible and is stored for other reasons.

In some cases, there is a one-to-one correspondence between what you see in Outlook and what is stored in the underlying MAPI database. The Subject box of an e-mail message is an example of this because this box corresponds to the PR_SUBJECT MAPI property. In this case, this property predates Outlook because this property was used by previous Microsoft e-mail clients. Other properties also have a one-to-one correspondence but are specific to Outlook. For example, a contact’s Web site address is stored in a specific MAPI named property.

Note For more information about named properties in Outlook, see the &quot;MAPI-specific information for named properties&quot; section.

In some cases, Outlook may use multiple MAPI properties to store information for a specific purpose, or Outlook may store multiple pieces of information in one property. In both of these scenarios, frequently there is no documentation that explains how these properties are implemented or how they function.

Programmatically changing the underlying properties involves some risk. The main areas include the following:
 * Outlook may experience unexpected behavior or stop responding when some properties are changed.
 * Problems may occur when various APIs are used to dynamically change some Outlook properties while Outlook is running.
 * Different versions of Outlook may connect to the same MAPI stores. Therefore, there may be added complexity because different versions of Outlook may interact with related properties in different ways.

Therefore, many MAPI properties that are used by Outlook are not documented at the MAPI level. The MAPI schema that is used is complex and may change with later versions MAPI.

Therefore, we recommend that you avoid accessing this low-level data directly and that you use a high-level API instead, such as the Outlook object library. Because of these factors, Microsoft generally does not support explaining how or why the underlying properties are implemented.

It is also important to differentiate between reading properties and writing properties. Programmatically reading MAPI properties by using APIs such as Extended MAPI, WebDAV, or the PropertyAccessor object in the Microsoft Office Outlook 2007 object model is supported. However, writing to those properties is not supported because of the potential for data corruption issues or for other problems that other MAPI clients may have when they use the modified data.

MAPI-specific information for named properties
MAPI provides a facility for assigning names to certain properties, for mapping these names to unique identifiers, and for making this mapping persistent. Outlook writes many Outlook-specific fields into these named properties that use identifiers in the 8000-FFFE range. Typically, the Microsoft Outlook object model is the only supported method of changing these named properties. Typically, changing these properties by using MAPI or by using Collaboration Data Objects (CDO) is not supported.

Named properties are identified by a name and by a GUID for a property set. The name can be a number or a string. These properties are manipulated by using the IMAPIProp::GetIDsFromNames function and the IMAPIProp::GetNamesFromIDs function. The GUID and the name are passed to the GetIDsFromNames function to obtain a property ID that is valid for the current MAPI session. Because this property ID can vary from computer to computer, the only consistent way to access a named property is to know its property set and its name.

Typically, named properties are used by Outlook clients as a way to add extra information to a message that is only used by that client. Therefore, most of the named properties that are used by Outlook clients are not documented. The only supported way to obtain these properties is through the Outlook object model.

Common named properties that are used by Outlook
The following table describes the common named properties that are used by Outlook.

In addition to the properties that are native to MAPI, user-defined fields on customized Outlook forms are supported through MAPI, through CDO, through WebDAV, and through the Outlook object model. These fields use the PS_PUBLIC_STRINGS property as the property set identifier and the name of the field as the property name. For more information about supportability scenarios for WebDAV-based data and for MAPI-based data, click the following article number to view the article in the Microsoft Knowledge Base:

920134 Available support for applications that use the WebDAV protocol to access Exchange 2000 Server or Exchange Server 2003

The Outlook Integration API provides additional documentation for integrating with Outlook in specific scenarios. To view this documentation, visit the following Microsoft Web site:

http://msdn2.microsoft.com/en-us/library/aa193231(office.11).aspx

Additionally, the following information is documented for Outlook 2007 and is scheduled to be included in the Outlook Integration API at a later date. For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

919198 Notification-based indexing support for store providers in Outlook 2007

919199 How to use the IAttachmentSecurity API to verify whether an attachment is considered to be blocked in Outlook

For more information, visit the following Microsoft Web sites:

Outlook 2007 documentation - Blocked attachments

http://blogs.msdn.com/stephen_griffin/archive/2006/05/09/593585.aspx

Outlook 2007 documentation - Notification based indexing support

http://blogs.msdn.com/stephen_griffin/archive/2006/05/10/594641.aspx

Microsoft Office Outlook 2003 Service Pack 1 (SP1) or later versions
For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

912239 How to use the dispidHeaderItem MAPI property to identify the state of a message that you receive in Outlook 2003

912238 How to use MAPI to manage messages in a .pst file when you are using Outlook 2003 to download messages from an IMAP server

912237 How to use named properties to relate Contact Address Book entries to e-mail messages, e-mail addresses, and picture attachments in Outlook 2003

915314 Information about two new named property definitions that can control how a message is processed by Office Outlook 2003 when users reply to the message

908074 How to use Extended MAPI to manage messages in an OST when the client is in cached Exchange mode in Office Outlook 2003

For more information, visit the following Microsoft Web sites:

New Outlook documentation part 5 - One-off forms

http://blogs.msdn.com/stephen_griffin/archive/2005/12/29/507991.aspx

Outlook 2003 Integration API wrapped PST documents and sample

http://blogs.msdn.com/stephen_griffin/archive/2005/09/28/Outlook-2003-Integration-API-Wrapped-PST-Docs-and-Sample.aspx

APIs that are supported in managed code
MAPI was originally designed and originally developed in the late 1980s. Therefore, MAPI predates managed code in the Microsoft .NET Framework. We do not provide managed wrappers for MAPI, and we discourage you from using third-party wrappers. This is because solutions may seem to work in a test environment, but issues that are related to memory management may occur when an application is deployed in a production environment and is exposed to real-world scalability scenarios.

The following table summarizes the support policy for Outlook APIs in the .NET Framework environment.

For more information about the support policies for other messaging APIs in managed code, click the following article number to view the article in the Microsoft Knowledge Base:

813349 Support policy for Microsoft Exchange APIs with .NET Framework applications

The .NET Framework user controls
The .NET Framework user controls are not supported in Outlook 2003, in earlier versions of Outlook, or in Outlook 2007 custom form regions. For more information about support for these controls, click the following article number to view the article in the Microsoft Knowledge Base:

897863 Description of the supportability of Winforms controls in unmanaged applications

Custom forms and HTTP scenarios for Outlook 2003 and for earlier versions of Outlook
In Outlook, custom Outlook forms are not supported for use with HTTP-based mail services such as Microsoft Hotmail. Outlook does not prevent you from using custom form features if you are using an HTTP-based mail service. However, some features do not work correctly. The features do not work correctly because HTTP-based mail messages are stored in a read-only state on the server. Therefore, we recommend that you do not use custom Outlook forms if you are using an HTTP-based mail service.

Microsoft Visual Basic 6.0 MAPI controls
Visual Basic 6.0 MAPI controls are based on Simple MAPI and are no longer tested or supported starting in Outlook 2007. We encourage you to use a newer API for e-mail solutions.

Note The standard support for Visual Basic 6.0 has expired.

Common Messaging Calls
Common Messaging Calls (CMC) is not supported after the release of the Outlook e-mail security update in June 2000.

Dynamic Data Exchange (DDE)
Unlike other Office applications, Outlook does not support Dynamic Data Exchange (DDE) as a way to programmatically communicate with Outlook.

Microsoft Outlook Express (Microsoft Windows XP)
For a long time, the only supported API for Outlook Express was Simple MAPI. Simple MAPI is a set of functions and the related data structures that you can use to add messaging functionality to custom applications. The Simple MAPI functions are available in versions for C, for C++, and for Visual Basic.

The documentation for Simple MAPI is provided in the Microsoft Exchange SDK. To view this documentation, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mapi/html/835175ab-a4c3-46ca-b069-b581dc445604.asp

Outlook Express uses Windows Address Book (WAB). For more information about Windows Address Book, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/WAB/wab/overviews/wabovw.asp

Windows Mail in Windows Vista
In Windows Vista, Windows Mail is the replacement for Outlook Express. For developer documentation, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/OutlookExpress/oe/oe_entry_point.asp

APIs that are available for Outlook Express 6.0 are also included in this documentation.

Windows Live APIs and SDKs
For more information about the APIs that are related to e-mail and about the support options for Windows Live, visit the following Microsoft Web site:

http://dev.live.com/

Microsoft Customer Support currently does not provide support for these APIs.

