Interfaces

Interfaces


This section describes the Active Document interfaces.

IContinueCallback
IEnumOleDocumentViews
IOleCommandTarget
IOleDocument
IOleDocumentSite
IOleDocumentView
IPrint

IContinueCallback

The IContinueCallback interface is a generic callback mechanism for interruptible processes that should periodically ask an object whether to continue.

The IContinueCallback::FContinue method is a generic continuation request. IContinueCallback::FContinuePrinting carries extra information pertaining to a printing process and is used in the context of the IPrint interface.

Methods in Vtable Order
IContinueCallback methods Description
FContinue Answers whether an operation should continue.
FContinuePrinting Answers whether a printing operation should continue.

IContinueCallback::FContinue

HRESULT FContinue(void);

Answers whether a given generic operation should continue.

IContinueCallback::FContinuePrinting

HRESULT FContinuePrinting(
    LONG cPagesPrinted,
    LONG nCurrentPage,
    LPOLESTR pszPrintStatus
    ); 

Answers whether a given lengthy printing operation should continue.

cPagesPrinted
Total number of pages that have been printed at the time the object receives a call to this method.
nCurrentPage
Page number of the page being printed at the time the object receives a call to this method.
pszPrintStatus
Address of a message about the current status of the print job. The object being printed may or may not display this message to the user. Can be NULL.

Implementations of IPrint::Print call this method at periodic intervals during the printing process. The IPrint implementation should call back at least after printing each page, so that its client can, if necessary, display useful visual feedback to the user. IPrint::Print can call back multiple times with the same cPagesPrinted and nCurrentPage values, which is useful when a page being printed is complex and it is appropriate to give a user an opportunity to cancel mid-page.

IEnumOleDocumentViews

The IEnumOleDocumentViews interface is used to enumerate the views supported by an Active Document. IEnumOleDocumentViews has the same methods as all enumerator interfaces. For general information on these methods, see IEnumXXXX.

When to Implement

Implement IEnumOleDocumentViews on enumerator objects associated with Active Documents that support more than one view of their data.

When to Use

Use the IEnumOleDocumentViews interface to enumerate all the views supported by an Active Document. The usual procedure is to first call the IOleDocument::EnumViews method. If the Active Document supports only one view, IOleDocument::EnumViews obtains a pointer to that view. If the Active Document supports two or more views, IOleDocument::EnumViews obtains a pointer to IEnumOleDocumentViews. Using this pointer, the container can then ask the Active Document to enumerate the views it supports.

Methods in Vtable Order
IEnumOleDocumentViews methods Description
Next Retrieves a specified number of items in the enumeration sequence.
Skip Skips over a specified number of items in the enumeration sequence.
Reset Resets the enumeration sequence to the beginning.
Clone Creates another enumerator that contains the same enumeration state as the current one.

IEnumOleDocumentViews::Clone

HRESULT Clone(
    IEnumOleDocumentViews ** ppenum);

Creates a separate view enumerator with the same state as the current enumerator, and that iterates over the same list. This makes it possible to record a point in the enumeration sequence and return to that point at a later time.

ppenum
[out] Address of the IEnumOleDocumentViews interface pointer that receives the newly created enumerator. The caller must release this enumerator separately from the original enumerator.

IEnumOleDocumentViews::Next

HRESULT Next(
    ULONG cViews, 
    IOleDocumentView * rgpView, 
    [out] ULONG * pcFetched);

Enumerates the next cViews elements in the enumerator's list, returning them in rgpView, along with the actual number of enumerated elements in pcFetched. The enumerator object is responsible for calling IUnknown::AddRef and the caller is responsible for calling IUnknown::Release on each pointer returned in rgpView.

cViews
[in] Number of IOleDocumentView pointers to be written to the array pointed to by rgpView. If pcFetched is NULL, this argument must be 1.
rgpView
[out, max_is(cViews)] Address of an array of IOleDocumentView pointers that receive the enumerated interfaces. The caller is responsible for allocating this array, and the array must be able to contain at least the number of elements specified in cViews.
pcFetched
[out] Address of a ULONG variable that receives the actual number of views enumerated in the rgpView parameter. This argument can be NULL, in which case the cViews argument must be 1.

E_NOTIMPL is not allowed by this method as a return value. If an error value is returned, no entries in the rgpView array are valid and no calls to IUnknown::Release are required.

IEnumOleDocumentViews::Reset

HRESULT Reset(void);

Resets the enumeration sequence to the beginning of the list of elements. There is no guarantee that the same set of elements will be enumerated on each pass through the list: It depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain this condition.

IEnumOleDocumentViews::Skip

HRESULT Skip(
    ULONG cViews);

Skips over a number of elements, specified in the cViews parameter, in the enumeration so that the next call to the IEnumOleDocumentViews::Next method will not return those elements.

