
This section describes the Active Document interfaces.
| IContinueCallback |
| IEnumOleDocumentViews |
| IOleCommandTarget |
| IOleDocument |
| IOleDocumentSite |
| IOleDocumentView |
| IPrint |
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. |
HRESULT FContinue(void);
Answers whether a given generic operation should continue.
HRESULT FContinuePrinting(
LONG cPagesPrinted,
LONG nCurrentPage,
LPOLESTR pszPrintStatus
);
Answers whether a given lengthy printing operation should continue.
| S_OK | Continue the printing operation. |
| E_FAIL | The printing operation failed. |
| S_FALSE | Cancel the print job as soon as possible. |
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.
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. |
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.
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.
| S_OK | The number of items requested in cViews is fetched. |
| S_FALSE | Less than the number of items requested is fetched. |
| OLE defined error code otherwise. |
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.
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.
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.
| S_OK | The number of items requested in cViews is skipped. |
| S_FALSE | Less than the number of items requested is skipped. |
| An OLE defined error code otherwise. |
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. |
HRESULT Exec(
const GUID *pguidCmdGroup,
DWORD nCmdID,
DWORD nCmdExecOpt,
VARIANTARG *pvaIn,
VARIANTARG *pvaOut
);
Executes a specified command or displays help for a command.
| S_OK | Success. |
| E_FAIL | The command failed. |
| E_UNEXPECTED | The command was executed at a time when the object was not expecting the command. |
| OLECMDERR_CANCELED | The user canceled the execution of the command. |
| OLECMDERR_DISABLED | The command identified by nCmdID is currently disabled and cannot be executed. |
| OLECMDERR_E_NOTSUPPORTED | The nCmdID parameter does not identify a valid command in the pguidCmdGroup group. |
| OLECMDERR_E_UNKNOWNGROUP | The pguidCmdGroup parameter is not NULL but does not specify a recognized command group. |
| OLECMDERR_NOHELP | The caller has asked for help on the command identified by nCmdID, but no help is available. |
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.
[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.
| S_OK | The command status and any optional strings were returned successfully. |
| E_FAIL | The query failed. |
| E_POINTER | The prgCmds argument is NULL. |
| E_UNEXPECTED | The query was received at a time that the object was not expecting it. |
| OLECMDERR_E_UNKNOWNGROUP | The pguidCmdGroup parameter is not NULL but does not specify a recognized command group. |
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 commandenabled/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.
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. |
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.
| S_OK | Success. |
| E_FAIL | The view object creation failed. |
| E_OUTOFMEMORY | There is not enough memory to create the view object. |
| E_POINTER | The address in ppView is NULL. |
| E_UNEXPECTED | The method was called at a time when the object was not expecting it. |
See also IOleDocumentSite::ActivateMe, IOleDocumentView::ApplyViewState, IOleDocumentView::Show, IOleDocumentView::UIActivate
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.
| S_OK | If the object supports multiple views, ppEnum contains a pointer to the enumerator object and the content of ppView is NULL. Otherwise, the content of ppEnum is NULL and ppView contains an interface pointer to the single view. |
| E_OUTOFMEMORY | There is not enough memory available to create the object. |
| E_POINTER | Either ppEnum or ppView is invalid. The caller must pass valid pointers for both parameters. |
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.
HRESULT GetDocMiscStatus(
DWORD *pdwStatus
);
Obtains information about whether an Active Document supports behaviors specified in the DOCMISC enumerator.
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.
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. |
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.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_OUTOFMEMORY | There was not enough memory to complete the operation. |
See also IOleClientSite, IOleDocumentView::SetInPlaceSite, IOleInPlaceSite, IOleObject::DoVerb
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. |
HRESULT ApplyViewState(
IStream *pstm
);
Initializes a view to a previously saved view state.
| S_OK | Success. |
| E_NOTIMPL | This view has no meaningful state to load. This error should be rare because most views will have at least some state information worth loading. |
| E_POINTER | The value in the pstm parameter is NULL. |
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.