Microsoft KB Archive/926453

From BetaArchive Wiki
Knowledge Base


Contents

Description of the mail envelope API in 2007 Office applications

Article ID: 926453

Article Last Modified on 10/30/2006



APPLIES TO

  • Microsoft Office Outlook 2007



INTRODUCTION

Several 2007 Microsoft Office applications provide an API that lets a mail client interface with 2007 Office applications when the API is implemented by the mail client. This API provides an integrated experience for sending a copy of a 2007 Office document. If the default mail client implements the API, you can use the Microsoft Office Outlook 2007 mail envelope experience directly in 2007 Office applications.

MORE INFORMATION

For you to use the mail envelope experience directly in 2007 Office applications, the mail client must implement the following interfaces.

IMsoEnvelope

Use the IMsoEnvelope interface to host a mail envelope in an application.

Inherits from IUnknown
Provided by CLSID_OEEnvelope = {A08AF898-C2A3-11d1-BE23-00C04FA31009}
Interface identifier IID_IMsoEnvelope = {00067298-0000-0000-C000-000000000046}

Vtable order

Init Initializes the envelope
SetParent Gives the envelope the parent HWND
Resize Tells the envelope to resize
Show Tells the envelope to show itself or to hide itself
Save Tells the envelope to save its data in a stream
GetAttach This method is a no-op method and always returns S_OK
SetAttach Adds an attachment to the envelope
NewAttach This method is a no-op method and always returns S_OK
SetFocus Tells the envelope to set focus in the envelope
GetHeaderInfo Returns the information from the header
SetHeaderInfo Sets information in the header
IsDirty Indicates whether the envelope data is dirty
GetLastError Returns the error string for the given error code
DoDebug This method is a no-op method and always returns S_OK

IMsoEnvelope ::Init

The Init method initializes the envelope and gives the envelope a pointer to its host interface.

Syntax
        HRESULT STDMETHODCALLTYPE Init( 
            IUnknown __RPC_FAR *punk,
            IMsoEnvelopeSite __RPC_FAR *penvsite,
            DWORD grfInit); 
Parameters

punk
[in] IUnknown interface pointer that points to message data that is either an IStream interface or an IDispatch interface.

penvsite
[in] Pointer to the EnvelopeSite interface that hosts the envelope.

Note This object must also support the IServiceProvider interface and be able to provide the IMsoComponentManager object from a call to the QueryService method.

grfInit
[in] The following flags can be set:

  • ENV_INIT_FROMSTREAM

0x0002 // The punk parameter is an IStream interface and not an IDispatch interface.

  • ENV_INIT_DOCBEHAVIOR

0x0020 // Behaves as a document and not as a mail message.

Return values

This method returns the following values:

  • E_INVALIDARG
  • E_OUTOFMEMORY
  • E_UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelope ::SetParent

The SetParent method gives the envelope the window handle (HWND) of the parent window.

Syntax
        HRESULT STDMETHODCALLTYPE SetParent( 
            HWND hwndParent);
Parameters

hwndParent
[in] HWND of the parent window.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::Resize

The Resize method tells the envelope to resize to the passed-in size.

Syntax
        HRESULT STDMETHODCALLTYPE Resize( 
            LPCRECT prc);
Parameters

prc
[in] Rectangle in which to resize.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::Show

The Show method tells the envelope to show itself or to hide itself.

Syntax
        HRESULT STDMETHODCALLTYPE Show( 
            BOOL fShow);
Parameters

fShow
[in] Indicates whether to show the envelope or to hide the envelope.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::Save

The Save method tells the envelope to save its data in the passed-in stream.

Syntax
        HRESULT STDMETHODCALLTYPE Save( 
            IStream __RPC_FAR *pstm,
            DWORD grfSave);
Parameters

pstm
[in] Stream in which to put the data.

grfSave
[in] Flag that affects the save. This flag is not used.

Return values

This method returns the following values:

  • E_INVALIDARG
  • E_OUTOFMEMORY
  • E_UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelope ::GetAttach

The GetAttach method is a no-operation (no-op) method and always returns S_OK.

Syntax
        HRESULT STDMETHODCALLTYPE GetAttach( 
            LPCWSTR wszURL,
            IStream __RPC_FAR *__RPC_FAR *ppstm);

IMsoEnvelope ::SetAttach

The SetAttach method adds an attachment to the envelope.

