Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

The COM Interfaces

Active documents, like their predecessor OLE documents, are built on the foundation of COM. Through a set of well-defined interfaces, it is possible to build an Active document that can operate within any Active container without knowing anything more about the container than that it supports a set of COM interfaces. This architecture allows for a great deal of flexibility and enables you to combine these Active document components in ways perhaps not envisioned by the original programmers.

This section contains 10 COM interfaces that make up the Active document specification. Six of these interfaces are part of the original OLE document specification. Four of them are new to Active documents and are not found in OLE. Two of the new active document COM interfaces are optional: IPrint and IOleCommandTarget.

IOleObject

IOleObject is the largest of the interfaces used with OLE compound documents and Active documents. It provides the main interface for a container to communicate with an embedded object and is required if an object wants to support embedding. Table 25.1 describes the IOleObject interfaces.

Table 25.1. IOleObject Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleObject Methods
SetClientSite Provides a pointer to the container's client site object
GetClientSite Obtains the pointer to the container's client site object
SetHostNames Provides the names of the container application and container document
Close Changes the state of the object from running to loaded
SetMoniker Allows the container to tell the object about its moniker
GetMoniker Obtains the object's moniker
InitFromData Allows the object to initialize itself from an IDataObject interface
GetClipboardData Obtains a current copy of the object in the form of an IDataObject interface
DoVerb Requests an object to perform one of its actions
EnumVerbs Enumerates the actions that an object supports
Update Updates linked objects
IsUpToDate Requests the object to check whether it is up to date
GetUserClassID Returns the object's CLSID
GetUserType Returns the object's displayable name
SetExtent Allows the container to tell the object how much display space it has
GetExtent Obtains the size of the object's display area
Advise Creates a connection between the container and the document
Unadvise Removes the connection between the container and the document
EnumAdvise Enumerates the Advise connections
GetMiscStatus Returns the status of the object
SetColorScheme Tells the object what color scheme to use

IDataObject

IDataObject is the means by which data is transferred between COM and OLE objects. This technology is called Uniform Data Transfer. With IDataObject, data can be transferred using a particular format over a specific storage medium. It also is possible to advise others of changed data. Table 25.2 describes the IDataObject interfaces.

Table 25.2. IDataObject Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IDataObject Methods
GetData Causes the source data object to render its data as described in a FORMATETC structure and transfers it through the STGMEDIUM structure
GetDataHere Similar to GetData, except that it uses the storage structure allocated by the caller
QueryGetData Asks the source data object whether it is capable of rendering its data as described in the FORMATETC structure
GetCanonicalFormatEtc Returns a canonical FORMATETC based on an input FORMATETC
SetData Sets the data of the object according to the FORMATETC and STGMEDIUM structures
EnumFormatEtc Allows the caller to enumerate the data formats supported by the object
DAdvise Allows the caller to be notified when data changes
DUnadvise Removes a notification of data change
EnumDAdvise Allows the caller to enumerate the advisory connection that has been set up

IPersistStorage

IPersistStorage provides a means for a container to pass a storage interface to an embedded object. The IPersistStorage interface uses structured storage and allows object data to be stored in its own area within the structured storage. Table 25.3 describes the IPersistStorage interfaces.

Table 25.3. IPersistStorage Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IPersist Method
GetClassID Returns the CLSID
IPersistStorage Methods
IsDirty Allows the caller to determine whether the object has changed since it was last saved
InitNew Initializes a new storage object and provides it with an IStorage interface
Load Loads an object from storage
Save Saves an object to storage
SaveCompleted Notifies the object that it can write to its storage
HandsOffStorage Notifies the object to release all storage objects

IPersistFile (Optional)

IPersistFile provides an interface that allows the object to store itself on the file system instead of in a structured storage object. Table 25.4 describes the IPersistFile interfaces.

Table 25.4. IPersistFile Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IPersist Method
GetClassID Returns the CLSID
  IPersistFile Methods
