IDispEventSimpleImpl Class

  • Article

 

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 IDispEventSimpleImpl Class.

This class provides implementations of the IDispatch methods, without getting type information from a type library.

Important

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

Syntax

template <UINT nID, class T, const IID* pdiid>  
class ATL_NO_VTABLE IDispEventSimpleImpl : public _IDispEventLocator<nID, pdiid>

Parameters

nID
A unique identifier for the source object. When IDispEventSimpleImpl is the base class for a composite control, use the resource ID of the desired contained control for this parameter. In other cases, use an arbitrary positive integer.

T
The user's class, which is derived from IDispEventSimpleImpl.

pdiid
The pointer to the IID of the event dispinterface implemented by this class.

Members

Public Methods

Name Description
IDispEventSimpleImpl::Advise Establishes a connection with the default event source.
IDispEventSimpleImpl::DispEventAdvise Establishes a connection with the event source.
IDispEventSimpleImpl::DispEventUnadvise Breaks the connection with the event source.
IDispEventSimpleImpl::GetIDsOfNames Returns E_NOTIMPL.
IDispEventSimpleImpl::GetTypeInfo Returns E_NOTIMPL.
IDispEventSimpleImpl::GetTypeInfoCount Returns E_NOTIMPL.
IDispEventSimpleImpl::Invoke Calls the event handlers listed in the event sink map.
IDispEventSimpleImpl::Unadvise Breaks the connection with the default event source.

Remarks

IDispEventSimpleImpl provides a way of implementing an event dispinterface without requiring you to supply implementation code for every method/event on that interface. IDispEventSimpleImpl provides implementations of the IDispatch methods. You only need to supply implementations for the events that you are interested in handling.

IDispEventSimpleImpl works in conjunction with the event sink map in your class to route events to the appropriate handler function. To use this class:

  • Add a SINK_ENTRY_INFO macro to the event sink map for each event on each object that you want to handle.

  • Supply type information for each event by passing a pointer to an _ATL_FUNC_INFO structure as a parameter to each entry. On the x86 platform, the _ATL_FUNC_INFO.cc value must be CC_CDECL with the callback function calling method of __stdcall.

  • Call DispEventAdvise to establish the connection between the source object and the base class.

  • Call DispEventUnadvise to break the connection.

You must derive from IDispEventSimpleImpl (using a unique value for nID) for each object for which you need to handle events. You can reuse the base class by unadvising against one source object then advising against a different source object, but the maximum number of source objects that can be handled by a single object at one time is limited by the number of IDispEventSimpleImpl base classes.

IDispEventSimplImpl provides the same functionality as IDispEventImpl, except it does not get type information about the interface from a type library. The wizards generate code based only on IDispEventImpl, but you can use IDispEventSimpleImpl by adding the code by hand. Use IDispEventSimpleImpl when you don't have a type library describing the event interface or want to avoid the overhead associated with using the type library.

Note

IDispEventImpl and IDispEventSimpleImpl provide their own implementation of IUnknown::QueryInterface enabling each IDispEventImpl or IDispEventSimpleImpl base class to act as a separate COM identity while still allowing direct access to class members in your main COM object.

CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined.

For more information, see Supporting IDispEventImpl.

Inheritance Hierarchy

_IDispEvent

_IDispEventLocator

IDispEventSimpleImpl

Requirements

Header: atlcom.h

IDispEventSimpleImpl::Advise

Call this method to establish a connection with the event source represented by pUnk.

HRESULT Advise(IUnknown* pUnk);

Parameters

pUnk
[in] A pointer to the IUnknown interface of the event source object.

Return Value

S_OK or any failure HRESULT value.

Remarks

Once the connection is established, events fired from pUnk will be routed to handlers in your class by way of the event sink map.

Note

If your class derives from multiple IDispEventSimpleImpl classes, you will need to disambiguate calls to this method by scoping the call with the particular base class you are interested in.

Advise establishes a connection with the default event source, it gets the IID of the default event source of the object as determined by AtlGetObjectSourceInterface.