Syntax
        HRESULT STDMETHODCALLTYPE SetAttach( 
            LPCWSTR wszName,
            LPCWSTR wszCID,
            IStream __RPC_FAR *__RPC_FAR *ppstm,
            DWORD __RPC_FAR *pgrfAttach);
Parameters

wszName
[in] Name of the attachment.

wszCID
[in] Content ID of the attachment.

ppstm
[out][in] Stream in which to put the attachment.

pgrfAttach
[out][in] Flags that describe the attachment. These flags are not used.

Return values

This method returns the following values:

  • E_INVALIDARG
  • E_OUTOFMEMORY
  • E_UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelope ::SetHelpMode

The SetHelpMode method is a no-operation (no-op) method and always returns S_OK.

Syntax
        HRESULT STDMETHODCALLTYPE SetHelpMode( 
            BOOL fEnter);

IMsoEnvelope ::NewAttach

The NewAttach method is a no-operation (no-op) method and always returns S_OK.

Syntax
        HRESULT STDMETHODCALLTYPE NewAttach( 
            LPCWSTR wszName,
            DWORD grfAttach);

IMsoEnvelope ::SetFocus

The SetFocus method tells the envelope to set the focus in the envelope.

Syntax
        HRESULT STDMETHODCALLTYPE SetFocus( 
            DWORD grfFocus);
Parameters

grfFocus
[in] Flag that indicates how to set the focus. The following flags can be set:

  • ENV_FOCUS_TAB

0x0001 Sets the focus in response to pressing SHIFT+TAB.

  • ENV_FOCUS_RESTORE

0x0002 Sets the focus to whatever control in the envelope most recently had the focus.

  • ENV_FOCUS_INITIAL

0x0004 Sets the focus to the initial control (the To field).

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::GetHeaderInfo

The GetHeaderInfo method returns the header information from the envelope.

Syntax
        HRESULT STDMETHODCALLTYPE GetHeaderInfo( 
            ULONG dispid,
            DWORD grfHeader,
            void __RPC_FAR *__RPC_FAR *ppv);
Parameters

dispid
[in] Header property to retrieve.

grfHeader
[in] Flags. These flags are not used.

ppv
[out] Returned information. This value is property specific. The following property is supported:

dispidSubject
0x0037 Returns the subject of the note. The ppv parameter returns a pointer to a wide string that contains the subject. The memory is allocated with the OLE task memory allocator.

Return values

This method returns the following values:

  • E_INVALIDARG
  • E_OUTOFMEMORY
  • E_UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelope ::SetHeaderInfo

The SetHeaderInfo method sets information for the envelope header.

Syntax
        HRESULT STDMETHODCALLTYPE SetHeaderInfo( 
            ULONG dispid,
            const void __RPC_FAR *pv);
Parameters

dispid
[in] Header property to set.

pv
[in] Data to be set. The type of this parameter is property specific. The following properties are used:

  • dispidSubject

0x0037 The subject of the note. The pv parameter is a pointer to a wide string that contains the subject.

  • dispidSendBtnText

0x1006 The text that is displayed on the Send button in the envelope. The pv parameter is a pointer to a side string that contains the text to put on the Send button.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::IsDirty

The IsDirty method returns a value that indicates whether the envelope is dirty.

Syntax
        HRESULT STDMETHODCALLTYPE IsDirty( void);
Return values

This method returns the following values:

  • S_OK

The envelope is dirty.

  • S_FALSE

The envelope is not dirty.

IMsoEnvelope ::GetLastError

The GetLastError method returns the error string for the passed-in error code.

Syntax
        HRESULT STDMETHODCALLTYPE GetLastError( 
            HRESULT hr,
            LPWSTR wszBuf,
            ULONG cchBuf);
Parameters

hr
[in] HRESULT value for which to obtain the display string.

wszBuf
[out][in] Buffer in which to put the string.

cchBuf
[in] Count of wide characters in the passed-in buffer.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelope ::DoDebug

The DoDebug method is a no-operation (no-op) method and always returns S_OK.

Syntax
        HRESULT STDMETHODCALLTYPE DoDebug( 
            DWORD grfDebug);

IMsoEnvelopeSite

Use the IMsoEnvelopeSite interface to let an envelope interact with a hosting application.

Inherits from IUnknown
Interface identifier IID_IMsoEnvelopeSite = {00067299-0000-0000-C000-000000000046}

Vtable order