cViews
[in] Number of elements to skip in the enumeration.

IOleCommandTarget

The IOleCommandTarget interface enables objects and their containers to determine if an object supports a command, to determine the status of a command, and to execute a command. For example, the container of an object can determine if the object supports the Paste command. If it does support the Paste command, the container can then determine if Paste can currently be executed. If the command can be executed, the container can use that information to enable its Paste command user interface. If the user selects Paste, the container can use this interface to execute the command on the object.

Normal in-place activation guidelines recommend that you remove or disable such buttons because no efficient, standard mechanism has been available to dispatch them to the container. Similarly, a container has heretofore had no efficient means to send commands such as Print, Page Setup, and Properties to an in-place active object. Such simple command routing could have been handled through existing OLE Automation standards and the IDispatch interface, but the overhead with IDispatch is more than is required in the case of Active Documents. The IOleCommandTarget interface provides a simpler means to achieve the same ends.

Available commands are defined by integer identifiers in a group. The group itself is identified with a GUID. The interface allows a caller both to query for support of one or more commands within a group and to issue a supported command to the object.

When to Implement

Implement IOleCommandTarget when your object supports one or more commands.

When to Use

Use IOleCommandTarget to determine the status of or execute a command implemented by an object.

Methods in Vtable Order
IOleCommandTarget methods Description
QueryStatus Queries an object for status of commands.
Exec Executes a command.

IOleCommandTarget::Exec

HRESULT Exec(
    const GUID *pguidCmdGroup,
    DWORD nCmdID,
    DWORD nCmdExecOpt,
    VARIANTARG *pvaIn,
    VARIANTARG *pvaOut
   );

Executes a specified command or displays help for a command.

pguidCmdGroup
[unique][in] Address of a globally unique identifier (GUID) of the command group; can be NULL to specify the standard group.
nCmdID
[in] Identifier of the command to be executed. This command must belong to the group specified in the pguidCmdGroup parameter.
nCmdExecOpt
[in] Values taken from the OLECMDEXECOPT enumeration, which describes how the object should execute the command.
pvaIn
[unique][in] Address of a VARIANTARG structure containing input arguments. Can be NULL.
pvaOut
[unique][in,out] Address of a VARIANTARG structure to receive command output. Can be NULL.

The list of input and output arguments of a command and how they are packaged is unique to each command. Such information should be documented with the specification of the command group. (See the description of OLECMDID_ZOOM in the OLECMDID enumeration.) In the absence of any specific information, the command is assumed to take no arguments and have no return value.

Notes to Callers

The pguidCmdGroup and nCmdID parameters together uniquely identify the command to invoke. The nCmdExecOpt parameter specifies the exact action to be taken. (For more details, see the OLECMDEXECOPT enumeration.)

Most commands neither take arguments nor return values. For such commands, the caller can pass NULL in pvaIn and pvaOut. For commands that expect one or more input values, the caller can declare and initialize a VARIANTARG structure and pass a pointer to that structure in pvaIn. If the input to the command is a single value, the argument can be stored directly in the VARIANTARG structure and passed to the function. If the command expects multiple arguments, those arguments must be packaged appropriately within the VARIANTARG structure, using one of the supported variant types (such as the IDispatch interface or the SAFEARRAY data type).

If a command returns one or more arguments, the caller is expected to declare a VARIANTARG, initialize it to VT_EMPTY, and pass its address in pvaOut. If the command returns a single value, the object can store that value directly in pvaOut. If the command has multiple output values, it will package those in some way appropriate for the VARIANTARG.

Because pvaIn and pvaOut are both caller-allocated, stack variables are permitted for both the caller and the object receiving the call. For commands that take zero or one argument on input and return zero or one value, no additional memory allocation is necessary. Most of the types supported by VARIANTARG do not require memory allocation. Exceptions include SAFEARRAY and BSTR. For a complete list, see the OLE documentation in the Microsoft® Platform SDK.

Notes to Implementers

A command target must implement this function; E_NOTIMPL is not a valid return value.

IOleCommandTarget::QueryStatus

[input_sync] HRESULT QueryStatus(
    const GUID *pguidCmdGroup,
    ULONG cCmds,
    OLECMD *prgCmds,
    OLECMDTEXT *pCmdText
   );

Queries the object for the status of one or more commands generated by user interface events.

pguidCmdGroup
[unique][in] Globally unique identifier of the command group; can be NULL to specify the standard group. All the commands that are passed in the prgCmds array must belong to the group specified by this parameter.
cCmds
[in] Number of commands in the prgCmds array.
prgCmds
[in,out] Caller-allocated array of OLECMD structures that indicates the commands for which the caller needs status information. This method fills the cmdf member of each structure with values taken from the OLECMDF enumeration.
pCmdText
[unique][in,out] Address of an OLECMDTEXT structure in which to return name and/or status information of a single command. Can be NULL to indicate that the caller does not need this information.