IsDirty Allows the caller to determine whether the object has changed since it was last saved
Load Loads an object from the specified file
Save Saves the object to the specified file
SaveCompleted Tells the object that the container has finished saving its data
GetCurFile Obtains the name of the current file

IOleDocument

IOleDocument is one of the new COM interfaces that supports Active documents. It allows the container to discover what kind of views are supported by the document and to obtain pointers to those view interfaces. Table 25.5 describes the IOleDocument interfaces.

Table 25.5. IOleDocument Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleDocument Methods
CreateView Allows the container to request a view object from the document
GetDocMiscStatus Returns miscellaneous status information about the document
EnumViews Enumerates views that are supported by the document

IOleInPlaceObject

IOleInPlaceObject allows a container to activate and deactivate an in-place Active object. It also gives the container the opportunity to set the viewable area of the embedded object. Table 25.6 describes the IOleInPlaceObject interfaces.

Table 25.6. IOleInPlaceObject Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleWindow Methods
GetWindow Obtains a window handle
ContextSensitiveHelp Determines whether context-sensitive help should be enabled
  IOleInPlaceObject Methods
InPlaceDeactivate Deactivates an in-place Active object
UIDeactivate Deactivates and removes the user interface of the Active object
SetObjectRects Indicates how much of the object is visible
ReactivateAndUndo Reactivates the previously deactivated object

IOleInPlaceActiveObject

IOleInPlaceActiveObject provides a means for the embedded object to communicate with the container's frame and the container's document window. Table 25.7 describes the IOleInPlaceActiveObject interfaces.

Table 25.7. IOleInPlaceActiveObject Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleWindow Methods
GetWindow Obtains a window handle
ContextSensitiveHelp Determines whether context-sensitive help should be enabled
  IOleInPlaceActiveObject Methods
TranslateAccelerator Processes accelerator keys
OnFrameWindowActivate Notifies the object when the container's top-level frame is activated
OnDocWindowActivate Notifies the object when the container's document window is activated
ResizeBorder Tells the object that it needs to resize its border space
EnableModeless Enables or disables modeless dialog boxes

IOleDocumentView

IOleDocumentView is another new COM interface that supports Active documents. It provides the means for a container to communicate with each of the Active document views. Table 25.8 describes the IOleDocumentView interfaces.

Table 25.8. IOleDocumentView Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleDocumentView Methods
SetInPlaceSite Gives the document a pointer to the container's view site
GetInPlaceSite Gets the pointer to the document's view site
GetDocument Gets the IUnknown pointer of the document
SetRect Sets the rectangular coordinates of the view port
GetRect Gets the rectangular coordinates of the view port
SetRectComplex Sets the rectangular coordinates of the view port, scrollbars, and size box
Show Asks the view to activate or deactivate itself
UIActivate Asks the view to activate or deactivate its user interface
Open Asks the view to open up in a separate window
Close Asks the view to close itself
SaveViewState Asks the view to save its state
ApplyViewState Asks the view to initialize itself to a previously saved state
Clone Asks the view to create a duplicate of itself

IPrint

IPrint is another new (and optional) Active document COM interface. It allows the container to communicate printing information to the document. Table 25.9 describes the IPrint interfaces.

Table 25.9. IPrint Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IPrint Methods
SetInitialPageNum Sets the page number of the first page
GetPageInfo Gets the page number of the first page and the total number of pages
Print Asks the document to print itself

IOleCommandTarget

IOleCommandTarget is an optional Active document COM interface. It provides a way for the container to pass on commands that it doesn't handle to the document. The reverse also is true; it provides a way for the document to pass on commands to the container. Table 25.10 describes the IOleCommandTarget interfaces.

Table 25.10. IOleCommandTarget Interfaces

Interface Description
  IUnknown Methods
QueryInterface Discovers required interfaces
AddRef Adds a reference count to the object
Release Decrements the reference count for the object and eventually deletes the object
  IOleCommandTarget Methods
QueryStatus Asks the object for the status of one or more commands
Exec Asks the object to execute a command

Share ThisShare This

Informit Network