IAxWinHostWindow Interface

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at IAxWinHostWindow Interface.

This interface provides methods for manipulating a control and its host object.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

interface IAxWinHostWindow : IUnknown

Members

Methods

AttachControl	Attaches an existing control to the host object.
CreateControl	Creates a control and attaches it to the host object.
CreateControlEx	Creates a control, attaches it to the host object, and optionally sets up an event handler.
QueryControl	Returns an interface pointer to the hosted control.
SetExternalDispatch	Sets the external IDispatch interface.
SetExternalUIHandler	Sets the external IDocHostUIHandlerDispatch interface.

Remarks

This interface is exposed by ATL's ActiveX control hosting objects. Call the methods on this interface to create and/or attach a control to the host object, to get an interface from a hosted control, or to set the external dispinterface or UI handler for use when hosting the Web browser.

Requirements

The definition of this interface is available as IDL or C++, as shown below.

Definition type	File
IDL	ATLIFace.idl
C++	ATLIFace.h (also included in ATLBase.h)

IAxWinHostWindow::AttachControl

Attaches an existing (and previously initialized) control to the host object using the window identified by hWnd.

STDMETHOD(AttachControl)(IUnknown* pUnkControl, HWND hWnd);

Parameters

pUnkControl
[in] A pointer to the IUnknown interface of the control to be attached to the host object.

hWnd
[in] A handle to the window to be used for hosting.

Return Value

A standard HRESULT value.

IAxWinHostWindow::CreateControl

Creates a control, initializes it, and hosts it in the window identified by hWnd.

STDMETHOD(CreateControl)(
    LPCOLESTR lpTricsData,
    HWND hWnd,
    IStream* pStream);

Parameters

lpTricsData
[in] A string identifying the control to create. Can be a CLSID (must include the braces), ProgID, URL, or raw HTML (prefixed by MSHTML:).

hWnd
[in] A handle to the window to be used for hosting.

pStream
[in] An interface pointer for a stream containing initialization data for the control. Can be NULL.

Return Value

A standard HRESULT value.

Remarks

This window will be subclassed by the host object exposing this interface so that messages can be reflected to the control and other container features will work.

Calling this method is equivalent to calling IAxWinHostWindow::CreateControlEx.

To create a licensed ActiveX control, see IAxWinHostWindowLic::CreateControlLic.

IAxWinHostWindow::CreateControlEx

Creates an ActiveX control, initializes it, and hosts it in the specified window, similar to IAxWinHostWindow::CreateControl.

STDMETHOD(CreateControlEx)(
    LPCOLESTR lpszTricsData,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnk,
    REFIID riidAdvise,
    IUnknown* punkAdvise);

Parameters

lpTricsData
[in] A string identifying the control to create. Can be a CLSID (must include the braces), ProgID, URL, or raw HTML (prefixed with MSHTML:).

hWnd
[in] A handle to the window to be used for hosting.

pStream
[in] An interface pointer for a stream containing initialization data for the control. Can be NULL.

ppUnk
[out] The address of a pointer that will receive the IUnknown interface of the created control. Can be NULL.

riidAdvise
[in] The interface identifier of an outgoing interface on the contained object. Can be IID_NULL.

punkAdvise
[in] A pointer to the IUnknown interface of the sink object to be connected to the connection point on the contained object specified by iidSink.

Return Value

A standard HRESULT value.

Remarks

Unlike the CreateControl method, CreateControlEx also allows you to receive an interface pointer to the newly created control and set up an event sink to receive events fired by the control.

To create a licensed ActiveX control, see IAxWinHostWindowLic::CreateControlLicEx.

IAxWinHostWindow::QueryControl

Returns the specified interface pointer provided by the hosted control.

STDMETHOD(QueryControl)(REFIID riid, void** ppvObject);

Parameters

riid
[in] The ID of an interface on the control being requested.

ppvObject
[out] The address of a pointer that will receive the specified interface of the created control.

Return Value

A standard HRESULT value.

IAxWinHostWindow::SetExternalDispatch

Sets the external dispinterface, which is available to contained controls through the IDocHostUIHandlerDispatch::GetExternal method.

STDMETHOD(SetExternalDispatch)(IDispatch* pDisp);

Parameters

pDisp
[in] A pointer to an IDispatch interface.

Return Value

A standard HRESULT value.

IAxWinHostWindow::SetExternalUIHandler

Call this function to set the external IDocHostUIHandlerDispatch interface for the CAxWindow object.

STDMETHOD(SetExternalUIHandler)(IDocHostUIHandlerDispatch* pDisp);

Parameters

pDisp
[in] A pointer to an IDocHostUIHandlerDispatch interface.

Return Value

A standard HRESULT value.

Remarks

This function is used by controls (such as the Web browser control) that query the host's site for the IDocHostUIHandlerDispatch interface.

See Also

IAxWinAmbientDispatch Interface
CAxWindow::QueryHost
AtlAxGetHost