Callers use this method to determine which commands are supported by a target object. The caller can then disable unavailable commands that would otherwise be routed to the object. The caller can also use this method to get the name or status of a single command.

Notes to Callers

The caller passes an array of OLECMD structures in prgCmds that describes the commands of interest from the group specified in pguidCmdGroup, where each structure's cmdID member is set to a command identifier and the cmdf member is set to zero.

Notes to Implementers

The object receiving the call fills the cmdf member for each command with values taken from the OLECMDF enumeration to describe the status of each command.

The called object should first mark the command as described above. Then, if the command is supported (OLECMDF_SUPPORTED), the object should check the OLECMDTEXTF_ flags in the cmdtextf member of pCmdText. If the OLECMDTEXTF_NAME flag is specified, the object should copy the localized name of the command (for example, "Open", "Copy", and so on) into the rgwz member of pCmdText. Attention should be paid to the size specified by the cwBuf member of pCmdText.

If the caller sets the OLECMDTEXTF_STATUS flag, the object should instead write a localized status string for the command into the rgwz member. The status string is typically contextual and depends on the state of the command—enabled/disabled, for example. If the buffer is not big enough, the object should zero-terminate the buffer. Whether the buffer is big enough or not, the object must return the total actual size of the string that it attempted to copy in the cwActual member of pCmdText.

If the command array contains more than one command, the textual information should be returned for the first command in the array that the object supports. Typically, this functionality is used to show the status text of a command. The caller can use either a stack or a global variable for rgwz, because memory for this parameter is not dynamically allocated.

Because IOleCommandTarget::QueryStatus is defined with the [input_sync] attribute, the implementing object cannot yield or make another non-input_sync RPC call while executing it.

A command target must implement this function; E_NOTIMPL is not an acceptable return value.

IOleDocument

The IOleDocument interface enables an Active Document to communicate its ability to create views of its data to containers. This interface also enables an Active Document to enumerate its views and to provide containers with miscellaneous information about itself, such as whether it supports multiple views or complex rectangles.

When to Implement

An OLE document that is to be activated as an Active Document must, at the very least, implement this interface. If an application exposes more than one type of Active Document, each type must implement IOleDocument.

When to Use

An Active Document container calls the methods of this interface to ask an Active Document to create views of itself, enumerate the views it supports, or provide miscellaneous information about its capabilities.

Methods in Vtable Order
IOleDocument methods Description
CreateView Creates a new view object.
GetDocMiscStatus Returns status information about the Active Document.
EnumViews Enumerates views supported by the Active Document.

IOleDocument::CreateView

HRESULT CreateView(
    IOleInPlaceSite *pIPSite,
    IStream *pstm,
    DWORD dwReserved,
    IOleDocumentView **ppView
   );

Creates a document view object in the caller's process and obtains a pointer to that object's IOleDocumentView interface.

pIPSite
[in] Address of the view site object to be associated with the new document view object. Can be NULL, as when the view is contained in a new, uninitialized Active Document, in which case the caller must initialize the view with a subsequent call to the IOleDocumentView::SetInPlaceSite method.
pstm
[in] Address of a stream containing data from which the new document view object should initialize itself. If NULL, the Active Document initializes the new document view object with a default state.
dwReserved
[in] Reserved for future use. Must be zero.
ppView
[out] Address of the IOleDocumentView interface pointer on the new document view object. If IOleDocument::CreateView succeeds, the caller is responsible for calling IUnknown::Release on this pointer when the view object is no longer needed.

See also IOleDocumentSite::ActivateMe, IOleDocumentView::ApplyViewState, IOleDocumentView::Show, IOleDocumentView::UIActivate

IOleDocument::EnumViews

HRESULT EnumViews(
    IEnumOleDocumentViews ** ppEnum,
    IOleDocumentView ** ppView
   );

Creates an object that enumerates the views supported by an Active Document, or, if only one view is supported, returns a pointer to that view.

ppEnum
[out] Address of the IEnumOleDocumentViews interface pointer on the enumerator object.
ppView
[out] Address of the IOleDocumentView interface on a single view object.

If an Active Document supports multiple views of its data, it must also implement IEnumOleDocumentViews and place that interface's pointer in ppEnum. Using this pointer, the container can enumerate the views supported by the Active Document.

If the Active Document supports only a single view, IOleDocument::EnumViews places that view's IOleDocumentView pointer in ppView.

Notes to Callers

Call this method to determine if an Active Document supports more than one view of its data. If it does, the caller can use the pointer written to ppEnum to specify which view to activate. When finished with the pointer, the caller must free it by calling IUnknown::Release.

