Microsoft KB Archive/216693

= OL98: New Optional Programming Interface Supported for Outlook Extensions =

Article ID: 216693

Article Last Modified on 1/24/2007

-

APPLIES TO


 * Microsoft Outlook 97 Standard Edition
 * Microsoft Outlook 98 Standard Edition

-



This article was previously published under Q216693



SYMPTOMS
Client extensions built for the Exchange Client may not function reliably when used with Outlook.

Outlook 8.04 adds a new programming interface that can be used by client extension developers. This new interface allows hooking of the OnOpen, OnOpenComplete, OnClose and OnCloseComplete actions. Support of this interface permits Outlook extensions to receive notifications when an item inspector is opened for viewing. This functionality was previously unavailable in the Exchange Client Extensions interface. Through this new interface, the extension can also suppress the item from being opened for viewing.



CAUSE
Prior to adding this new interface to Outlook, Exchange Client extensions attempted to recognize that a message was brought into view by receiving OnRead notifications. The Exchange client did all user transactions through the store. OnRead was called when the user was composing, reading, replying, or forwarding. Onread hooked into the MAPI layer. This is not always reliable, and does not work with the Outlook client. For example, Outlook does not access the store for the initial compose operation.



RESOLUTION
A supported fix is now available from Microsoft, but it is only intended to correct the problem that is described in this article. Apply it only to computers that are experiencing this specific problem. This fix may receive additional testing. Therefore, if you are not severely affected by this problem, Microsoft recommends that you wait for the next release of Outlook that contains this hotfix.

To resolve this problem immediately, contact Microsoft Product Support Services to obtain the fix. For a complete list of Microsoft Product Support Services phone numbers and information about support costs, visit the following Microsoft Web site:

http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMS

NOTE: In special cases, charges that are ordinarily incurred for support calls may be canceled if a Microsoft Support Professional determines that a specific update will resolve your problem. The typical support costs will apply to additional support questions and issues that do not qualify for the specific update in question.

  File Name     Version -  Outllib.dll   8.3.1.5107    Outlook 97 Outllib.dll  8.5.00.5109   Outlook 98



STATUS
Microsoft has confirmed that this is a problem in the Microsoft products that are listed at the beginning of this article.



MORE INFORMATION
Outlook supports four new functions through this extension interface:
 * OnOpen
 * OnOpenComplete
 * OnClose
 * OnCloseComplete

If an extension implements this optional interface, the functions are called by Outlook as follows:

OnOpen
OnOpen is called whenever the item is about to be brought into view. The extension may return S_FALSE or E_ABORT, but should not return any other result code. Returning S_OK may break other extensions that implement these same interfaces. If the extension returns S_FALSE, Outlook will proceed to open the item (unless some other extension or user action cancels the operation). If the extension returns E_ABORT, then the Open operation is aborted and the item is not brought into view.

OnOpenComplete
Like any other completion routine, OnOpenComplete is called after the OnOpen method is called for all extensions. This informs the extension that no other extensions or user operation has decided to cancel the call. There are three values that can be passed to OnOpenComplete. They are 0, EEME_FAILED, and EEME_COMPLETE_FAILED. If 0 is passed, then the action has not (yet) been canceled. The other two values indicate that the Open operation has been aborted. The Open operation may be aborted after the OnOpenComplete(0) has been called, in which case OnOpenComplete will get called again with EEME_COMPLETE_FAILED. OnOpenComplete may be called any number of times, and the last one indicates the success or failure of the original OnOpen operation. OnOpenComplete(EEME_*_FAILED)may be called without an OnOpen call of some other extension canceled the OnOpen before your extension has been called. All of the completion routines behave this way.

OnClose
OnClose is called when the item's window has been requested to be closed. Like OnOpen, an extension may return S_FALSE or E_ABORT. A result code of S_OK is not defined, and may break other extensions.

OnCloseComplete
Outlook will follow up with a call to OnCloseComplete after OnClose, indicating success or failure. The last call to OnCloseComplete indicates the true success or failure. If OnCloseComplete(EEME_*_FAILED) is called, then the item remains in an Open state and is still visible to the user. An extension's item context cannot consider itself "closed for good" until its Release method has been called an its reference count has become 0.

The more formal definition of this optional extension interface is: EXTERN_C const IID IID_IOutlookExtItemEvents;

interface IOutlookExtItemEvents : public IUnknown {   public: virtual HRESULT __stdcall OnOpen(            /* [in] */ IExchExtCallback __RPC_FAR *peecb) = 0; virtual HRESULT __stdcall OnOpenComplete(            /* [in] */ IExchExtCallback __RPC_FAR *peecb,            /* [in] */ ULONG ulFlags) = 0; virtual HRESULT __stdcall OnClose(            /* [in] */ IExchExtCallback __RPC_FAR *peecb,            /* [in] */ ULONG ulSaveOptions) = 0; virtual HRESULT __stdcall OnCloseComplete(            /* [in] */ IExchExtCallback __RPC_FAR *peecb,            /* [in] */ ULONG ulFlags) = 0; };

// uuid(0006723A-0000-0000-C000-000000000046) DEFINE_OLEGUID(IID_IOutlookExtItemEvents,  MAKELONG(0x7000+(0x23A),0x0006),0,0);

In order for these events to be fired from Outlook, they must be declared in the extension's ECF file. Specifically, Misc Flags should include OutlookCommands and the [Item] section should have OnOpen and OnClose as Events. The following ECF snippet illustrates this:

[General] Display Name=MyExtension Description=MyExtension Path="MyExtension.dll" Entry Point=1 Client Version=4.0 Misc Flags=NoOptimizeInterfaceMap;MoreContexts;InstallCommandsEarly;WarnIfNoDLL;OutlookCommands

[Item] Message Class=IPM Item States=Modal;NonModal;Read;Compose Events=OnOpen;OnClose

Additional query words: 98

Keywords: kbbug kbfix kbqfe KB216693

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.