The Makeup of a Typical ActiveX Control

---

ActiveX controls tend to have a common set of requirements. In a nutshell, a full-blown control will need to provide the following basic behaviors, all of which are exposed using standard COM interfaces:

• A set of custom properties and methods exposed via IDispatch. This is what makes your control a unique entity. Although an ActiveX control does not have to provide its services using IDispatch, most will, to allow web-based scripting languages to access their functionality.

• A set of events exposed through a [default, source] dispinterface. Beyond providing support for IConnectionPointContainer many ActiveX controls support a connection proxy for a related interface: IPropertyNotifySink.

• The ability to be rendered as needed by the control container. This ability is provided by additional COM interfaces such as IViewObject, IViewObject2, and IViewObjectEx.

• The ability to be persisted by the container. In other words, a control should be able to save and load its state when asked to do so. This behavior is provided when a control implements a number of COM persistence interfaces such as IPersistPropertyBag, IPersist, IPersistStorage, and IPersistStreamInit.

• The ability to handle standard windowing messages, given that most controls respond to some type of user input. In ATL, this is provided by the MSG_MAP structure as well as various windowing templates we examined in Chapter 13.

• Some set of property pages to allow the user to set properties at design time. Each property page supports the standard IPropertyPage interface (and possibly IPropertyPage2). As well, the coclass needs to support ISpecifyPropertyPages to expose these pages to the container.

• The ability to run "in-place active" as an embedded object. This allows containers such as MS Word and Excel to make use of your controls using IOleInPlaceObject (among others). Support for these OLE-centric interfaces is optional; however, without them your control cannot run as an OLE object.

• Most controls support COM exception handling, using ISupportErrorInfo.

As you can see, you already know a good deal about what a control is capable of, given your understanding of various standard COM interfaces. The remaining aspects of an ActiveX control (such as rendering and persistence) are provided by additional COM interfaces. To serve as a road map for the remainder of this chapter, the following table outlines the core interfaces required to build a full-blown ActiveX control, with a brief description of the acquired functionality.

COM Interfaces	Meaning in Life
IConnectionPointContainer IConnectionPoint IPropertyNotifySink	Used to establish connections with the ActiveX control.
ISpecifyPropertyPages IPropertyPage(2)	ISpecifyPropertyPages is used to determine which property pages are used by the control. IPropertyPage(2) is implemented by the individual property page objects.
IOleInPlaceActiveObject IViewObject(2) IViewObjectEx IOleInPlaceObject IOleInPlaceObjectWindowless	Used to allow the control host to render the ActiveX control. Hit testing, sizing, and generic drawing abilities are provided by this set of interfaces.
IOleControl IOleObject IOleWindow IDataObject	Core ActiveX control support. Used to establish communication between the container and the control, enable in-place activation, and transmit data between the two parties.
IQuickActivate	Allows a container to grab a batch of interfaces from a single interface.
IPersist IPersistStorage IPersistStreamInit IPersistPropertyBag	Allows the control host to save and load the control's properties, in a variety of client-specified formats.
IProvideClassInfo(2)	Allows container to grab type information from the control and quickly discover the default [source] dispinterface.

Some controls may choose not to implement all of the listed interfaces. At minimum (according to the official word from Microsoft), the only interface an ActiveX control really must support is our good friend IUnknown, and dwell a self-registering DLL (exporting DllRegisterServer() and DllUnregisterServer()). However, most people who are willing to spend money on a control expect to do more than obtain a pointer to IID_IUnknown all day long. Therefore, most production controls do implement the listed interfaces, in addition to the domain-specific logic that makes your control unique.

---