Notes to Implementers

This method must be completely implemented on all Active Documents; E_NOTIMPL is not an acceptable return value.

IOleDocument::GetDocMiscStatus

HRESULT GetDocMiscStatus(
    DWORD *pdwStatus
   );

Obtains information about whether an Active Document supports behaviors specified in the DOCMISC enumerator.

pdwStatus
[out] Address of the information on supported behaviors. Values written to the address specified by this pointer are taken from the DOCMISC enumeration.

This method provides a way for containers to ascertain whether an Active Document supports multiple views, complex rectangles, opening in a pop-up window, or file read/write.

Notes to Callers

By calling this method prior to activating an Active Document, containers can take whatever steps are necessary to support or otherwise accommodate specified behaviors.

Notes to Implementers

This method must be completely implemented in any Active Document, even if the dereferenced value of pdwStatus is zero. E_NOTIMPL is not an acceptable return value. Normally, the returned DOCMISC value should be hard-coded for performance.

IOleDocumentSite

The IOleDocumentSite interface enables a document that has been implemented as an Active Document to bypass the normal activation sequence for in-place active objects and to directly instruct its client site to activate it as an Active Document object. A client site with this ability is called a document site.

For each Active Document to be hosted, a container must provide a corresponding document site. This document site is an OLE Documents client site that, in addition to implementing the IOleClientSite and IAdviseSink interfaces, also implements IOleDocumentSite. Each document site implements a separate document view site object for each view of a document to be activated. The document view site implements IOleInPlaceSite and, optionally, IContinueCallback.

When to Implement

Implement IOleDocumentSite on each client site that is to host an Active Document. In addition to this interface, a document site must also implement the IOleClientSite, IOleInPlaceSite, and IAdviseSink interfaces. Implementing IContinueCallback is optional.

When to Use

An Active Document calls IOleDocumentSite::ActivateMe to ask its document site to activate it, typically in response to the container's call to IOleObject::DoVerb.

Methods in Vtable Order
IOleDocumentSite methods Description
ActivateMe Activates an Active Document.

IOleDocumentSite::ActivateMe

HRESULT ActivateMe(
    IOleDocumentView *pViewToActivate 
    );

Asks a document site to activate the document making the call as an Active Document rather than an in-place active object. Optionally, specifies which view of the object document to activate.

pViewToActivate
[in] Address of the document view to be used in activating the Active Document. Can be NULL, in which case the container should call IOleDocument::CreateView to obtain a document view pointer.

See also IOleClientSite, IOleDocumentView::SetInPlaceSite, IOleInPlaceSite, IOleObject::DoVerb

IOleDocumentView

The IOleDocumentView interface enables a container to communicate with each view supported by an Active Document.

An Active Document that supports multiple views of its data represents each view as a separate object. Each document view object implements IOleDocumentView, along with the IOleInPlaceObject and IOleInPlaceActiveObject interfaces, as well as optional interfaces such as IPrint and IOleCommandTarget. An Active Document that supports only a single view does not require that view to be implemented as a separate object. Instead, both document and view can be implemented as a single class.

When to Implement

All Active Documents must implement IOleDocumentView for each view they support. If an Active Document supports multiple views, each view must be implemented as a separate class object. If an Active Document supports only a single view, the Active Document and its view can both be implemented as a single class.

When to Use

A container calls the methods of this interface to activate, deactivate, close, and generally communicate with a document view object.

Methods in Vtable Order
IOleDocumentView methods Description
SetInPlaceSite Associates a container view site with this view.
GetInPlaceSite Retrieves the view site associated with this view.
GetDocument Obtains the IUnknown pointer of the Active Document that owns this view.
SetRect Sets the coordinates of the view port.
GetRect Retrieves the coordinates last passed in the SetRect method.
SetRectComplex Sets the coordinates of the view port, scroll bars, and size box.
Show In-place activates or deactivates a view.
UIActivate In-place activates or deactivates a view's user-interface elements.
Open Displays the view in a separate pop-up window.
CloseView Instructs the view to close.
SaveViewState Saves the view state into a stream.
ApplyViewState Initializes the view with the view state previously saved in the call to the SaveViewState method.
Clone Creates a duplicate view object.

IOleDocumentView::ApplyViewState

HRESULT ApplyViewState(
    IStream *pstm
   );

Initializes a view to a previously saved view state.

pstm
[in] Address of a stream containing data from which the view should initialize itself.

Typically, this method is called after an existing view has been created in the container but before that view has been displayed. It is the responsibility of the view to validate the data in the view stream; the container does not attempt to interpret the view's state data.

See also IOleDocument::CreateView, IOleDocumentView::SaveViewState

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.