/**************************************************************************** Copyright 1994-2000 Microsoft Corporation. All Rights Reserved. File: olecm.idl Contents: This file describes the OLE Component Manager interfaces ****************************************************************************/ #ifndef INTEROPLIB import "oleidl.idl"; import "servprov.idl"; import "oaidl.idl"; import "docobj.idl"; import "designer.idl"; import "textmgr.idl"; import "oleipc.idl"; #endif /**************************************************************************** Component integration structures and constants ****************************************************************************/ // Component registration flags enum _OLECRF { olecrfNeedIdleTime = 1, // needs idle time olecrfNeedPeriodicIdleTime = 2, // needs idle time every N milliseconds olecrfPreTranslateKeys = 4, // must process keyboard msgs // before translation olecrfPreTranslateAll = 8, // must process all msgs // before translation olecrfNeedSpecActiveNotifs = 16, // needs to be notified for special // activation changes (currently, this will // notify comp if ExclusiveBorderSpace // or ExclusiveActivation mode changes) // Top-level comps should reg this flag. olecrfNeedAllActiveNotifs = 32, // needs to be notified for every // change in activation state olecrfExclusiveBorderSpace = 64, // needs exclusive border space when // active (normally only used by TopLevel // Mac components) olecrfExclusiveActivation = 128, // comp becomes exclusively active // when activated }; typedef DWORD OLECRF; // Component registration advise flags (see olecstate enumeration) enum _OLECADVF { olecadvfModal = 1, // needs modal state change notification // (must be registered by components // managing a toplevel window) olecadvfRedrawOff = 2, // needs redrawOff state change notif olecadvfWarningsOff = 4, // needs warningsOff state change notif olecadvfRecording = 8, // needs Recording state change notif }; typedef DWORD OLECADVF; // Component registration information typedef struct _OLECRINFO { ULONG cbSize; // size of OLECRINFO structure in bytes. ULONG uIdleTimeInterval; // If olecrfNeedPeriodicIdleTime is registered // in grfcrf, component needs to perform // periodic idle time tasks during an idle phase // every uIdleTimeInterval milliseconds. OLECRF grfcrf; // bit flags taken from olecrf values (above) OLECADVF grfcadvf; // bit flags taken from olecadvf values (above) } OLECRINFO; // Component Host flags enum _OLECHOSTF { olechostfExclusiveBorderSpace = 1, // needs exclusive border space when // active (normally only used by // TopLevel Mac hosts) }; typedef DWORD OLECHOSTF; // Component Host information typedef struct _OLECHOSTINFO { ULONG cbSize; // size of OLECHOSTINFO structure in bytes. OLECHOSTF grfchostf; // bit flags taken from olechostf values (above) } OLECHOSTINFO; // idle flags, passed to IOleComponent::FDoIdle and // IOleStdComponentMgr::FDoIdle. enum _OLEIDLEF { oleidlefPeriodic = 1, // periodic idle tasks oleidlefNonPeriodic = 2, // any nonperiodic idle task oleidlefPriority = 4, // high priority, nonperiodic idle tasks oleidlefAll = -1 // all idle tasks }; typedef DWORD OLEIDLEF; // Reasons for pushing a message loop, passed to // IOleComponentManager::FPushMessageLoop and // IOleComponentHost::FPushMessageLoop. The host should remain in message // loop until IOleComponent::FContinueMessageLoop // (or IOleStdComponentMgr::FContinueMessageLoop) returns FALSE. enum _OLELOOP { oleloopFocusWait = 1, // component is activating host oleloopDoEvents = 2, // component is asking host to process messages oleloopDebug = 3, // component has entered debug mode oleloopModalForm = 4 // component is displaying a modal form }; typedef ULONG OLELOOP; /* olecstate values: state IDs passed to IOleComponent::OnEnterState, IOleComponentManager::OnComponentEnterState/FOnComponentExitState/FInState, IOleComponentHost::OnComponentEnterState, IOleStdComponentMgr::OnHostEnterState/FOnHostExitState/FInState. When the host or a component is notified through one of these methods that another entity (component or host) is entering or exiting a state identified by one of these state IDs, the host/component should take appropriate action: olecstateModal (modal state): If app is entering modal state, host/component should disable its toplevel windows, and reenable them when app exits this state. Also, when this state is entered or exited, host/component should notify approprate inplace objects via IOleInPlaceActiveObject::EnableModeless. olecstateRedrawOff (redrawOff state): If app is entering redrawOff state, host/component should disable repainting of its windows, and reenable repainting when app exits this state. olecstateWarningsOff (warningsOff state): If app is entering warningsOff state, host/component should disable the presentation of any user warnings, and reenable this when app exits this state. olecstateRecording (Recording state): Used to notify host/component when Recording is turned on or off. */ enum _OLECSTATE { olecstateModal = 1, // modal state; disable toplevel windows olecstateRedrawOff = 2, // redrawOff state; disable window repainting olecstateWarningsOff = 3, // warningsOff state; disable user warnings olecstateRecording = 4, // Recording state }; typedef ULONG OLECSTATE; /* ** Comments on State Contexts ** IOleComponentManager::FCreateSubComponentManager allows one to create a hierarchical tree of component managers. This tree is used to maintain multiple contexts with regard to olecstateXXX states. These contexts are referred to as 'state contexts'. Each component manager in the tree defines a state context. The components registered with a particular component manager or any of its descendents live within that component manager's state context. Calls to IOleComponentManager::OnComponentEnterState/FOnComponentExitState can be used to affect all components, only components within the component manager's state context, or only those components that are outside of the component manager's state context. IOleComponentManager::FInState is used to query the state of the component manager's state context at its root. oleccontext values: context indicators passed to IOleComponentManager::OnComponentEnterState/FOnComponentExitState. These values indicate the state context that is to be affected by the state change. In IOleComponentManager::OnComponentEnterState/FOnComponentExitState, the comp mgr informs only those components/host that are within the specified state context. */ enum _OLECCONTEXT { oleccontextAll = 0, // all state contexts in state context tree oleccontextMine = 1, // component manager's state context oleccontextOthers = 2, // all other state contexts outside of comp mgr's }; typedef ULONG OLECCONTEXT; /* ** WM_MOUSEACTIVATE Note (for top level compoenents and host) ** If the active (or tracking) comp's reg info indicates that it wants mouse messages, then no MA_xxxANDEAT value should be returned from WM_MOUSEACTIVATE, so that the active (or tracking) comp will be able to process the resulting mouse message. If one does not want to examine the reg info, no MA_xxxANDEAT value should be returned from WM_MOUSEACTIVATE if any comp is active (or tracking). One can query the reg info of the active (or tracking) component at any time via IOleComponentManager::FGetActiveComponent. */ /* olegac values: values passed to IOleComponentManager::FGetActiveComponent. */ enum _OLEGAC { olegacActive = 0, // retrieve true active component olegacTracking = 1, // retrieve tracking component olegacTrackingOrActive = 2, // retrieve tracking component if one exists, // otherwise retrieve true active component }; typedef DWORD OLEGAC; /* olecWindow values: values passed to IOleComponent::HwndGetWindow. */ enum _OLECWINDOW { olecWindowFrameToplevel = 0, /* MDI Apps should return the MDI frame (not MDI client) or App frame window, and SDI Apps should return the frame window which hosts the component. Basically it should be the topmost window which owns the component. For a toolbar set this will be the toplevel owner of TBS::m_hwnd. */ olecWindowFrameOwner = 1, /* This is the window which owns the component. It could be same as the window obtained by olecWindowFrameTopLevel or be an owned window of that window. For a toolbar set this will be TBS::m_hwnd. */ olecWindowComponent = 2, /* This is the "main" window of the component (if it has one). */ olecWindowDlgOwner = 3, /* Caller wishes to display a dialog to be parented by the component. Component should return a window suitable for use as the dialog's owner window. */ }; typedef DWORD OLECWINDOW; /**************************************************************************** Defines the IOleComponent interface Any component that needs idle time, the ability to process messages before they are translated (for example, to call TranslateAccelerator or IsDialogMessage), notification about modal states, or the ability push message loops must implement this interface and register with the Component Manager. ****************************************************************************/ [ uuid(000C0600-0000-0000-C000-000000000046), version(1.0), pointer_default(unique), local ] interface IOleComponent : IUnknown { /* Reserved method. Use "Return TRUE" as implementation of this method. */ BOOL FReserved1( [in] DWORD dwReserved, [in] UINT message, [in] WPARAM wParam, [in] LPARAM lParam); /* Give component a chance to process the message pMsg before it is translated and dispatched. Component can do TranslateAccelerator, do IsDialogMessage, modify pMsg, or take some other action. Return TRUE if the message is consumed, FALSE otherwise. */ BOOL FPreTranslateMessage ([in, out] MSG *pMsg); #if MAC /* Give Macintosh component a chance to process the event pEvt before it is processed by the host. Return TRUE if the event is consumed, FALSE otherwise. (WLM components can simply return FALSE.) */ BOOL FPreProcessMacEvent(EventRecord *pEvt); #endif // MAC /* Notify component when app enters or exits (as indicated by fEnter) the state identified by uStateID (a value from olecstate enumeration). Component should take action depending on value of uStateID (see olecstate comments, above). Note: If n calls are made with TRUE fEnter, component should consider the state to be in effect until n calls are made with FALSE fEnter. Note: Components should be aware that it is possible for this method to be called with FALSE fEnter more times than it was called with TRUE fEnter (so, for example, if component is maintaining a state counter (incremented when this method is called with TRUE fEnter, decremented when called with FALSE fEnter), the counter should not be decremented for FALSE fEnter if it is already at zero.) */ void OnEnterState ([in] OLECSTATE uStateID, [in] BOOL fEnter); /* Notify component when the host application gains or loses activation. If fActive is TRUE, the host app is being activated and dwOtherThreadID is the ID of the thread owning the window being deactivated. If fActive is FALSE, the host app is being deactivated and dwOtherThreadID is the ID of the thread owning the window being activated. Note: this method is not called when both the window being activated and the one being deactivated belong to the host app. */ void OnAppActivate( [in] BOOL fActive, [in] DWORD dwOtherThreadID); /* Notify the active component that it has lost its active status because the host or another component has become active. */ void OnLoseActivation (); /* Notify component when a new object is being activated. If pic is non-NULL, then it is the component that is being activated. In this case, fSameComponent is TRUE if pic is the same component as the callee of this method, and pcrinfo is the reg info of pic. If pic is NULL and fHostIsActivating is TRUE, then the host is the object being activated, and pchostinfo is its host info. If pic is NULL and fHostIsActivating is FALSE, then there is no current active object. If pic is being activated and pcrinfo->grf has the olecrfExclusiveBorderSpace bit set, component should hide its border space tools (toolbars, status bars, etc.); component should also do this if host is activating and pchostinfo->grfchostf has the olechostfExclusiveBorderSpace bit set. In either of these cases, component should unhide its border space tools the next time it is activated. If pic is being activated and pcrinfo->grf has the olecrfExclusiveActivation bit is set, then pic is being activated in "ExclusiveActive" mode. Component should retrieve the top frame window that is hosting pic (via pic->HwndGetWindow(olecWindowFrameToplevel, 0)). If this window is different from component's own top frame window, component should disable its windows and do other things it would do when receiving OnEnterState(olecstateModal, TRUE) notification. Otherwise, if component is top-level, it should refuse to have its window activated by appropriately processing WM_MOUSEACTIVATE (but see WM_MOUSEACTIVATE NOTE, above). Component should remain in one of these states until the ExclusiveActive mode ends, indicated by a future call to OnActivationChange with ExclusiveActivation bit not set or with NULL pcrinfo. */ void OnActivationChange( [in] IOleComponent *pic, [in] BOOL fSameComponent, [in] const OLECRINFO *pcrinfo, [in] BOOL fHostIsActivating, [in] const OLECHOSTINFO *pchostinfo, [in] DWORD dwReserved); /* Give component a chance to do idle time tasks. grfidlef is a group of bit flags taken from the enumeration of oleidlef values (above), indicating the type of idle tasks to perform. Component may periodically call IOleComponentManager::FContinueIdle; if this method returns FALSE, component should terminate its idle time processing and return. Return TRUE if more time is needed to perform the idle time tasks, FALSE otherwise. Note: If a component reaches a point where it has no idle tasks and does not need FDoIdle calls, it should remove its idle task registration via IOleComponentManager::FUpdateComponentRegistration. Note: If this method is called on while component is performing a tracking operation, component should only perform idle time tasks that it deems are appropriate to perform during tracking. */ BOOL FDoIdle([in] OLEIDLEF grfidlef); /* Called during each iteration of a message loop that the component pushed. uReason and pvLoopData are the reason and the component private data that were passed to IOleComponentManager::FPushMessageLoop. This method is called after peeking the next message in the queue (via PeekMessage) but before the message is removed from the queue. The peeked message is passed in the pMsgPeeked param (NULL if no message is in the queue). This method may be additionally called when the next message has already been removed from the queue, in which case pMsgPeeked is passed as NULL. Return TRUE if the message loop should continue, FALSE otherwise. If FALSE is returned, the component manager terminates the loop without removing pMsgPeeked from the queue. */ BOOL FContinueMessageLoop( [in] OLELOOP uReason, [in] void *pvLoopData, [in] MSG *pMsgPeeked); /* Called when component manager wishes to know if the component is in a state in which it can terminate. If fPromptUser is FALSE, component should simply return TRUE if it can terminate, FALSE otherwise. If fPromptUser is TRUE, component should return TRUE if it can terminate without prompting the user; otherwise it should prompt the user, either 1.) asking user if it can terminate and returning TRUE or FALSE appropriately, or 2.) giving an indication as to why it cannot terminate and returning FALSE. */ BOOL FQueryTerminate( [in] BOOL fPromptUser); /* Called when component manager wishes to terminate the component's registration. Component should revoke its registration with component manager, release references to component manager and perform any necessary cleanup. */ void Terminate(); /* Called to retrieve a window associated with the component, as specified by dwWhich, a olecWindowXXX value (see olecWindow, above). dwReserved is reserved for future use and should be zero. Component should return the desired window or NULL if no such window exists. */ HWND HwndGetWindow( [in] OLECWINDOW dwWhich, [in] DWORD dwReserved); }; /**************************************************************************** Defines the IOleComponentManager interface A component manager is an object implementing the IOleComponentManager interface. The component manager coordinates components with its message loop for proper distribution of idle time and pre-translation message processing. It also coordinates modalities and the pushing of message loops. ****************************************************************************/ [ uuid(000C0601-0000-0000-C000-000000000046), version(1.0), pointer_default(unique), local ] interface IOleComponentManager : IUnknown { /* Return in *ppvObj an implementation of interface iid for service guidService (same as IServiceProvider::QueryService). Return NOERROR if the requested service is supported, otherwise return NULL in *ppvObj and an appropriate error (eg E_FAIL, E_NOINTERFACE). */ HRESULT QueryService( [in] REFGUID guidService, [in] REFIID iid, [out] void **ppvObj); /* Reserved method. Use "Return TRUE" as implementation of this method. */ BOOL FReserved1([in] DWORD dwReserved, [in] UINT message, [in] WPARAM wParam, [in] LPARAM lParam); /* Register component piComponent and its registration info pcrinfo with this component manager. Return in *pdwComponentID a cookie which will identify the component when it calls other IOleComponentManager methods. Return TRUE if successful, FALSE otherwise. */ BOOL FRegisterComponent( [in] IOleComponent *piComponent, [in] const OLECRINFO *pcrinfo, [out] DWORD_PTR *pdwComponentID); /* Undo the registration of the component identified by dwComponentID (the cookie returned from the FRegisterComponent method). Return TRUE if successful, FALSE otherwise. */ BOOL FRevokeComponent( [in] DWORD_PTR dwComponentID); /* Update the registration info of the component identified by dwComponentID (the cookie returned from FRegisterComponent) with the new registration information pcrinfo. Typically this is used to update the idle time registration data, but can be used to update other registration data as well. Return TRUE if successful, FALSE otherwise. */ BOOL FUpdateComponentRegistration ( [in] DWORD_PTR dwComponentID, [in] const OLECRINFO *pcrinfo); /* Notify component manager that component identified by dwComponentID (cookie returned from FRegisterComponent) has been activated. The active component gets the chance to process messages before they are dispatched (via IOleComponent::FPreTranslateMessage) and typically gets first crack at idle time after the host. This method fails if another component is already Exclusively Active. In this case, FALSE is returned and SetLastError is set to oleerrACompIsXActive (comp usually need not take any special action in this case). Return TRUE if successful. */ BOOL FOnComponentActivate( [in] DWORD_PTR dwComponentID); /* Called to inform component manager that component identified by dwComponentID (cookie returned from FRegisterComponent) wishes to perform a tracking operation (such as mouse tracking). The component calls this method with fTrack == TRUE to begin the tracking operation and with fTrack == FALSE to end the operation. During the tracking operation the component manager routes messages to the tracking component (via IOleComponent::FPreTranslateMessage) rather than to the active component. When the tracking operation ends, the component manager should resume routing messages to the active component. Note: component manager should perform no idle time processing during a tracking operation other than give the tracking component idle time via IOleComponent::FDoIdle. Note: there can only be one tracking component at a time. Return TRUE if successful, FALSE otherwise. */ BOOL FSetTrackingComponent( [in] DWORD_PTR dwComponentID, [in] BOOL fTrack); /* Notify component manager that component identified by dwComponentID (cookie returned from FRegisterComponent) is entering the state identified by uStateID (olecstateXXX value). (For convenience when dealing with sub CompMgrs, the host can call this method passing 0 for dwComponentID.) Component manager should notify all other interested components within the state context indicated by uContext (a oleccontextXXX value), excluding those within the state context of a CompMgr in rgpicmExclude, via IOleComponent::OnEnterState (see "Comments on State Contexts", above). Component Manager should also take appropriate action depending on the value of uStateID (see olecstate comments, above). dwReserved is reserved for future use and should be zero. rgpicmExclude (can be NULL) is an array of cpicmExclude CompMgrs (can include root CompMgr and/or sub CompMgrs); components within the state context of a CompMgr appearing in this array should NOT be notified of the state change (note: if uContext is oleccontextMine, the only CompMgrs in rgpicmExclude that are checked for exclusion are those that are sub CompMgrs of this Component Manager, since all other CompMgrs are outside of this Component Manager's state context anyway.) Note: Calls to this method are symmetric with calls to FOnComponentExitState. That is, if n OnComponentEnterState calls are made, the component is considered to be in the state until n FOnComponentExitState calls are made. Before revoking its registration a component must make a sufficient number of FOnComponentExitState calls to offset any outstanding OnComponentEnterState calls it has made. Note: inplace objects should not call this method with uStateID == olecstateModal when entering modal state. Such objects should call IOleInPlaceFrame::EnableModeless instead. */ void OnComponentEnterState( [in] DWORD_PTR dwComponentID, [in] OLECSTATE uStateID, [in] OLECCONTEXT uContext, [in] ULONG cpicmExclude, [in] IOleComponentManager **rgpicmExclude, [in] DWORD dwReserved); /* Notify component manager that component identified by dwComponentID (cookie returned from FRegisterComponent) is exiting the state identified by uStateID (a olecstateXXX value). (For convenience when dealing with sub CompMgrs, the host can call this method passing 0 for dwComponentID.) uContext, cpicmExclude, and rgpicmExclude are as they are in OnComponentEnterState. Component manager should notify all appropriate interested components (taking into account uContext, cpicmExclude, rgpicmExclude) via IOleComponent::OnEnterState (see "Comments on State Contexts", above). Component Manager should also take appropriate action depending on the value of uStateID (see olecstate comments, above). Return TRUE if, at the end of this call, the state is still in effect at the root of this component manager's state context (because the host or some other component is still in the state), otherwise return FALSE (ie. return what FInState would return). Caller can normally ignore the return value. Note: n calls to this method are symmetric with n calls to OnComponentEnterState (see OnComponentEnterState comments, above). */ BOOL FOnComponentExitState( [in] DWORD_PTR dwComponentID, [in] OLECSTATE uStateID, [in] OLECCONTEXT uContext, [in] ULONG cpicmExclude, [in] IOleComponentManager **rgpicmExclude); /* Return TRUE if the state identified by uStateID (a olecstateXXX value) is in effect at the root of this component manager's state context, FALSE otherwise (see "Comments on State Contexts", above). pvoid is reserved for future use and should be NULL. */ BOOL FInState([in] OLECSTATE uStateID, [in] void *pvoid); /* Called periodically by a component during IOleComponent::FDoIdle. Return TRUE if component can continue its idle time processing, FALSE if not (in which case component returns from FDoIdle.) */ BOOL FContinueIdle(); /* Component identified by dwComponentID (cookie returned from FRegisterComponent) wishes to push a message loop for reason uReason. uReason is one the values from the oleloop enumeration (above). pvLoopData is data private to the component. The component manager should push its message loop, calling IOleComponent::FContinueMessageLoop(uReason, pvLoopData) during each loop iteration (see IOleComponent::FContinueMessageLoop comments). When IOleComponent::FContinueMessageLoop returns FALSE, the component manager terminates the loop. Returns TRUE if component manager terminates loop because component told it to (by returning FALSE from IOleComponent::FContinueMessageLoop), FALSE if it had to terminate the loop for some other reason. In the latter case, component should perform any necessary action (such as cleanup). */ BOOL FPushMessageLoop( [in] DWORD_PTR dwComponentID, [in] OLELOOP uReason, [in] void *pvLoopData); /* Cause the component manager to create a "sub" component manager, which will be one of its children in the hierarchical tree of component managers used to maintiain state contexts (see "Comments on State Contexts", above). piunkOuter is the controlling unknown (can be NULL), riid is the desired IID, and *ppvObj returns the created sub component manager. piunkServProv (can be NULL) is a ptr to an object supporting IServiceProvider interface to which the created sub component manager will delegate its IOleComponentManager::QueryService calls. (see objext.h or docobj.h for definition of IServiceProvider). Returns TRUE if successful. */ BOOL FCreateSubComponentManager( [in] IUnknown *piunkOuter, [in] IUnknown *piunkServProv, [in] REFIID riid, [out] void **ppvObj); /* Return in *ppicm an AddRef'ed ptr to this component manager's parent in the hierarchical tree of component managers used to maintain state contexts (see "Comments on State Contexts", above). Returns TRUE if the parent is returned, FALSE if no parent exists or some error occurred. */ BOOL FGetParentComponentManager( [out] IOleComponentManager **ppicm); /* Return in *ppic an AddRef'ed ptr to the current active or tracking component (as indicated by dwgac (a olegacXXX value)), and its registration information in *pcrinfo. ppic and/or pcrinfo can be NULL if caller is not interested these values. If pcrinfo is not NULL, caller should set pcrinfo->cbSize before calling this method. Returns TRUE if the component indicated by dwgac exists, FALSE if no such component exists or some error occurred. dwReserved is reserved for future use and should be zero. */ BOOL FGetActiveComponent( [in] OLEGAC dwgac, [out] IOleComponent **ppic, [in, out] OLECRINFO *pcrinfo, [in] DWORD dwReserved); }; // The Service Identifier (SID) for OleCompoentManager is different // than the IIDs, so we can't do a simple define here. // The following line will get the symbol declared. It is defined // in olecmid.c which is built into vsguids.lib. If you link that // lib the symbol will be defined. cpp_quote("EXTERN_C const IID SID_SOleComponentManager;")