OL98: New Optional Programming Interface Supported for Outlook Extensions (216693)

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

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