RequestResize Requests that the host resizes the height of the envelope
CloseNote Tells the host to close the message after it sends
GetBody Obtains the body of the message
Placeholder member Not supported or documented
Placeholder member Not supported or documented
OnEnvSetFocus Tells the host that focus has been put into the envelope
DirtyToolbars Tells the host to consider the toolbars as dirty
OnPropChange Tells the host that a header property has changed
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
GetFrameWnd Asks for the HWND of the outermost frame window
Placeholder member Not supported or documented
Placeholder member Not supported or documented
TranslateAccelerators Lets a host handle translating accelerators

IMsoEnvelopeSite ::RequestResize

The RequestResize method requests that the envelope height be resized to the passed-in value.

Syntax
        HRESULT STDMETHODCALLTYPE RequestResize( 
            int __RPC_FAR *pcHeight);
Parameters

pcHeight
[out][in] Height for the envelope.

Return values

This method returns the following values:

  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::CloseNote

The CloseNote method tells the host to close the message, and the flag indicates the reason that the note is closing.

Syntax
        HRESULT STDMETHODCALLTYPE CloseNote( 
            DWORD grfClose);
Parameters

grfClose
[in] Flag that indicates why the note is closing. The value can be as follows:

ENV_CLOSE_SEND
0x0002 The note is closing because it was sent.

Return values

This method returns the following values:

  • E_ABORT
  • E_UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::GetBody

The GetBody method obtains the body of the note in a stream. A code page and flags are used to indicate which body to obtain and in what code page.

Syntax
        HRESULT STDMETHODCALLTYPE GetBody( 
            IStream __RPC_FAR *pstm,
            DWORD dwCodePage,
            DWORD grfBody);
Parameters

pstm
[in] Stream in which to put the body.

dwCodePage
[in] Code page in which to return the body.

grfBody
[in] Flags that indicate which body to return. The following flags can be set:

  • ENV_BODY_HTML

0x0001 The body is in HTML.

  • ENV_BODY_TEXT

0x0003 The body is in plain text.

Return values

This method returns the following values:

  • E_ABORT
  • E_ OUTOFMEMORY
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::OnEnvSetFocus

The OnEnvSetFocus method tells the host that the focus has been put into the envelope.

Syntax
            HRESULT STDMETHODCALLTYPE OnEnvSetFocus( void);
Return values

This method returns the following values:

  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::Dirtytoolbars

The DirtyToolbars method tells the host that something has changed and requires the toolbars to be updated.

Syntax
        HRESULT STDMETHODCALLTYPE DirtyToolbars( void);
Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::OnPropChange

The OnPropChange method tells the host that a property has been dirtied in the envelope.

Syntax
         HRESULT STDMETHODCALLTYPE OnPropChange( 
            ULONG dispid);
Parameters

dispid
[in] Microsoft COM dispatch identifier of a property that was changed. Only the following value is used:

dispidSomething
0xffffffff Indicates that an unspecified property has changed.

Return values

This method returns the following values:

  • E_ UNEXPECTED
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::GetFrameWnd

The GetFrameWnd method asks the host for the outermost frame window.

Syntax
        HRESULT STDMETHODCALLTYPE GetFrameWnd( 
            HWND __RPC_FAR *phwndFrame);
Parameters

phwndFrame
[out] HWND of the frame window.

Return values

S_OK
The call succeeded and returned the expected value or values.

IMsoEnvelopeSite ::TranslateAccelerators

The TranslateAccelerators method passes the accelerators to the host to be handled.

Syntax
        HRESULT STDMETHODCALLTYPE TranslateAccelerators( 
            MSG __RPC_FAR *pMsg);
Parameters

pMsg
[in] Message to be handed to the host.

Return values

This method returns the following values:

  • E_ UNEXPECTED
  • E_OUTOFMEMORY
  • E_ABORT
  • E_FAIL
  • S_FALSE
  • S_OK

The call succeeded and returned the expected value or values.

IMsoComponent

Use the IMsoComponent interface to let an envelope interact with a hosting application.

Inherits from IUnknown
Interface identifier IID_IMsoComponent = {000C0600-0000-0000-C000-000000000046}

Vtable order

RequestResize Requests that the host resizes the height of the envelope
FDebugMessage This method is a no-op method and always returns S_OK
FPreTanslateMessage Lets a component handle a message
OnEnterState This method is a no-op method and always returns S_OK
OnAppActivate This method is a no-op method and always returns S_OK
OnLoseActivation This method is a no-op method and always returns S_OK
OnActivationChange This method is a no-op method and always returns S_OK
FDoIdle This method is a no-op method and always returns S_OK
FContinueMessageLoop This method is a no-op method and always returns S_OK
FQueryTerminate This method is a no-op method and always returns S_OK
Terminate Tells the component that the component manager wants to terminate
HwndGetWindow Retrieves the HWND for a particular window