IDispEventSimpleImpl::DispEventAdvise

Call this method to establish a connection with the event source represented by pUnk.

HRESULT DispEventAdvise(IUnknown* pUnk  const IID* piid);

Parameters

pUnk
[in] A pointer to the IUnknown interface of the event source object.

piid
A pointer to the IID of the event source object.

Return Value

S_OK or any failure HRESULT value.

Remarks

Subsequently, events fired from pUnk will be routed to handlers in your class by way of the event sink map.

Note

If your class derives from multiple IDispEventSimpleImpl classes, you will need to disambiguate calls to this method by scoping the call with the particular base class you are interested in.

DispEventAdvise establishes a connection with the event source specified in pdiid.

IDispEventSimpleImpl::DispEventUnadvise

Breaks the connection with the event source represented by pUnk.

HRESULT DispEventUnadvise(IUnknown* pUnk  const IID* piid);

Parameters

pUnk
[in] A pointer to the IUnknown interface of the event source object.

piid
A pointer to the IID of the event source object.

Return Value

S_OK or any failure HRESULT value.

Remarks

Once the connection is broken, events will no longer be routed to the handler functions listed in the event sink map.

Note

If your class derives from multiple IDispEventSimpleImpl classes, you will need to disambiguate calls to this method by scoping the call with the particular base class you are interested in.

DispEventAdvise breaks a connection that was established with the event source specified in pdiid.

IDispEventSimpleImpl::GetIDsOfNames

This implementation of IDispatch::GetIDsOfNames returns E_NOTIMPL.

STDMETHOD(GetIDsOfNames)(
    REFIID /* riid */,
    LPOLESTR* /* rgszNames */,
    UINT /* cNames */,
    LCID /* lcid */,
    DISPID* /* rgdispid */);

Remarks

See IDispatch::GetIDsOfNames in the Windows SDK.

IDispEventSimpleImpl::GetTypeInfo

This implementation of IDispatch::GetTypeInfo returns E_NOTIMPL.

STDMETHOD(GetTypeInfo)(
    UINT /* itinfo */,
    LCID /* lcid */,
    ITypeInfo** /* pptinfo */);

Remarks

See IDispatch::GetTypeInfo in the Windows SDK.

IDispEventSimpleImpl::GetTypeInfoCount

This implementation of IDispatch::GetTypeInfoCount returns E_NOTIMPL.

STDMETHOD(GetTypeInfoCount)(UINT* /* pctinfo */);

Remarks

See IDispatch::GetTypeInfoCount in the Windows SDK.

IDispEventSimpleImpl::Invoke

This implementation of IDispatch::Invoke calls the event handlers listed in the event sink map.

STDMETHOD(Invoke)(
    DISPID dispidMember,
    REFIID /* riid */,
    LCID lcid,
    WORD /* wFlags */,
    DISPPARMS* pdispparams,
    VARIANT* pvarResult,
    EXCEPINFO* /* pexcepinfo */,
    UINT* /* puArgErr */);

Remarks

See IDispatch::Invoke.

IDispEventSimpleImpl::Unadvise

Breaks the connection with the event source represented by pUnk.

HRESULT Unadvise(IUnknown* pUnk);

Parameters

pUnk
[in] A pointer to the IUnknown interface of the event source object.

Return Value

S_OK or any failure HRESULT value.

Remarks

Once the connection is broken, events will no longer be routed to the handler functions listed in the event sink map.

Note

If your class derives from multiple IDispEventSimpleImpl classes, you will need to disambiguate calls to this method by scoping the call with the particular base class you are interested in.

Unadvise breaks a connection that was established with the default event source specified in pdiid.

Unavise breaks a connection with the default event source, it gets the IID of the default event source of the object as determined by AtlGetObjectSourceInterface.

See Also

_ATL_FUNC_INFO Structure
IDispatchImpl Class
IDispEventImpl Class
SINK_ENTRY_INFO
Class Overview