Microsoft KB Archive/926453

= 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.

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.

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.

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.

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.

Remarks
To register as an envelope host, the application should add a key for itself under the  registry key. The key should be the application name and should have a subkey that is named. The  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

-

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

© Microsoft Corporation. All rights reserved.