IMsoComponent ::FDebugMessage

The FDebugMessage method is a no-operation (no-op) method and always returns S_OK.

Syntax
    BOOL  FDebugMessage (HMSOINST hinst, 
         UINT message, WPARAM wParam, LPARAM lParam);

IMsoComponent ::FPreTranslateMessage

The FPreTranslateMessage method gives components a chance to process a message before the message is translated and is dispatched. Components can perform the TranslateAccelerator method, perform the IsDialogMessage method, modify the pMsg parameter, or take some other action.

Syntax
    BOOL  FPreTranslateMessage (MSG *pMsg);
Parameters

pMsg
[in] Message for the component to handle.

Return values

This method returns the following values:

  • TRUE

The message was consumed.

  • FALSE

The message was not consumed.

IMsoComponent ::OnEnterState

The OnEnterState method is a no-operation (no-op) method and always returns S_OK.

Syntax
    void OnEnterState( ULONG uStateID, BOOL fEnter);

IMsoComponent ::OnAppActivate

The OnAppActivate method is a no-operation (no-op) method and always returns S_OK.

Syntax
    void OnAppActivate( 
        BOOL fActive, DWORD dwOtherThreadID);

IMsoComponent ::OnLoseActivation

The OnLoseActivation method is a no-operation (no-op) method and always returns S_OK.

Syntax
    void OnLoseActivation  ();

IMsoComponent ::OnActivationChange

The OnActivationChange method is a no-operation (no-op) method and always returns S_OK.

Syntax
    void OnActivationChange( 
        IMsoComponent *pic, 
        BOOL fSameComponent,
        const MSOCRINFO *pcrinfo,
        BOOL fHostIsActivating,
        const MSOCHOSTINFO *pchostinfo, 
        DWORD dwReserved);

IMsoComponent ::FDoIdle

The FDoIdle method is a no-operation (no-op) method and always returns S_OK.

Syntax
    BOOL FDoIdle( DWORD grfidlef);

IMsoComponent ::FContinueMessageLoop

The FContinueMessageLoop method is a no-operation (no-op) method and always returns S_OK.

Syntax
    BOOL FContinueMessageLoop( 
        ULONG uReason, void *pvLoopData, MSG *pMsgPeeked);

IMsoComponent ::FQueryTerminate

The FQueryTerminate method is a no-operation (no-op) method and always returns S_OK.

Syntax
    BOOL FQueryTerminate( BOOL fPromptUser);

IMsoComponent ::Terminate

The Terminate method terminates the IMsoComponent interface’s registration. The IMsoComponent interface should revoke its registration with the component manager, release references to the component manager, and then perform any necessary cleanup.

Syntax
    void Terminate ();

IMsoComponent ::HwndGetWindow

The HwndGetWindow method is called to retrieve a window that is associated with the component. The IMsoComponent interface should return the desired window or return NULL if no such window exists.

Syntax
    HWND HwndGetWindow( 
        DWORD dwWhich, DWORD dwReserved);
Parameters

dwWhich
[in] Indicates the window for which to obtain the HWND. The possible values are as follows:

  • msocWindowFrameToplevel = 0

The multiple-document interface (MDI) applications should return the MDI frame (not the MDI client) or the application frame window. The single-document interface (SDI) applications should return the frame window that hosts the component. This should be the topmost window that owns the component.

  • msocWindowFrameOwner = 1

The msocWindowFrameOwner value is the window that owns the component. The msocWindowFrameOwner value may be the same as the window that is obtained by the msocWindowFrameTopLevel value or may be an owned window of that window.

  • msocWindowComponent = 2

The msocWindowComponent value is the main window of the component.

  • msocWindowDlgOwner = 3

The caller wishes to display a dialog box to be parented by the component. The component should return a window that is suitable for use as the dialog box's owner window.

dwReserved
The dwReserved parameter is reserved for future use and should be zero.

Return values

This method returns NULL on failures. Otherwise, this method returns the requested HWND.

IMsoComponentManager

Use the IMsoComponentManager interface to let an envelope interact with a hosting application.

Inherits from IUnknown
Interface identifier IID_IMsoComponentManager = {000C0601-0000-0000-C000-000000000046}

Vtable order

Placeholder member Not supported or documented
Placeholder member Not supported or documented
FRegisterComponent Registers a component with the component manager
FRevokeComponent Revokes the registration of a component
Placeholder member Not supported or documented
FOnComponentActivate Notifies the component manager that the component was activated
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented
Placeholder member Not supported or documented

IMsoComponentManager ::FRegisterComponent

The FRegisterComponent method registers a component and the component's registration information with the component manager.

Syntax
    BOOL FRegisterComponent(
        IMsoComponent *piComponent, const MSOCRINFO *pcrinfo, 
        DWORD *pdwComponentID);
Parameters

piComponent
[in] The IMsoComponent object that is being registered.

pcrinfo
[in] The component registration information is given in following structure.

struct _MSOCRINFO
    {
    ULONG cbSize;             // Size of MSOCRINFO structure in bytes.
    ULONG uIdleTimeInterval;  // (Not used) If msocrfNeedPeriodicIdleTime is registered
                              // in grfcrf, the component must perform
                              // periodic idle time tasks during an idle phase
                              // every uIdleTimeInterval milliseconds.
    DWORD grfcrf;           // Registration flags. Only flag used:
// msocrfPreTranslateAll = 8 must process all msgs before translation.
    DWORD grfcadvf;           // Registration advise flags.  Only flag used:
                // msocadvfRedrawOff = 2  needs redrawOff state change notif
    } MSOCRINFO;

pdwComponentID
[out] Cookie that identifies the component when the component calls other IMsoComponentManager interface methods.

Return values

This method returns the following values:

  • TRUE

Successfully registered the component.

  • FALSE

Did not register the component.

IMsoComponentManager ::FRevokeComponent

The FRevokeComponent method undoes the registration of the component that is identified by the dwComponentID parameter.

Syntax
    BOOL FRevokeComponent( DWORD dwComponentID);
Parameters

dwComponentID
[in] ID of the component being revoked.

Return values

This method returns the following values:

  • TRUE

Successfully unregistered the component.

  • FALSE

Failed when unregistering the component.

IMsoComponentManager ::FOnComponentActivate

The FOnComponentActivate method notifies the component manager that the component that is identified by the dwComponentID parameter was activated. The active component receives the change to process the messages before the messages are dispatched. Typically, the active component receives the first check at idle time after the host. The method fails when another component is already exclusively active.

Syntax
    BOOL FOnComponentActivate( DWORD dwComponentID);
Parameters

dwComponentID
[in] ID of the component being activated.

Return values

This method returns the following values:

  • TRUE

The method was executed successfully.

  • FALSE

The method failed.

IMsoEnvelopeHost

Use the IMsoEnvelopeHost interface to create an envelope note.

Inherits from IUnknown
Interface identifier IID_IMsoEnvelopeHost = {0006729A-0000-0000-C000-000000000046}

Vtable order

CreateNote Creates an enveloped note
Placeholder member Not supported or documented

Remarks

To register as an envelope host, the application should add a key for itself under the HKEY_LOCAL_MACHINE\SOFTWARE\Clients\EnvelopeHost registry key. The key should be the application name and should have a subkey that is named CLSID. The CLSID subkey should have a default value that is created to obtain the IID_ IMsoEnvelopeHost interface.

IMsoEnvelopeHost ::CreateNote

The CreateNote method creates a new enveloped note in the host application. The application should create a new blank item and then host the envelope that is requested in the blank item.

Syntax
    HRESULT CreateNote(
         IUnknown* punk,
         REFCLSID clsidCreate,
        LPCWSTR wszTheme,
        LPCWSTR wszAuthor,
        LPCWSTR wszPrefix,
        DWORD grfCreate);
Parameters

punk
[in] Not used. The value that is used should be NULL.

clsidCreate
[in] Class identifier (CLSID) of the envelope to create. The value that is used should be CLSID_OEEnvelope.

wszTheme
[in] Not used. The value that is used should be NULL.

wszAuthor
[in] Not used. The value that is used should be NULL.

wszPrefix
[in] Not used. The value that is used should be NULL.

grfCreate
[in] Not used. The value that is used should be 0.

Return values

This method returns the following values:

  • E_ UNEXPECTED
  • E_OUTOFMEMORY
  • E_ABORT
  • E_FAIL
  • S_OK

The call succeeded and returned the expected value or values.



Additional query words: OL2007 Outlook2007

Keywords: kbcode kbinfo kbapi kbexpertiseadvanced kbhowto KB926453