[TOC]

DHyperlink [Beta]

TBD
DHyperlink Methods Description
get_FriendlyName //Retrieves the friendly name of the hyperlink
put_FriendlyName //Sets the friendly name of the hyperlink
get_Target //Retrieves the hyperlink's target
put_Target //Sets the hyperlink's target
Navigate //Navigates to the hyperlink

[TOC]

DHyperLink::get_FriendlyName [Beta]

Returns the friendly name of a hyperlink.

HRESULT DHyperLink::get_FriendlyName(
BSTR * pbstrName // TBD
);

Parameters

pbstrName

[out] TBD

Return Values

TBD

[TOC]

DHyperLink::get_Target [Beta]

Returns the target of a hyperlink.

HRESULT DHyperLink::get_Target(
BSTR * pbstrTarget // TBD
);

Parameters

pbstrTarget

[out] TBD

Return Values

TBD

[TOC]

DHyperLink::Navigate [Beta]

Jumps to the hyperlink.

HRESULT DHyperLink::Navigate(
VARIANT * OpenInNewWindow // TBD
VARIANT * NoHistory// TBD
);

Parameters

OpenInNewWindow

[in] TBD

NoHistory

[in] TBD

Return Values

TBD

[TOC]

DHyperLink::put_FriendlyName [Beta]

Sets the friendly name of a hyperlink.

HRESULT DHyperLink::put_FriendlyName(
BSTR bstrName // TBD
);

Parameters

bstrName

[in] TBD

Return Values

TBD

[TOC]

DHyperLink::put_Target [Beta]

Sets the target for the hyperlink.

HRESULT DHyperLink::put_Target(
BSTR bstrTarget // TBD
);

Parameters

bstrTarget

[in] TBD

Return Values

TBD

[TOC]

IBasicAuthentication [Beta]

The single method of IBasicAuthentication provides basic authentication information from a bind client.

When to Implement

Only custom protocol writers need to implement this interface.

When to Use

The method of this interface may be called when a URL bind requires authentication for a URL download. To get a pointer to this interface, call IBindStatusCallback::QueryInterface.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IBasicAuthentication Methods Description
Authenticate Supplies basic authentication to a URL moniker from a bind client.

[TOC]

IBasicAuthentication::Authenticate [Beta]

Called by the URL Moniker when it needs basic authentication information from a bind client

HRESULT Authenticate(
HWND * phwnd // Client-provided HWND of the parent window for default authentication UI
LPWSTR szUsername// Client-provided username for authentication.
LPWSTR szPassword// Client-provided password for authentication.
);

Parameter

phwnd

[in]Client-provided HWND of the parent window for default authentication UI. If no UI is desired, the client must provide a username and password in the other parameters, and this handle.is set to the value -1.

szUsername

Client-provided username for authentication. If the client returns a value here it should also set *phwnd = -1.

szPassword

Client-provided password for authentication. If the client returns a value here it should also set *phwnd = -1.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

Remarks

This function is called by the URL Moniker when it needs basic authentication information from a bind client. The client may choose to return username and password strings, or it may provide an HWND that is used to present default authentication UI.

See Also

IBasicAuthentication::Authenticate

[TOC]

IBindHost [Beta]

This interface is implemented on a site object to supply another object with services and information it requires when performing an asynchronous data transfer, specifically parsing a name and converting it to a moniker and initializing a bind context.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IBindHost Methods Description
ParseDisplayName Turns a text name into a moniker.
GetBindContext Supplies a pointer to an implementation of IBindCtx.

[TOC]

IBindHost::GetBindCtx [Beta]

IBindHost::GetBindCtx is the factory method for a host-initialized bind context. It supplies a pointer to an implementation of IBindCtx. Its arguments are identical to those for the API function CreateBindCtx.

HRESULT GetBindCtx(
DWORD dwReserved, // Reserved for future use.
IBindCtx ** ppbc// Receives an indirect pointer to the IBindCtx interface
);

Parameters

dwReserved

[in] Reserved. Must be zero.

ppbc

[out] The address of the caller's IBindCtx * variable in which to store the bind context's pointer on successful return. The caller is responsible for calling IBindCtx::Release when the bind context is no longer needed.

Return Values

S_OK

The bind context was successfully obtained and the caller is responsible for the interface pointer.

E_OUTOFMEMORY

There is insufficient memory to create the bind context.

E_UNEXPECTED

An unknown error occurred.

Remarks

E_NOTIMPL is not allowed¾a bind host is responsible for providing bind context creation services.

[TOC]

IBindHost::ParseDisplayName [Beta]

Provides the caller with a means to turn some sort of text name into a moniker such that the caller does not have to interpret the name in any way itself. In many cases, the implementation of IBindHost::ParseDisplayName will simply call MkParseDisplayNameEx, but this method gives the implementor of IBindHost a chance to catch host-specific strings that MkParseDisplayNameEx would not otherwise recognize.

HRESULT ParseDisplayName(
LPOLESTR pszName, // Points to the string to parse
IMoniker ** ppmk// Receives an indirect pointer to the IMoniker interface for the new moniker
);

Parameters

pszName

[in] Pointer to the string containing the name to parse.

ppmk

[out] The address of the caller's IMoniker * variable in which to store the moniker created from pszName. The caller is responsible for calling IMoniker::Release when the moniker is no longer needed.

Return Values

S_OK

The moniker was successfully obtained and the caller is responsible for the interface pointer.

E_OUTOFMEMORY

There is insufficient memory to create the moniker.

E_UNEXPECTED

An unexpected error occurred.

MK_E_SYNTAX

The bind host was unable to parse the string into a moniker because the information in the name was unrecognizable.

Remarks

E_NOTIMPL is not allowed¾a bind host is responsible for providing moniker parsing services.

[TOC]

IBinding [Beta]

The IBinding interface provides methods for managing the bind operation for asynchronous monikers. Asynchronous monikers must provide a binding object to their callers via IBindStatusCallback::OnStartBinding to allow control over the binding process.

When to Implement

Implementations of custom asynchronous monikers will implement and expose this interface to allow control of the bind operation. They will usually implement this interface on a separate object created by the moniker on a per-bind basis.

When to Use

Clients of asynchronous monikers obtain a pointer to this interface through a call to IBindStatusCallback::OnStartBinding. They typically keep a reference to this interface to be able to control the bind operation over the course of the bind.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IBinding Methods Description
Abort Permanently aborts the bind operation
Suspend Suspends the bind operation.
Resume Resumes a suspended bind operation.
SetPriority Establishes the priority for the bind operation.
GetPriority Retrieves the current priority of this bind operation.

[TOC]

IBinding::Abort [Beta]

Permanently aborts the bind operation.

HRESULT Abort(void);

Return Values

S_OK

The abort operation was successful.

S_FALSE

The bind operation was already aborted.

E_FAIL

The bind operation could not be aborted.

Remarks

An aborted bind operation will result in a call to IBindStatusCallback::OnStopBinding with a corresponding error code and/or a failure of the IMoniker::BindToObject/BindToStorage call in case this call did not previously return.

After aborting the bind operation the client must still release any pointers obtained during the binding. After aborting the bind operation the client may still receive some notifications about the binding.

Note Calling the last IBinding::Release does not terminate the bind operation.

See Also

IBindStatusCallback::OnStopBinding

[TOC]

IBinding::GetPriority [Beta]

Retrieves the current priority of this bind operation.

HRESULT GetPriority(
LONG * pnPriority, // Points to where to put priority value
);

Parameters

pnPriority

[out]On return, points to location of a value indicating the priority established for this binding relative to other bindings and the system. May not be NULL.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

The pnPriority argument is invalid.

Remarks

IBinding::GetPriority retrieves the current priority of this bind operation. Priority values are taken from the Win32 thread priority APIs (SetThreadPriority and GetThreadPriority).

See Also

[TOC]

IBinding::Resume [Beta]

Resumes a suspended bind operation.

HRESULT Resume(void);

Return Values

S_OK

The resume operation was successful.

S_FALSE

The bind operation was not previously suspended.

E_FAIL

The suspended bind operation could not be resumed.

Remarks

Resumes a suspended bind operation. The bind operation must have been previously suspended by a call to IBinding::Suspend .

See Also

[TOC]

IBinding::SetPriority [Beta]

Establishes the priority for the bind operation.

HRESULT SetPriority(
LONG nPriority, // Relative priority for this binding
);

Parameters

nPriority

[in]A value indicating the priority to establish for this binding relative to other bindings and the system.

Return Values

S_OK

The operation was successful.

E_FAIL

The priority could not be changed.

Remarks

IBinding::SetPriority stablishes the priority for the bind operation to nPriority. Priority values are taken from the Microsoft® Win32® thread priority APIs (SetThreadPriority and GetThreadPriority).

See Also

[TOC]

IBinding::Suspend [Beta]

Suspends the bind operation.

HRESULT Suspend(void);

Return Values

S_OK

The suspend operation was successful.

S_FALSE

The bind operation was already suspended.

E_FAIL

The bind operation could not be suspended.

Remarks

Suspends the bind operation. The bind operation will be suspended until resumed by a later call to IBinding::Resume or canceled by a call to IBinding::Abort.

After calling IBinding::Suspend the client may still receive some notifications about the bind.

See Also

[TOC]

IBindProtocol [Beta]

A custom protocol component creates an IBinding given a URL. URL moniker actually performs its download using the IBinding interface. The bind protocol object essentially acts as a factory for IBinding.

When to Implement

Only custom protocol writers need to implement this interface. They typically register their component with the system as described above.

When to Use

Only custom moniker writers use this interface, as it is otherwise only required for the URL moniker to initialize the transport and retrieve a binding handle.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IBindProtocol Methods Description
CreateBinding Checks an object for changes since it was last saved.

[TOC]

IBindProtocol::CreateBinding [Beta]

Creates the actual binding object.

HRESULT CreateBinding(
LPCWSTR szURL // The URL being bound to.
IBindCtx * pbc// The bind-context passed into the BindTo... call
IBinding ** ppbinding // Location to return the IBinding interface of the transport.
);

Parameter

szURL

[in]The URL being bound to.

pbc

The bind-context passed into the BindToStorage or BindToObject call. May not be NULL.

ppbinding

Location to return the IBinding interface of the transport. May not be NULL.

Return Values

S_OK

Success.

E_INVALIDARG

The ppmkCur argument is invalid.

Remarks

Creates the actual binding object. In the case of the default protocol binding components that come with URL Moniker, the returned object also supports the IInternetDownload interface.

See Also

IWinINetInfo , IWinSockInfo

[TOC]

IBindStatusCallback [Beta]

Clients have to provide an object exposing the following callback interface. An asynchronous moniker will provide information regarding the bind by calling methods on this interface.

This interface also serves the purpose of passing additional bind information to the moniker. The moniker will call two methods (GetBindInfo and GetPriority) after receiving one of the calls either to IMoniker::BindToObject or BindToStorage, to obtain this additional bind information. IBindStatusCallback::QueryInterface provides extensibility to IBindStatusCallback because it allows the moniker to request additional interfaces from the client in case the bind operation requires additional information or negotiaion

All methods in IBindStatusCallback may be invoked from within the IMoniker::BindToObject or BindToStorage call and after the moniker returns the call, if the bind information indicates asynchronous binding (ABINDF_ASYNCHRONOUS).

Clients of asynchronous monikers register their callback interface into the bind context using RegisterBindStatusCallback . This API allows multiple clients to register callback functions for the same bind operation, and each client can specify (through grfBSCOption) which callback methods it is interested in hearing. During the bind operation, these callbacks are called in an arbitrary order, and the asynchronous moniker may set policy and limit certain callback notifications (e.g. GetBindInfo, OnDataAvailable, OnObjectAvailable) to only one of the registered callbacks.

The moniker retrieves the bind status callback interface from the bind context and immediately removes it. It checks the identity registered for the one called and provides only OnProgress notifications, if it is not the one called. This prevents other asynchronous monikers, which could be invoked during the bind operation, from calling the original client's callback function and thus prevents clients from receiving erroneous notifications.

If the asynchronous moniker needs to invoke other monikers as part of the bind operation, it may register its own IBindStatusCallback interface in the bind context just like any other client of a moniker would. Specifically it has to register the identity of the direct callee. This allows chaining of notifications, where the "out-most" moniker can consolidate its own progress with the inner moniker's progress notifications.

When to Implement

Any client of an asynchronous moniker has to implement this interface to obtain asynchronous behaviour. A client will implement this interface on a separate object (similar to a site object) that it associates with a specific bind operation.

The methods in IBindStatusCallbacks do not provide information as to which specific bind the notification belongs to, so that a client will want to provide a separate object instance for each simultaneous asynchronous bind operation it initiates.

The client registers the interface into the bind context by calling RegisterBindStatusCallback . The bind context will keep a reference to the object. The moniker will optionally add references to this object.

When to Use

Implementations of asynchronous monikers will use this interface for two purposes:

· Obtain additional bind information: During the call to IMoniker::BindToStorage or BindToObject the moniker will call IBindStatusCallback::GetBindInfo to check at least the ABINDF_ASYNCHRONOUS flag. If this flag is not set, the method may not return until the object/storage object is available. (Note: Monikers have to behave synchronously if they are not registered as the one being called.)The moniker may call IBindStatusCallback::GetPriority at this time or at a later point. Lastly, the moniker may call IBindStatusCallback::QueryInterface to request a new interface from the client if the bind operation needs further information or additional services from the client.

· Provide notifications: During the call to BindToStorage or BindToObject the moniker may call any of the notification methods as well as the bind information methods. After returning from the call, the moniker will provide additional notifications for the duration of the bind. Monikers may not call methods other than IBindStatusCallback::OnProgress , if they are not registered as the one being called.

The moniker obtains this interface from the bind context by calling IBindCtx::GetObjectParam.

The moniker also has to obtain the identity of the one being called with the following call:

IBindCtx::GetObjectParam(SZ_ASYNCCALLEE, &pCallee)

It then has to verify if punkCallee refers to itself with this call:

pCallee->QueryInterface(IID_IUnknown, punkCallee)

and compare punkCallee to its own IUnknown pointer. If the pointers are identical, the moniker may interpret the additional bind information (GetBindInfo/GetPriority). Otherwise, it has to behave synchronously and may only call IBindStatusCallback::OnProgress.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IBindStatusCallback Methods Description
GetBindInfo Called by asynchronous moniker to get bind info
OnStartBinding Tells the client which callback methods it is registered for receiving.
GetPriority Gets data during asynchronous bind operations.
OnProgress Indicates the current progress of this bind operation.
OnDataAvailable Retrieves the current priority of this bind operation.
OnObjectAvailable Called by asynchronous moniker to to pass the requested object interface pointer to the client.
OnLowResource An asynchronous moniker calls this method when it detects low resources.
OnStopBinding An asynchronous moniker calls this method to indicate the end of the bind operation.

[TOC]

IBindStatusCallback::GetBindInfo [Beta]

An asynchronous moniker calls this method to obtain the bind information for the bind operation.

HRESULT GetBindInfo(
DWORD * pgrfBINDF, // Points to where to put BINDF value
BINDINFO * pbindinfo // Points to where to put BINDINFO structure
);

Parameters

pgrfBINDF

[out]On return, Location to return a value taken from the BINDF enumeration which indicates whether the bind should proceed synchronously or asynchronously.

pbindinfo

Location to return the BINDINFO structure which describes how the caller wants the binding to occur.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The moniker calls this method within its implementations of BindToObject and BindToStorage before returning to obtain the bind information about the specific bind.

See Also

[TOC]

IBindStatusCallback::GetPriority [Beta]

Obtains the priority for the bind.

HRESULT GetBindInfo(
LONG * pnPriority // Points to where to put priority value
);

Parameters

pnPriority

[out]On return, location to return a value indicating the priority of this download. Priorities may be any of the constants defined for prioritizing threads. See the Win32 documentation for SetThreadPriority and GetThreadPriority for details.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The moniker calls this method, typically prior to initiating the bind operation, to obtain the priority for the bind. This method may be called at any time during the bind operation if the moniker needs to make new priority decisions.

It may use this value for setting the actual priority of a thread associated with a download operation but more commonly it will interpret the priority to perform its own scheduling among multiple bind operations. The moniker must not change the priority of the thread used for calling BindToStorage or BindToObject.

See Also

[TOC]

IBindStatusCallback::OnDataAvailable [Beta]

An asynchronous moniker calls this method to provide data to the client as it becomes available during asynchronous bind operations.

HRESULT GetBindInfo(
DWORD grfBSCF, // BSCF enumeration values
DWORD dwSize, // Bytes of data available from current bind operation
FORMATETC * pfmtetc, // Points to where to put BINDF value
BINDINFO * pbindinfo // Points to where to put BINDINFO structure
);

Parameters

grfBSCF

[in]Values taken from the BSCF enumeration.

dwSize

[in]The amount (in bytes) of total data available from the current bind operation.

pfmtetc

[in]Indicates the format of the available data when called as a result of IMoniker::BindToStorage. If there is no format associated with the available data, pformatetc may contain CF_NULL.

pstgmed

[in]Holds the actual data that became available when called as a result of IMoniker::BindToStorage. If it wishes to keep the data in pstgmed allocated, the client should call AddRef on pstgmed->pUnkForRelease (if the pointer is non-NULL).

Return Values

S_OK

The operation was successful.

E_INVALIDARG

One or more arguments are invalid.

Remarks

During asynchronous IMoniker::BindToStorage bind operations, an asynchronous moniker calls this method to provide data to the client as it becomes available.

See Also

IMoniker::BindToStorage

[TOC]

IBindStatusCallback::OnObjectAvailable [Beta]

An asynchronous moniker calls this method to pass the requested object interface pointer to the client.

HRESULT OnObjectAvailable(
REFIID riid, // IID of the requested interface
IUnknown * punk// IUnknown pointer to object requested in IMoniker::BindToObject
);

Parameters

riid

[in]The REFIID of the requested interface.

punk

The object pointer requested in the call to IMoniker::BindToObject. The client should call AddRef on this pointer in order to maintain a reference to the object.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

One or more arguments are invalid.

Remarks

During asynchronous IMoniker::BindToObject bind operations, an asynchronous moniker calls this method to pass the requested object interface pointer to the client. This method is never called for IMoniker::BindToStorage operations.

See Also

[TOC]

IBindStatusCallback::OnLowResource [Beta]

An asynchronous moniker calls this method when it detects low resources.

HRESULT OnLowResource(
DWORD dwReserved // Reserved, must be 0
);

Parameters

dwReserved

[in]Reserved for future use. Must be zero.

Return Values

S_OK

The operation was successful.

Remarks

The moniker calls this method when it detects low resources. The client should free any resource it no longer needs when receiving this notification.

See Also

[TOC]

IBindStatusCallback::OnProgress [Beta]

Indicates the current progress of this bind operation.

HRESULT OnProgress(
ULONG ulProgress // Progress of bind operation
ULONG ulProgressMax // Expected max value of ulProgress
ULONG ulStatusCode, // BINDSTATUS value indicating bind progress
LPCWSTR szStatusText // Displayable information on progress of bind operation
);

Parameters

ulProgress

[in]Indicates the current progress of the bind operation relative to the expected maximum indicated in ulProgressMax.

ulProgressMax

[in]Indicates the expected maximum value of ulProgress for the duration of calls to OnProgress for this operation. Note that this value may change across invocations of this method.

ulStatusCode

Provides additional information regarding the progress of the bind operation. Valid values are taken from the BINDSTATUS enumeration.

szStatusText

Textual information about the current progress, appropriate for display in the user interface of the client.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The moniker calls this method repeatedly to indicate the current progress of this bind operation, typically at reasonable intervals during a lengthy operation.

The client may use the progress notification to provide progress information to the user (ulProgress/ulProgressMax and szStatusText) or to make programmatic decisions based on ulStatusCode.

See Also

BINDSTATUS

[TOC]

IBindStatusCallback::OnStartBinding [Beta]

Tells the client which callback methods it is registered for receiving. This is a response to the flags the client requested in RegisterBindStatusCallback .

HRESULT GetBindInfo(
DWORD grfBSCOption, // BSC_OPTION flags
IBinding * pbinding// Points to the IBinding interface for the current bind operation
);

Parameters

grfBSCOption

[in]Flags from the BSC_OPTION enumeration that specify what callback notifications the client is registered for receiving.

pbinding

The IBinding interface of the current bind operation. May not be NULL. The client should call AddRef on this pointer if it wishes to keep a reference to the binding object.

Return Values

S_OK

The operation was successful.

E_INVALIDARG

The pbinding argument is invalid.

Remarks

Asynchronous monikers typically call this method while initiating the bind operation, during IMoniker::BindToStorage or IMoniker::BindToObject.

This method tells the client which callback methods it is registered for receiving. This is a response to the flags the client requested in RegisterBindStatusCallback.

This notification also passes the binding object associated with the current bind operation to the client. The binding object allows control of the bind operation and the client may call it at any time.

To keep a reference to the binding object, the callee must store the pointer and call AddRef, and Release it when they are done. Calling Release does not cancel the bind operation, it simply frees the reference to the IBinding interface sent in the callback.

See Also

RegisterBindStatusCallback , IBinding

[TOC]

IBindStatusCallback::OnStopBinding [Beta]

An asynchronous moniker calls this method to indicate the end of the bind operation.

HRESULT OnStopBinding(
HRESULT hrStatus, // Bind operation status code
LPCWSTR szStatusText // Status text
);

Parameters

hrStatus

[in]Status code which would have been returned from the method that initiated the bind operation (IMoniker::BindToObject or IMoniker::BindToStorage).

szStatusText

Status text. In case of error, describes the error. In case of success, displays the friendly name of the data location bound to.

Return Values

S_OK

The operation was successful.

Remarks

The moniker calls this method to indicate the end of the bind operation. This method is always called, whether the bind operation succeeded, failed, or was aborted by a client. At this point the moniker client must call Release on the IBinding pointer it received in IBindStatusCallback::OnStartBinding.

See Also

IBinding

[TOC]

ICatInformation [Beta]

The ICatInformation interface provides methods for obtaining information about available categories.

When to Implement

Implement ICatInformation to manipulate the Registry keys under the CLSID root key.

When to Use

Call the methods of ICatInformation to obtain a listing of available categories, enumerate classes that belong to a particular category, and determine if a class belongs to a specific category.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

ICatInformation Methods Description
EnumCategories Returns an enumerator for the component categories registered for a specific CLSID, or for all component categories registered on the system.
GetCategoryDesc Retrieves the localized description string for a specific category ID.
EnumClassesOfCategory Returns an enumerator for the CLSIDs of all classses supporting a particular category.
IsClassOfCategory Determines if a class is of a particular category.

See Also

ICatRegister

[TOC]

ICatInformation::EnumCategories [Beta]

Returns an enumerator for the component categories registered for a specific CLSID, or for all the component categories registered on the system.

HRESULT EnumCategories(
LCID lcid, // Requested locale for returned szDescription of enumerated CATEGORYINFOs
REFCLSID rclsid, // The CLSID to be queried
IEnumCATEGORYINFO ppenumCatInfo, // Location in which to return an IEnumCATEGORYINFO interface
);

Parameters

lcid

[in] Identifies the requested locale for any return szDescription of the enumerated CATEGORYINFOs. Typically, the caller specifies GetUserDefaultLCID for this parameter.

rclsid

[in] Specifies the CLSID to be queried. If rclsid is CLSID_NULL, the enumerator returned will enumerate all component categories.

ppenumCatInfo

[out] Specifies the location to return an IEnumCATEGORYINFO interface. This can be used to enumerate the CATIDs and localized description strings of the component categories registered with the system.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

E_OUTOFMEMORY

Insufficient memory to create and return an enumerator object.

See Also

ICatInformation::GetCategoryDesc , ICatInformation::EnumClassesOfCategory , ICatInformation::IsClassOfCategory

[TOC]

ICatInformation::EnumClassesOfCategory [Beta]

Returns an enumerator over the CLSIDs of all the classes that support a particular category.

HRESULT EnumClassesOfCategory(
REFCATID rcatid, // Category identifier
IEnumCLSID** ppenumCLSID, // Location in which to return an IEnumCLSID interface
);

Parameters

rcatid

[in] The category identifier.

ppenumCLSID

[out] The location in which to return an IEnumCLSID interface that can be used to enumerate the CLSIDs of the classes specific to category rcatid.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

E_OUTOFMEMORY

Insufficient memory to create and return an enumerator object.

See Also

ICatInformation::EnumCategories , ICatInformation::GetCategoryDesc , ICatInformation::IsClassOfCategory

[TOC]

ICatInformation::GetCategoryDesc [Beta]

Retrieves the localized description string for a specific category ID.

HRESULT GetCategoryDesc(
REFCATID rcatid, // Category for which the string is to be returned
LCID lcid,// Locale in which the resulting string is returned
PWCHAR* ppszDesc, // Pointer to the string pointer that contains the description
);

Parameters

rcatid

[in] Identifies the category for which the description string is to be returned.

lcid

[in] Specifies the locale in which the resulting string is returned.

ppszDesc

[out] A pointer to the string pointer that contains the description. This must be released by the caller using CoMemTaskFree.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

E_OUTOFMEMORY

Insufficient memory to create and return an enumerator object.

CAT_E_CATIDNOEXIST

The category ID rcatid is not registered.

CAT_E_NODESCRIPTION

There is no description string for rcatid with the specified locale.

See Also

ICatInformation::EnumCategories , ICatInformation::EnumClassesOfCategory , ICatInformation::IsClassOfCategory

[TOC]

ICatInformation::IsClassOfCategory [Beta]

Determines if a class is of a particular category.

HRESULT IsClassOfCategory(
REFCLSID rclsid, // Class ID of the class to query
REFCATID rcatid// Identifies the category
);

Parameters

rclsid

[in] The class ID of the relevent class to query.

rcatid

[out] Identifies the category.

Return Values

S_OK

rclsid is of category rcatid.

S_FALSE

rclsid is not of category rcatid.

See Also

ICatInformation::EnumCategories , ICatInformation::GetCategoryDesc , ICatInformation::EnumClassesOfCategory

[TOC]

ICatRegister [Beta]

The ICatRegister interface provides methods for registering and unregistering component category information in the Registry.

When to Implement

Implement ICatRegister to manipulate the Registry keys under the CLSID root key.

When to Use

Call the methods of ICatRegister to register component categories or to remove the registration of component categories. Methods of this interface are also used to register category identifiers with a particular class or to remove category identifiers from a class.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

ICatRegister Methods Description
RegisterCategories Registers one or more component categories.
UnRegisterCategories Removes the registration of one or more component categories.
RegisterClassCategories Registers one or more category identifiers with a class.
UnRegisterClassCategories Removes one or more category identifiers from a class.

See Also

ICatInformationswp_ICatInformation 

[TOC]

ICatRegister::RegisterCategories [Beta]

Registers one or more component categories. Each component category consists of a CATID and a list of locale-dependent description strings.

HRESULT RegisterCategories(
ULONG cCategories, // Number of component categories
CATEGORYINFO rgCategoryInfo, // Array of cCagetories CATEGORYINFO structures
);

Parameters

cCategories

[in] The number of component categories to register.

rgCategoryInfo

[in] The array of cCategories CATEGORYINFO structures. By providing the same CATID for multiple CATEGORYINFO structures, multiple locales can be registered for the same component category.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

See Also

ICatRegister::UnRegisterCategories , ICatRegister::RegisterClassCategories , ICatRegister::UnRegisterClassCategories

[TOC]

ICatRegister::RegisterClassCategories [Beta]

Registers one or more category identifiers with a class.

HRESULT RegisterClassCategories(
REFCLSID rclsid, // Class ID of the relevent class
ULONG cCategories// Number of category GUIDs
CATID rgcatid, // Array of cCategories CATID
);

Parameters

rclsid

[in] The class ID of the relevent class for which category information will be set.

cCategories

[in] The number of category GUIDs to associate as category identifiers for the class.

rgcatid

[in] The array of cCategories CATID to associate as category identifiers for the class.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

Remarks

This function is not required in order to restore the state to the conditions prior to the call.

See Also

ICatRegister::RegisterCategories , ICatRegister::UnRegisterCategories , ICatRegister::UnRegisterClassCategories

[TOC]

ICatRegister::UnRegisterCategories [Beta]

Removes the registration of one or more component categories. Each component category consists of a CATID and a list of locale-dependent description strings.

HRESULT UnRegisterCategories(
ULONG cCategories, // Number of cCategories CATIDs
REFCATID rgcatid, // Array of cCategories TYPID
);

Parameters

cCategories

[in] The number of cCategories CATIDs to be removed.

rgcatid

[in] Identifies the categories to be removed.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

Remarks

This function will be successful even if one or more of the category IDs specified are not registered.

Note This method does not remove the component category tags from individual classes. To do this, use the ICatRegister::UnRegisterClassCategories method.

See Also

ICatRegister::RegisterCategories , ICatRegister::RegisterClassCategories , ICatRegister::UnRegisterClassCategories

[TOC]

ICatRegister::UnRegisterClassCategories [Beta]

Removes one or more category identifiers from a class.

HRESULT UnRegisterClassCategories(
REFCLSID rclsid, // Class ID of the relevent class
ULONG cCategories// Number of category GUIDs
CATID rgcatid, // Array of cCategories CATID
);

Parameters

rclsid

[in] The class ID of the relevent class to be manipulated.

cCategories

[in] The number of category GUIDs to remove.

rgcatid

[in] The array of cCategories CATID that are to be removed. Only the category IDs specified in this array are removed.

Return Values

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

Remarks

This function is not required in order to restore the state to the conditions prior to the call.

See Also

ICatRegister::RegisterCategories , ICatRegister::UnRegisterCategories , ICatRegister::RegisterClassCategories

[TOC]

IContinueCallback [Beta]

This interface is a generic callback mechanism for interruptible processes that should periodically ask an object with this interface whether to continue the process.

The FContinue function is a generic continuation request. FContinuePrinting carries extra information pertaining to a printing process and is used in the contect of IPrint.

Methods in VTable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces
AddRefIncrements reference count
ReleaseDecrements reference count

IContinueCallback Methods Description
FContinue Answers whether an operation should continue
FContinuePrinting Answers whether a printing operation should continue

[TOC]

IContinueCallback::FContinue [Beta]

Answer as to whether a given generic operation should continue.

HRESULT FContinue(void)

Return Values

S_OK

Continue the operation.

S_FALSE

Cancel the operation as soon as possible

[TOC]

IContinueCallback::FContinuePrinting [Beta]

Answer whether a given lengthy printing operation should continue.

HRESULT FContinuePrinting(
LONG cPagesPrinted // Total pages printed at time of call
LONG nCurrentPage// Number of page currently being printed
LPOLESTR pszPrintStatus // Pointer to status message about print job
);

Parameters

cPagesPrinted

The total number of pages that have been printed at the time the object receives a call to IContinueCallback::FContinuePrinting.

nCurrentPage

The page number of the page being printed at the time the object receives a call to IContinueCallback::FContinuePrinting.

pszPrintStatus

Pointer to message about the current status of the print job. The object being printed may or may not display this message to the user. May be NULL.

Return Values

S_OK

Continue the printing operation.

S_FALSE

Cancel the print job as soon as possible.

E_UNEXPECTED

An unknown error occurred.

Remarks

Implementations of IPrint call back on 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. Your Iprint implementation can legally call back multiple times with the same cPagesPrinted and nCurrentPage values, which is sometimes useful when a page being printed is complex and it is appropriate to give a user an opportunity to cancel mid-page.

See Also

IPrint

[TOC]

IDataPathBrowser [Beta]

This interface offers extended type-specific browsing capabilities such that a control can invoke a container-provided property-browsing user-interface if desired. Any property page that wishes to invoke a browsing user interface can query for IDataPathBrowser on the property page site object that it receives through IPropertyPage::SetPageSite. The presence of IDataPathBrowser indicates the possibility that the container supplies some type-specific browsing user interface. To invoke the container-provided user interface, the control calls the IDataPathBrowser::BrowseType method, passing the GUID identifying the type along with a default path and a buffer in which to store the selected path. If the browser supports the type identified with the GUID, it will display a user interface for that type and return any selection to the control.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IDataPathBrowser Methods Description
BrowseTypeInvokes a browsing user interface for the specified type.

[TOC]

IDataPathBrowser::BrowseType [Beta]

Instructs the browser to invoke a browsing user interface for the type identified with rguidPathType, if the user interface is available. If the user selects a path to data from within the user interface, the browser should return the string for that path in pszPath.

HRESULT BrowseType(
REFGUID rguidPathType, // GUID identifying the data type to browse
LPOLESTR pszDefaultType, // Default path string to display in the browsing user interface
ULONG cchPath,// Size of buffer pointed to by pszPath
LPOLESTR pszPath,// Receives the selected string
HWND hWnd// Parent window of the browsing user interface
);

Parameters

rguidPathType

[in] The GUID identifying the data type to browse.

pszDefaultPath

[in] The default path string to display in the browsing user interface.

cchPath

[in] The size of the buffer pointed to by pszPath.

pszPath

[out] The buffer to receive the selected string if the browsing is successful.

hWnd

[in] The window that should be the parent of the browsing user interface.

Return Values

S_OK

The browsing user interface was successfully displayed and a new path is returned in pszPath.

S_FALSE

The browsing user interface was successfully displayed but the user did not select a path (for example, the user may have pressed Cancel).

E_OUTOFMEMORY

There was not enough memory to display the user interface, but the browsing user interface is available.

E_FAIL

The site does not support browsing for the type specified in rguidPathType.

Remarks

E_NOTIMPL is not allowed¾without implementing the BrowseType method, the IDataPathBrowser interface is unnecessary.

[TOC]

IEnumHLITEM [Beta]

The IEnumHLITEM interface is used to enumerate an array of HLITEM structures in a hyperlink browse context navigation stack. IEnumHLITEM has the same methods as all enumerator interfaces: Next, Skip, Reset, Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumHLITEM must be implemented by all hyperlink browse context objects to support calls to IHlinkBrowseContext::EnumNavigationStack, which supplies a pointer to the enumerator's IEnumHLITEM interface. Because there is a default implementation of IHlinkBrowseContext, you do not normally need to implement this interface.

When to Use

You do not normally need to call this interface directly. The default implementation of IHlinkBrowseContext calls this interface to examine the HLITEM structures in the browse context's navigation stack to determine which hyperlink sources have been previously visited.

The prototypes of the methods are as follows:

HRESULT Next(
ULONG celt, // Number of HLITEM structures returned in rgelt
HLITEM * rgelt,// Array to receive enumerated HLITEM structures
ULONG *pcFetched// Location for actual number of HLITEM structures
);

HRESULT Skip(
ULONG cHlitems // Number of elements to skip
);

HRESULT Reset(void);

HRESULT Clone(
IEnumHLITEMs **ppEnumHlitems // Location for newly created enumerator list
);

Remarks

IEnumHLITEM::Next

Retrieves the next celt HLITEMs in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched.

IEnumHLITEM::Skip

Skips the next celt HLITEMs in the enumeration sequence.

IEnumHLITEM::Reset

Resets the enumeration sequence to the beginning. There is no guarantee that the same set of elements will be enumerated after the Reset, because it depends on the implementation doing the enumeration. It can be too expensive for some collections to guarantee this condition or it may not be possible due to concurrent access to the same collection by multiple threads or processes.

IEnumHLITEM::Clone

Creates another enumerator that contains the same state as the current enumerator to iterate over the same list. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

See Also

IHlinkBrowseContext::EnumNavigationStack, HLITEM, IEnumXXXX

[TOC]

IEnumHLITEM::Next [Beta]

Retrieves the next celt HLITEMs in the enumeration sequence.

HRESULT IEnumHLITEM::Next(
ULONG celt // Number of elements to retrieve
HLITEM * rgelt
// Location to return at most celt HLITEM structures
ULONG * pceltFetched // Location to return actual number of elements returned in rgelt
);

Parameters

celt

[in] The number of elements to retrieve.

rgelt

[out] Location to return a maximum of celt HLITEM structures. This may not be NULL.

pceltFetched

[out] Location to return the actual number of elements returned in rgelt. May be NULL if the caller is not interested in the actual number of elements returned.

Return Values

S_OK

Indicates all of the elements specified by celt have been successfully supplied.

S_FALSE

Indicates fewer than the number of elements specified by celt have been successfully supplied. The number actually supplied (including zero) is in rgelt and their values reached through pceltFetched, if non-NULL.

See Also

[TOC]

IEnumHLITEM::Skip [Beta]

Skips the next celt HLITEMs in the enumeration sequence.

HRESULT IEnumHLITEM::Skip(
ULONG celt // Number of elements to skip
);

Parameters

celt

[in] The number of elements to skip.

Return Values

S_OK

Indicates all of the elements specified by celt have been successfully skipped.

S_FALSE

Indicates fewer than the number of elements specified by celt, and possibly zerio elements, have been successfully skipped. This indicates that the enumerator has reached the end of the collection.

See Also

TBD

[TOC]

IEnumHLITEM::Reset [Beta]

Resets the enumeration sequence to the beginning.

HRESULT IEnumHLITEM::Reset(
);

Return Values

S_OK

Indicates the enumeration sequence has been reset to the beginning.

See Also

TBD

[TOC]

IEnumHLITEM::Clone [Beta]

Creates another enumerator with the same enumeration state as the current one.

HRESULT IEnumHLITEM::Clone(
IEnumHLITEM ** ppenumhlitem // Location to return the new enumerator
);

Parameters

ppenumhlitem

[out] Location to return the new enumerator. Must be cleared to NULL on failure.

Return Values

S_OK

Indicates the enumerator has been duplicated successfully.

E_OUTOFMEMORY

Indicates insufficient memory to create the new enumerator.

[TOC]

IEnumOleDocumentViews [Beta]

The IEnumOleDocumentViews interface is used to enumerate the views supported by a document object. IEnumOleDocumentViews has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, see IEnumXXX.

The resulting enumerator returned by this mtehod implements the interface IEnumOleDocumentViews through which a client can access all the individual document view objects supported by the document object itself, where each view implements IOleDocumentView .

When to Implement

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

When to Use

Use the IEnumOleDocumentViews to enumerate all the views supported by a document object. The usual procedure is to first call IOleDocument::EnumViews . If the document object supports only one view, it will return a pointer to that view. If the document object supports two or more views, it will return a pointer to IEnumOleDocumentViews. Using this pointer, the container can then ask the document object to enumerate the views it supports.

The prototypes of the methods are as follows:

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

HRESULT Skip([in] ULONG cViews

HRESULT Reset(void)

HRESULT Clone([out] IEnumOleDocumentViews ** ppenum)

Remarks

IEnumOleDocumentViews::Next

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 caller is responsible for calling IOleDocumentView::Release through each pointer returned in rgpView.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpView array are valid on exit and require no release.

cViews

[in] Specifies the number of IOleDocumentView pointers to return in the array pointed to by rgpView. This argument must be 1 if pcFetched is NULL.

rgpView

[out, max_is(cViews)] A pointer to a caller-allocated IOleDocumentView * array of size cViews in which to return the enumerated connection points. The caller is responsible for calling IOleDocumentView::Release through each pointer enumerated into the array once this method returns successfully. If cViews is greater than 1 the caller must also pass a non-NULL pointer passed to pcFetched to know how many pointers to release.

pcFetched

[out] A Indirect pointer to the actual number of views enumerated in rgpView. This argument can be NULL in which case the cViews argument must be 1.

IEnumOleDocumentViews::Skip

Instructs the enumerator to skip the next cViews elements in the enumeration such that the next call to IEnumOleDocumentViews::Next will not return those elements.

cViews

[in] Specifies the number of elements to skip in the enumeration.

IEnumOleDocumentViews::Reset

Instructs the enumerator to position itself at 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::Clone

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

ppEnum

[out] A Indirect pointer to the IEnumOleDocumentViews interface for the newly created enumerator. The caller must release this enumerator separately from the one from which it was cloned.

[TOC]

IErrorLog [Beta]

The IErrorLog interface is an abstraction for an error log that is used to communicate detailed error information between a client and an object. The caller of the single interface method, AddError, simply logs an error where the error is an EXCEPINFO structure attached to a specific property. The implementor of the interface is responsible for handling the error in whatever way it desires.

IErrorLog is used in the protocol between a client that implements IPropertyBag and an object that implements IPersistPropertyBag.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IErrorLog Method Description
AddErrorLogs an error (an EXCEPINFO structure) in the error log for a named property.

See Also

IPersistPropertyBag , IPropertyBag

[TOC]

IErrorLog::AddError [Beta]

Logs an error (an EXCEPINFO structure) in the error log for a named property.

HRESULT AddError(
LPCOLESTR pszPropName, // Points to the name of the property involved with the error
LPEXCEPINFO pException // Points to the caller-initialized EXCEPINFO structure describing the error
);

Parameters

pszPropName

[in] The name of the property involved with the error. Cannot be NULL.

pExcepInfo

[in] The address of the caller-initialized EXCEPINFO structure that describes the error to log. Cannot be NULL.

Return Values

S_OK

The error was logged successfully.

E_FAIL

There was a problem logging the error.

E_OUTOFMEMORY

There was not enough memory to log the error.

E_POINTER

The address in pszPropName or pExceptInfo is not valid (such as NULL). The caller must supply both.

Remarks

E_NOTIMPL is not a valid return code as the method is the only one in the entire interface.

[TOC]

IHlink [Beta]

The IHlink interface enables a COM object known as a hyperlink to completely encapsulate the behavior of navigating to its target location.

Hyperlinks are managed by COM hyperlink container objects, which support the IHlinkSite interface for hyperlinks within the container and the IHlinkTarget interface for hyperlinks referring to documents or document objects within it.

IHlink provides methods for a hyperlink object to navigate to its target, access a friendly name for display purposes, and identify itself to its container and frame.

When to Implement

Typically, you do not need to implement this interface. A standard implementation of a hyperlink component is provided as part of the system, and it is not advisable to implement another version. A document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the capability of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. The standard hyperlink object implements IHlink, IPersistStream, and IDataObject interfaces.

When to Use

IHlink interfaces are typically called by an application's hyperlink container as part of a user interface for creating new hyperlinks. Standard hyperlink objects are created via the HlinkCreateFromData , HlinkCreateFromMoniker , HlinkCreateFromString , and OleLoadFromStream APIs.

While the hyperlink object provides many useful functions that are needed for general purpose uses, often applications are only interested in navigating to a hyperlink target. For simple navigation needs, there are a number of "helper" APIs such as HlinkSimpleNavigateToString , HlinkSimpleNavigateToMoniker , and HlinkNavigateToStringReference that allow simple hyperlink navigation without any knowledge of other hyperlink interfaces or objects.

Hyperlink navigation involves transitioning from one document/object/application, known as the hyperlink container, to another document/object/application, known as the hyperlink target. Usually, both remain running, but the hyperlink target visually replaces the hyperlink container (from which the navigation originated). There are three "flavors" of hyperlink containers and targets.

1. Top-level documents.

2. OLE Document objects in a browser.

3. OLE Document objects in an Office Binder-like application that does not support OLE in-place/DocObj server functionality, and hence cannot be shown in-place in a browser.

The following are possible forms of navigation:

1. From one top-level document to another top-level document (for example, between Office documents in the absence of a browser).

2. From a top-level document to an OLE Document in a browser (for example, from a stand-alone application to an HTML document).

3. From one OLE document object in a browser to another OLE document object in the same browser (for example, one HTML document to another).

4. From one OLE document object in a browser to an OLE document object in a Binder-type application (for example, if the hyperlink target is embedded as an OLE Document Object in an Office Binder document; in this scenario, the end user model gets complicated and confusing if the embedded OLE Document Object is shown in the browser's window, instead of letting it appear in its own container's window).

5. From one location in an object/document to another location in the same object/document (applicable to all three flavors of hyperlink containers/hyperlink targets).

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IHlink Methods Description
SetHlinkSiteSaves the interface pointer on the site object.
GetHlinkSiteRetrieves the interface pointer on the site object.
GetMonikerReferenceRetrieves the moniker and location portions of the target.
GetStringReferenceRetrieves the name and location portions of the target.
GetFriendlyNameRetrieves the friendly name of the target.
SetFriendlyNameSets the friendly name of the target.
GetTargetFrameNameRetrieves the name of the target frame.
SetTargetFrameNameSets the name of the target frame.
GetAdditionalParamsRetrieves additional hyperlink parameters.
SetAdditionalParamsSets additional hyperlink parameters.
NavigateNavigates to the given target.
GetMiscStatusQueries if hyperlink is absolute or relative.

See Also

HlinkSimpleNavigateToMoniker , HlinkSimpleNavigateToString , HlinkNavigateToStringReference

[TOC]

IHlink::GetAdditionalParams [Beta]

Retrieves additional parameters or properties for the hyperlink.

HRESULT IHlink::GetAdditionalParams(
LPWSTR * pszAdditionalParams // Extensible parameter string
);

Parameters

pszAdditionalParams

[out] On return, points to the location to return the string containing a list of parameters or properties for the hyperlink in the following format:

  ... 


Return Values

S_OK

The hyperlink's additional parameters string was retrieved.

Remarks

The parameters retrieved in this string are primarily interpreted by the hyperlink frame.

See Also

IHlink:SetAdditionalParams

[TOC]

IHlink::GetFriendlyName [Beta]

Retrieves the friendly name of the target. The container normally uses this name to determine how to represent the hyperlink in its user interface.

HRESULT IHlink::GetFriendlyName(
DWORD grfHLFNAMEF // TBD
LPWSTR * pszFriendlyName // Receives the friendly name of the hyperlink target.
);

Parameters

grfHLFNAMEF

[in] TBD.

pszFriendlyName

[out] On return, points to the friendly name of the hyperlink target. May not be NULL.

Return Values

S_OK

The friendly name string of the hyperlink was retrieved.

See Also

IHlink::SetFriendlyName , IHlinkTarget::GetFriendlyName

[TOC]

IHlink::GetHlinkSite [Beta]

Retrieves the hyperlink site and associated site data from a hyperlink object.

HRESULT IHlink::GetHlinkSite(
IHlinkSite ** pphlSite // Receives the hyperlink site interface
DWORD *pdwSiteData// Receives additional site data
);

Parameters

pphlSite

[out] On return, points to the IHlinkSite interface pointer on the hyperlink object. This may not be a NULL pointer on input.

pdwSiteData

[in, out] On return, points to the site data of the hyperlink target. This may not be a NULL pointer on input.

Return Values

S_OK

The hyperlink site and associated data have been successfully retrieved.

See Also

IHlink::SetHlinkSite

[TOC]

IHlink::GetMiscStatus [Beta]

Queries whether or not the hyperlink is an absolute or a relative link.

HRESULT IHlink::GetHlinkSite(
DWORD * pdwStatus // Receives absolute/relative status of hyperlink
);

Parameters

pdwStatus

[out] On return, points to a value from the HLINKMISC enumeration. May not be NULL.

Return Values

S_OK

The hyperlink status has been successfully retrieved.

See Also

HLINKMISC

[TOC]

IHlink::GetMonikerReference [Beta]

Retrieves the moniker and location portions of the hyperlink reference.

HRESULT IHlink::GetMonikerReference(
DWORD dwWhichRef // Absolute or relative reference
IMoniker ** ppmk// Receives a pointer to the moniker of the hyperlink target
LPWSTR * pszLocation // Receives the location portion of the hyperlink target
);

Parameters

dwWhichRef

[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.

ppmk

[out] On return, points to the IMoniker pointer of the target's moniker object, if any. May be NULL, in which case the caller is not interested in the moniker to the hyperlink reference.

pszLocation

[in,out,unique] On return, points to the string location portion of the target, if any. If NULL, the caller is not interested in the location portion of the hyperlink reference.

Return Values

S_OK

Indicates the moniker and location portions of the target of the hyperlink target have been successfully supplied.

See Also

HLINKGETREF , IHlinkSite::GetMoniker , IHlinkTarget::GetMoniker

[TOC]

IHlink::GetStringReference [Beta]

Retrieves strings that identify the hyperlink target and the location within the hyperlink target.

HRESULT IHlink::GetStringReference(
DWORD dwWhichRef // Absolute or relative reference
LPWSTR * pszTarget// Receives the string that helps identify the hyperlink target
LPWSTR * pszLocation // Receives the location portion of the hyperlink target
);

Parameters

dwWhichRef

[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.

pszTarget

[out] On return, points to a string that helps identify the hyperlink target of the hyperlink reference. If NULL, the caller is not interested in the target string of the hyperlink reference.

pszLocation

[out] On return, points to the location portion of the hyperlink reference. If NULL, the caller is not interested in the location portion of the hyperlink reference.

Return Values

S_OK

Indicates the target and location strings of the hyperlink target have been successfully supplied.

See Also

HLINKGETREF , HlinkNavigateToStringReference , HlinkSimpleNavigateToString , IHlink::GetMonikerReference

[TOC]

IHlink::GetTargetFrameName [Beta]

Retrieves the name of the target frame for the hyperlink.

HRESULT IHlink::GetTargetFrameName(
LPWSTR * pszTargetFrameName // Receives the target frame name for the hyperlink
);

Parameters

pszTargetFrameName

[out] On return, points to the target frame name for the hyperlink. May not be NULL.

Return Values

S_OK

The target frame name string for the hyperlink was retrieved.

See Also

IHlink::SetTargetFrameName

[TOC]

IHlink::Navigate [Beta]

Navigates to the hyperlink reference. IHlink::Navigate is the heart of the navigation process that implements the action of resolving a hyperlink target.

HRESULT IHlink::Navigate(
DWORD grfHLNF // Navigation flags
IBindCtx * pbc// Bind context interface pointer
IBindStatusCallback * pbsc // Bind-status-context interface pointer
IHlinkBrowseContext * phlbc // Browse context interface pointer
);

Parameters

grfHLNF

[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.

pbc

[in] IBindCtx interface pointer to the bind context to be used for any moniker binding during this operation. May not be NULL.

pbsc

[in] IBindStatusCallback interface pointer to the bind status context to use for any asynchronous moniker binding performed during the navigation. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information

phlbc

[in] Pointer to the IHlinkBrowseContext interface to use for this navigation. May not be NULL. As part of navigation, this browse context's navigation stack may be updated (depending on the navigation flags in grfHLNF) and its cache of hyperlink targets is consulted for a matching to the current hyperlink target.

Return Values

S_OK

Navigation to the hyperlink has been completed successfully.

HLINK_S_NAVIGATEDTOLEAFNODE


See Also

HlinkNavigate , HLNF , IHlinkFrame::Navigate , IHlinkTarget::Navigate

[TOC]

IHlink::SetAdditionalParams [Beta]

Sets the additional parameters or properties for the hyperlink.

HRESULT IHlink::SetAdditionalParams(
LPCWSTR szAdditionalParams // Extensible parameter string
);

Parameters

szAdditionalParams

[in] The string containing a list of parameters or properties for the hyperlink in the following format:

  ... 


Return Values

S_OK

The hyperlink's additional parameters string was set.

Remarks

The parameters saved in this string are primarily interpreted by the hyperlink frame.

See Also

IHlink::GetAdditionalParams

[TOC]

IHlink::SetFriendlyName [Beta]

Sets the friendly name for the hyperlink. The friendly name is used by hyperlink containers to represent the hyperlink within their user interface.

HRESULT IHlink::SetFriendlyName(
LPCWSTR szFriendlyName // Friendly name of the hyperlink
);

Parameters

szFriendlyName

[in]The friendly name string of the hyperlink target.

Return Values

S_OK

The friendly name string of the hyperlink was set.

See Also

IHlink::GetFriendlyName

[TOC]

IHlink::SetHlinkSite [Beta]

Sets the hyperlink site and associated site data on a hyperlink object.

HRESULT IHlink::SetHlinkSite(
IHlinkSite * phlSite // Interface pointer to the new hyperlink site
DWORD dwSiteData// Additional site data
);

Parameters

phlSite

[in] Pointer to a new IHlinkSite object for this hyperlink.

dwSiteData

[in] DWORD that specifies additional information about the site. For instance, each site may differ in color or style from other sites in the same container.

Return Values

S_OK

The hyperlink site object and its site data have been successfully set.

See Also

IHlink::GetHlinkSite

[TOC]

IHlink::SetTargetFrameName [Beta]

Sets the target frame name for the hyperlink.

HRESULT IHlink::SetTargetFrameName(
LPCWSTR szTargetFrameName // Target frame name for the hyperlink
);

Parameters

szTargetFrameName

[in] The string target frame name for the hyperlink.

Return Values

S_OK

The target frame name string for the hyperlink was set.

See Also

IHlink::GetTargetFrameName

[TOC]

IHlinkBrowseContext [Beta]

The IHlinkBrowseContext interface enables a COM object to define and manage the browsing context for an OLE hyperlink application.

A hyperlink browse context keeps track of the order in which the object/documents (perhaps belonging to different processes) have been visited and chains them together into a navigation stack. The context also keeps track of enabling or disabling buttons like Go Forward or Go Back for each entry in the navigation stack. In addition, the context maintains window positioning information for hyperlink targets so that a hyperlink application can provide a seamless user-interface.

Browse context objects are not required for hyperlink navigation. HlinkSimpleNavigateToString and HlinkSimpleNavigateToMoniker provide examples of navigation between hyperlink containers and hyperlink targets that do not use a browsing context.

IHlinkBrowseContext provides methods that maintain the hyperlink navigation stack and keep track of window position information.

When to Implement

The system provides a default implementation.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IHlinkBrowseContext Methods Description
RegisterRegisters an object with the browse context.
GetObjectRetrieves an object previously registered in the browse context under the given name.
RevokeRevokes an object previously registered with this browse context.
SetBrowseWindowInfoEstablishes the browse window info structure of this browse context.
GetBrowseWindowInfoRetrieves the browse window info structure associated with this browse context.
EnumNavigationStackRetrieves an enumerator which can be used to enumerate the current contents of the navigation stack.
QueryHlinkTests the validity of a hyperlink ID value.
GetHlinkRetrieves a hyperlink from this browse context.
SetCurrentHlinkSets the current hyperlink in this browse context's navigation stack.
OnNavigateHlinkNotifies a browse context that a hyperlink has been navigated.
CloneDuplicates a browse context.
CloseCloses the hyperlink browse context.

See Also

HlinkCreateBrowseContext , IHlink , IHlinkFrame , IHlinkTarget

[TOC]

IHlinkBrowseContext::Clone [Beta]

Duplicates a browse context.

HRESULT IHlinkBrowseContext::Clone(
IUnknown* punkOuter // Controlling IUnknown interface for possible aggregation
REFIID riid// Interface ID to return on the new browse context
void** ppv// Receives the requested interface's pointer
);

Parameters

punkOuter

[in] Pointer to the controlling IUnknown interface for the new hyperlink object. If NULL, the new hyperlink object is not aggregated.

riid

[in] The interface to return on the new hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter is non-NULL.

ppv

[out] Receives the pointer to the riid interface.

Return Values

S_OK

The browse context has been duplicated.

[TOC]

IHlinkBrowseContext::Close [Beta]

Closes the hyperlink browse context. Releases all hyperlink targets that have been registered with the browse context.

HRESULT IHlinkBrowseContext::Close(
DWORD dwReserved // Reserved for future use
);

Parameters

dwReserved

[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

Return Values

S_OK

The hyperlink browse context has been successfully closed.

See Also

IHlinkBrowseContext::Register

[TOC]

IHlinkBrowseContext::EnumNavigationStack [Beta]

Retrieves an enumerator which can be used to enumerate the current contents of the navigation stack.

HRESULT IHlinkBrowseContext::EnumNavigationStack(
IEnumHLITEM ** ppenumhlitem // Location to receive the enumeration interface pointer
);

Parameters

ppenumhlitem

[out] Location to return the IEnumHLITEM enumeration interface over the set of hyperlinks in this navigation stack.

Return Values

S_OK

The enumerator has been successfully retrieved.

See Also

HLID , HLITEM , IEnumHLITEM

[TOC]

IHlinkBrowseContext::GetBrowseWindowInfo [Beta]

Retrieves the HLBWINFO structure currently associated with this browse context.

HRESULT IHlinkBrowseContext::GetBrowseWindowInfo(
HLBWINFO * phlbwi // Location to receive the HLBWINFO structure
);

Parameters

phlbwi

[out] Pointer to the location to return the current HLBWINFO structure.

Return Values

S_OK

The HLBWINFO structure for this browse window has been retrieved.

See Also

HLBWINFO , IHlinkBrowseContext::SetBrowseWindowInfo

[TOC]

IHlinkBrowseContext::GetHlink [Beta]

Retrieves a hyperlink from this browse context.

HRESULT IHlinkBrowseContext::GetHlink(
ULONG uHLID // Hyperlink to retrieve
IHlink ** pphl// Buffer to return the IHlink interface of the hyperlink
);

Parameters

uHLID

[in] Identifies the hyperlink to retrieve. May be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

pphl

[out] Pointer to the buffer to return the IHlink interface pointer of the hyperlink object.

Return Values

S_OK

The hyperlink has been successfully retrieved from this browse context.

E_FAIL

Indicates the specified hyperlink does not exist in this browse context.

See Also

HLID , IHlink , IHlinkBrowseContext::SetCurrentHlink

[TOC]

IHlinkBrowseContext::GetObject [Beta]

Retrieves an object previously registered in the browse context.

HRESULT IHlinkBrowseContext::GetObject(
IMoniker * pmk // Moniker interface pointer of the object being retrieved
IUnknown ** ppunk// Location to receive the unknown interface pointer of requested object
);

Parameters

pmk

[in,unique] Identifies the object being retrieved.

ppunk

[out] Location to return the IUnknown interface of the object being retrieved.

Return Values

S_OK

Indicates the previously registered object has been retrieved.

S_FALSE

Indicates no object indicated by pmk was registered in the browse context.

See Also

IHlinkBrowseContext::Register

[TOC]

IHlinkBrowseContext::OnNavigateHlink [Beta]

Notifies a browse context that a hyperlink has been navigated.

HRESULT IHlinkBrowseContext::OnNavigateHlink(
DWORD grfHLNF // Navigation flags
IMoniker * pmkTarget // Moniker interface pointer of the hyperlink target
LPCWSTR pszLocation// Location within the hyperlink target of new hyperlink
LPCWSTR szFriendlyName // Friendly name of the hyperlink
);

Parameters

grfHLNF

[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.

pmkTarget

[in] Pointer to an IMoniker interface on the hyperlink target.

pszLocation

[in] A string identifying the location within the hyperlink target that was navigated to. May not be NULL.

szFriendlyName

[in] The friendly name of the location within the hyperlink target that has been navigated to. May not be NULL.

Return Values

S_OK

The browse context has been successfully notified that a hyperlink has been navigated.

See Also

HlinkOnNavigate , HLNF , IHlinkFrame::OnNavigate , IHlinkSite::OnNavigationComplete

[TOC]

IHlinkBrowseContext::QueryHlink [Beta]

Tests the validity of a uHLID value.

HRESULT IHlinkBrowseContext::QueryHlink(
DWORD grfHLQF // Value from the HLQF enumeration
ULONG uHLID// Hyperlink identifier to query
);

Parameters

grfHLQF

[in] A single value taken from the HLQF enumeration.

uHLID

[in] Identifies the hyperlink to query about. May be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

Return Values

S_OK

If grfHLQF is HLQF_ISVALID, uHLID identifies a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID identifies the current hyperlink of the browse context.

S_FALSE

If grfHLQF is HLQF_ISVALID, uHLID does not identify a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID does not identify the current hyperlink of the browse context.

See Also

HLID , HLQF

[TOC]

IHlinkBrowseContext::Register [Beta]

Registers an object with the browse context.

HRESULT IHlinkBrowseContext::Register(
DWORD dwReserved // Reserved for future use
IUnknown punk// Object being registered
IMoniker * pmk// Moniker interface pointer of the object being registered
DWORD * pdwRegister// Receives the registration value
);

Parameters

dwReserved

[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

punk

[in, unique] The object being registered.

pmk

[in, unique] Pointer to the IMoniker interface pointer that identifies the object being registered.

pdwRegister

[out] Pointer to a location to return a value identifying the registration which can be used to subsequently revoke the registration.

Return Values

S_OK

The object has been registered.

MK_S_MONIKERALREADYREGISTERED

The object was successfully registered, but another object (possibly the same object) has already been registered with the same moniker in this browse context.

E_OUTOFMEMORY

There was insufficient memory to register the object with the browse context.

See Also

HlinkCreateBrowseContext , IHlinkBrowseContext::Close , IHlinkBrowseContext::Revoke

[TOC]

IHlinkBrowseContext::Revoke [Beta]

Revokes an object previously registered with this browse context.

HRESULT IHlinkBrowseContext::Revoke(
DWORD dwRegister // Object to revoke
);

Parameters

dwRegister

[in] Identifies the object to revoke. Returned by a previous call to IHlinkBrowseContext::Register.

Return Values

S_OK

The previously-registered object has been revoked from this browse context.

See Also

IHlinkBrowseContext::Register

[TOC]

IHlinkBrowseContext::SetBrowseWindowInfo [Beta]

Establishes the HLBWINFO structure of this browse context.

HRESULT IHlinkBrowseContext::SetBrowseWindowInfo(
HLBWINFO * phlbwi // Pointer to the new HLBWINFO structure for this browse context
);

Parameters

phlbwi

[in,unique] Pointer to the new HLBWINFO structure for this browse context.

Return Values

S_OK

The HLBWINFO structure for this browse window has been established.

See Also

HLBWINFO , IHlinkBrowseContext::GetBrowseWindowInfo

[TOC]

IHlinkBrowseContext::SetCurrentHlink [Beta]

Sets the current hyperlink in this browse context's navigation stack.

HRESULT IHlinkBrowseContext::SetCurrentHlink(
ULONG uHLID // Hyperlink ID to set in the navigation stack
);

Parameters

uHLID

[in] Identifies the hyperlink to set in the current browse context's navigation stack. May be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

Return Values

S_OK

This hyperlink has been successfully set in the current browse context's navigation stack.

E_FAIL

Indicates the specified hyperlink does not exist in this browse context.

See Also

HLID , IHlinkBrowseContext::GetHlink

[TOC]

IHlinkFrame [Beta]

The IHlinkFrame interface provides methods that allow a hyperlink frame to interpose itself in the navigation process to allow an application to provide a seamless user interface when navigating from one document/object/application to another when resolving a hyperlink.

When to Implement

When to Use

You do not normally call the IHlinkFrame methods directly. They are referenced by the IHlink::Navigate routines when a hyperlink frame is detected.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IHlinkFrame Methods Description
GetBrowseContextRetrieves the browse context of the hyperlink frame
NavigateNavigates to the target hyperlink
OnNavigateNotifies the hyperlink frame of a hyperlink navigation
SetBrowseContextSets the browse context of the hyperlink frame

See Also

HlinkNavigate , HlinkNavigateToStringReference , HlinkSimpleNavigateToString , HlinkSimpleNavigateToMoniker , IHlink

[TOC]

IHlinkFrame::GetBrowseContext [Beta]

Retrieves the browse context of the hyperlink frame.

HRESULT IHlinkFrame::GetBrowseContext(
IHlinkBrowseContext ** pphlbc // Buffer to receive the interface of the current browse context
);

Parameters

pphlbc

[out] Location to return the browse context interface's pointer.

Return Values

S_OK

The browse context has been successfully retrieved.

E_NOTIMPL

The hyperlink target does not understand browse contexts.

See Also

HlinkCreateBrowseContext , IHlinkBrowseContext , IHlinkFrame::SetBrowseContext , IHlinkTarget

[TOC]

IHlinkFrame::Navigate [Beta]

Navigates to the hyperlink target.

HRESULT IHlinkFrame::Navigate(
DWORD grfHLNF // How to navigate
IBindCtx * pbc// Bind context interface pointer
IBindStatusCallback * pbsc // Bind-status callback interface pointer
IHlink * phlNavigate // Hyperlink target interface pointer
);

Parameters

grfHLNF

[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.

pbc

[in] Pointer to the IBindCtx object interface to use for any moniker binding during this operation. May not be NULL.

pbsc

[in] Pointer to the IBindStatusCallback object interface to use for any asynchronous moniker binding performed during the navigation. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.

phlNavigate

[in] Pointer to the IHlink object interface to the hyperlink target.

Return Values

S_OK

The navigation to the target has been successful.

IHlink::Navigate errors

Since IHlinkFrame::Navigate calls IHlink::Navigate, the errors associated with this method can be returned.

See Also

HLNF , IHlink::Navigate

[TOC]

IHlinkFrame::OnNavigate [Beta]

Notifies the hyperlink frame that a hyperlink has been navigated to.

HRESULT IHlinkFrame::OnNavigate(
DWORD grfHLNF // Navigation flags
);

Parameters

grfHLNF

[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.

Return Values

S_OK

The hyperlink frame has been successfully notified.

See Also

HlinkOnNavigate , HLNF , IHlinkBrowseContext::OnNavigateHlink , IHlinkSite::OnNavigationComplete

[TOC]

IHlinkFrame::SetBrowseContext [Beta]

Sets the browse context of the hyperlink frame.

HRESULT IHlinkFrame::GetBrowseContext(
IHlinkBrowseContext * phlbc // Interface pointer of the current browse context
);

Parameters

phlbc

[in] The browse context interface's pointer.

Return Values

S_OK

The browse context has been successfully set.

E_NOTIMPL

The hyperlink target does not understand browse contexts.

See Also

HlinkCreateBrowseContext , IHlinkBrowseContext , IHlinkFrame::SetBrowseContext , IHlinkTarget::SetBrowseContext

[TOC]

IHlinkSite [Beta]

The IHlinkSite interface provides methods for a hyperlink to retrieve the moniker or the interface on its hyperlink container. The navigation process which resolves a hyperlink uses this information to efficiently handle internal (within the same container) and external (to a different container) hyperlink references.

When to Implement

Implement IHlinkSite when you want to hyperlink to other documents. For each hyperlink object provided by the system, a third party, or that you create, you provide an IHlinkSite object. One site object can support multiple hyperlinks.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IHlinkSite Methods Description
GetMonikerRetrieves the moniker to the hyperlink target.
GetInterfaceRetrieves the interface to the hyperlink target.
OnNavigationCompleteNotifies the hyperlink site that hyperlink navigation is complete.

See Also

IHlink

[TOC]

IHlinkSite::GetInterface [Beta]

Retrieves the hyperlink target interface on a hyperlink's container (usually the document that contains the hyperlink site).

HRESULT IHlinkSite::GetInterface(
DWORD dwSiteData // Site data to identify the hyperlink its site
DWORD dwReserved// Reserved for future use
REFIID riid// Interface ID to return on the hyperlink container
Void* ppv// Buffer to receive the riid interface
);

Parameters

dwSiteData

[in] Identifies the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite .

dwReserved

[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

riid

[in] Identifies the interface to return.

ppv

[out] Location to return the riid interface.

Return Values

S_OK

The hyperlink container interface was successfully retrieved.

E_NOINTERFACE

The desired interface is not available.

See Also

IHlinkSite::GetMoniker

[TOC]

IHlinkSite::GetMoniker [Beta]

Returns the relative moniker of the hyperlink's container.

HRESULT IHlinkSite::GetMoniker(
DWORD dwSiteData // Site data for the new hyperlink object
DWORD dwAssign// Whether or not to create a moniker if one not found
DWORD dwWhich// Which moniker to retrieve
IMoniker ** ppmk// Buffer to receive the requested moniker interface pointer
);

Parameters

dwSiteData

[in] Identifies the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite .

dwAssign

[in] A value from the OLEGETMONIKER enumeration. This is typically either OLEGETMONIKER_ONLYIFTHERE, indicating the function should not force a moniker to be created if one does not already exist, or OLEGETMONIKER_FORCEASSIGN, indicating that the function should create a moniker if one does not exist.

dwWhich

[in] A value from the OLEWHICHMK enumeration. This is typically OLEWHICHMK_CONTAINER, indicating that the site should return the moniker of the hyperlink container.

ppmk

[out] Location to return the IMoniker interface.

Return Values

S_OK

Indicates the moniker of the hyperlink's site container was successfully supplied.

E_FAIL

Indicates a moniker does not exist for this hyperlink target and OLEGETMONIKER_ONLYIFTHERE was specified for dwAssign.

See Also

IHlink::GetMonikerReference , IHlinkSite::GetInterface , IHlinkTarget::GetMoniker

[TOC]

IHlinkSite::OnNavigationComplete [Beta]

Notifies the hyperlink site that a hyperlink navigation has been successful. This notification in particularly useful if the hyperlink has been navigated asynchronously because it is the only notification the hyperlink receives to realize that hyperlinking has completed.

HRESULT IHlinkSite::OnNavigationComplete(
DWORD dwSiteData // Site data for the hyperlink object
HRESULT hrStatus// Result of the hyperlink navigation
LPCWSTR pszStatus// Description of the failure, if any
);

Parameters

dwSiteData

[in] Identifies the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite .

hrStatus

[in] Result of the hyperlink navigation. Either S_OK for success or E_ABORT or E_FAIL for failure.

pszStatus

[in] Pointer to the string describing the failure that occurred.

Return Values

S_OK

The hyperlink site has been successfully notified.

See Also

HlinkOnNavigate , IHlinkBrowseContext::OnNavigateHlink , IHlinkFrame::OnNavigate

[TOC]

IHlinkTarget [Beta]

A hyperlink target implements the IHlinkTarget interface and gives out hyperlink references to its contents.

When to Implement

Implement this interface when you have an application that can be the target for a hyperlink. In other words, hyperlinks from other applications use this interface to determine how to find, display, and navigate to your target.

An existing OLE document application which supports OLE linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application may also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile.

When to Use

You do not normally call these methods directly. When an end user selects a hyperlink through an application's user interface, the implementation of IHlink::Navigate calls these methods to determine how to display, locate, and navigate to the target.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IHlinkTarget Methods Description
SetBrowseContextEstablishes the current browse context for this hyperlink target.
GetBrowseContextRetrieves the current browse context within which this hyperlink target is currently running.
NavigateIf the given location is not visible, navigates to and shows that position within the target.
GetMonikerReturns a moniker to the hyperlink target object.
GetFriendlyNameReturns a friendly name for the given hyperlink location within this target.

See Also

HlinkNavigate , HlinkSimpleNavigateToMoniker , HlinkSimpleNavigateToString , IHlink , IHlinkBrowseContext

[TOC]

IHlinkTarget::GetBrowseContext [Beta]

Retrieves the browse context in which this hyperlink target is currently running.

HRESULT IHlinkTarget::GetBrowseContext(
IHlinkBrowseContext ** pphlbc // Buffer to receive the current browse context's interface pointer
);

Parameters

pphlbc

[out] Pointer to the location to return the browse context object's interface pointer.

Return Values

S_OK

The browse context has been successfully retrieved.

E_NOTIMPL

The hyperlink target does not understand browse contexts.

See Also

HlinkCreateBrowseContext , IHlinkBrowseContext , IHlinkFrame::GetBrowseContext , IHlinkTarget::SetBrowseContext

[TOC]

IHlinkTarget::GetFriendlyName [Beta]

Retrieves a friendly name for the given hyperlink destination within this target.

HRESULT IHlinkTarget::GetFriendlyName(
LPCWSTR szLocation // Hyperlink location within this target
LPWSTR * pszFriendlyName // Buffer to receive the friendly name
);

Parameters

szLocation

[in, unique] String that indicates the position of the hyperlink destination within this hyperlink target.

pszFriendlyName

[out] Pointer to the buffer to return the friendly name. This string must be allocated using CoTaskMemAlloc. It is the caller's responsibility to free this string using CoTaskMemFree.

Return Values

S_OK

The friendly name string of the hyperlink destination with this target has been retrieved.

E_OUTOFMEMORY

Indicates there is insufficient memory to retrieve the friendly name.

See Also

IHlink::GetFriendlyName

[TOC]

IHlinkTarget::GetMoniker [Beta]

Returns a moniker to the hyperlink target object for the given hyperlink destination szLocation.

HRESULT IHlinkTarget::GetMoniker(
LPCWSTR szLocation // Hyperlink destination within this target
DWORD dwAssign// Whether or not to create a moniker if one not found
IMoniker ** ppmkLocation // Buffer to receive this moniker
);

Parameters

szLocation

[in, unique] Identifies the hyperlink destination within this target.

dwAssign

[in] A value from the OLEGETMONIKER enumeration. This is typically either OLEGETMONIKER_ONLYIFTHERE, indicating the function should not force a moniker to be created if one does not already exist, or OLEGETMONIKER_FORCEASSIGN, indicating that the function should create a moniker if one does not exist.

ppmkLocation

[out] Pointer to location to return the IMoniker interface pointer to the hyperlink target object for this szLocation.

Return Values

S_OK

The moniker to the hyperlink target object retrieved.

E_FAIL

A moniker does not exist for this hyperlink target and OLEGETMONIKER_ONLYIFTHERE was specified for dwAssign.

CreateFileMoniker, MkParseDisplayName, and other moniker creation API errors

See Also

HlinkSimpleNavigateToMoniker , IHlinkSite::GetMoniker , IHlink::GetMonikerReference

[TOC]

IHlinkTarget::Navigate [Beta]

If the given location is not visible, navigates to and shows the location position within the object/document.

HRESULT IHlinkTarget::Navigate(
DWORD grfHLNF // Value from the HLNF enumeration
LPCWSTR * szLocation // Location within the hyperlink target to navigate to
);

Parameters

grfHLNF

[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.

szLocation

[in] The string location portion of the hyperlink reference.

Return Values

S_OK

The navigation to the hyperlink target has been successful.

See Also

HlinkNavigate , HlinkNavigateToStringReference , HLNF , IHlinkFrame::Navigate , IHlink::Navigate

[TOC]

IHlinkTarget::SetBrowseContext [Beta]

Establishes the current browse context for this hyperlink target.

HRESULT IHlinkTarget::SetBrowseContext(
IHlinkBrowseContext * phlbc // Browse context interface pointer to set for the hyperlink target
);

Parameters

phlbc

[in, unique] Pointer to the browse context object's interface.

Return Values

S_OK

The browse context has been successfully set.

E_NOTIMPL

The hyperlink target does not understand browse contexts.

See Also

HlinkCreateBrowseContext , IHlinkBrowseContext , IHlinkFrame::SetBrowseContext , IHlinkTarget::GetBrowseContext

[TOC]

IHttpNegotiate [Beta]

The single method of IHttpNegotiate provides basic authentication information from a bind client.

When to Implement

Only custom protocol writers need to implement this interface.

When to Use

The method of this interface may be called when a URL bind encounters a generic HTTP problem during a URL download. To get a pointer to this interface, call IBindStatusCallback::QueryInterface.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IHttpNegotiate Methods Description
BeginningTransactionNotifies a client of a URL being bound to at the beginning of the HTTP transaction.
OnHeadersAvailableProvides the client with the HTTP response header information.
OnErrorAllows the client to add HTTP headers that are used to respond to the error.

[TOC]

IHttpNegotiate::BeginningTransaction [Beta]

Notifies a client of a URL being bound to at the beginning of the HTTP transaction.

HRESULT BeginningTransaction(
LPCWSTR szURL // The URL for the HTTP transaction.
DWORD dwReserved// Reserved for future use.
LPCWSTR szHeaders// The current request headers.
LPWSTR szAdditionalHeaders // Additional headers to append to the HTTP request header.
);

Parameter

szURL

[in]The URL being bound to.

pbc

The bind-context passed into the BindToStorage or BindToObject call. May not be NULL.

ppbinding

Location to return the IBinding interface of the transport. May not be NULL.

Return Values

S_OK

Success, append the headers.

S_FALSE

Do not append any headers.

E_INVALIDARG

The argument is invalid.

E_ABORT

Abort the HTTP transaction.

Remarks

IHttpNegotiate::BeginningTransaction is called by the URL Moniker before sending an HTTP request. It notifies the client of the URL being bound to at the beginning of the HTTP transaction. It also allows the client to add additional headers to the request.

See Also

IBinding

[TOC]

IHttpNegotiate::OnHeadersAvailable [Beta]

Provides the client with the HTTP response header information.

HRESULT OnHeadersAvailable(
DWORD dwResponseCode // HTTP response code.
LPCWSTR szHeaders// The bind-context passed into the BindTo... call
);

Parameter

dwResponseCode

[in] HTTP response code (see HTTP specification).

szHeaders

The response headers (a NULL-terminated string).

Return Values

S_OK

Success. Continue the HTTP transaction.

E_INVALIDARG

The argument is invalid.

E_ABORT

Abort the HTTP transaction.

Remarks

IHttpNegotiate::OnHeadersAvailable is called by the URL Moniker to provide the client with the HTTP response header information. The client may examine these headers and choose to abort the HTTP transaction.

See Also

[TOC]

IHttpNegotiate::OnError [Beta]

Allows the client to add HTTP headers that are used to respond to the error.

HRESULT CreateBinding(
DWORD dwResponseCode // HTTP response code
LPCWSTR szRequestHeaders // HTTP headers sent to the HTTP server.
LPCWSTR szResponseHeaders // Response headers from the HTTP server.
LPWSTR szAdditionalRequestHeaders // Headers to add to the request headers before resending
);

Parameter

szResponseHeaders

[in] Response headers from the HTTP server.

szAdditionalRequestHeaders

[in] Headers to add to the request headers before resending

Return Values

S_OK

Success, append the headers to the request.

S_FALSE

Do not append any headers.

E_INVALIDARG

The argument is invalid.

E_ABORT

Abort the HTTP transaction.

Remarks

IHttpNegotiate::OnError is called when an HTTP error occurs that cannot be resolved. The method allows the client to add HTTP headers that are used to respond to the error.

See Also

[TOC]

IInternetExplorer [Beta]

The IInternetExplorer interface TBD

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IDispatch Methods Description
GetIDsOfNamesReturns the number of type descriptions for object
GetTypeInfoRetrieves a description of objects programmable interface
GetTypeInfoCountMaps name of method or property to DISPID
InvokeCalls one of the object's methods, or gets/sets one of its properties

IInternetExplorer Methods Description
GoBack//Navigates to the previous item in history list
GoForward//Navigates to the next item in history list
GoHome//Navigates to the home/start page
GoSearch//Navigates to the search page
Open//Opens a file
Navigate//Navigates to a hyperlink
CloseTBD
Refresh//Refreshes the current file
Stop//Stops opening a file
PrintOut//Prints the current document
get_Application//Retrieves a pointer to this OC
get_Container//Retrieves a pointer to the container
get_Document//Retrieves the active document
get_FileName//Retrieves the file name
get_FullName//Retrieves the full path name
get_FullScreen//Retrieves whether or not this control is fullscreen
put_FullScreen//Sets whether or not this control is fullscreen
get_StatusBar//Retrieves the statusbar value
put_StatusBar//Sets the statusbar value
get_StatusText//Retrieves the text of the status window
put_StatusText//Sets the text of the status window
get_ToolBar//Retrieves whether the toolbar is on or off
put_ToolBar//Sets whether the toolbar is on or off
get_Name//Retrieves the name of the application
get_Parent//Retrieves a pointer to the parent object
get_TopLevelContainer//TBD
get_Type//Retrieves the type of the contained object
get_Visible//Retrieves whether or not this OC is visible
put_Visible//Sets whether or not this OC is visible
get_Left//Retrieves the horizontal dimension of the frame window relative to screen
put_Left//Sets the horizontal dimension of the frame window relative to screen
get_Top//Retrieves the vertical dimension of the frame window relative to screen
put_Top//Sets the vertical dimension of the frame window relative to screen
get_Width//Retrieves the horizontal dimension of the frame window
put_Width//Sets the horizontal dimension of the frame window
get_Height//Retrieves the vertical dimension of the frame window
put_Height//Sets the vertical dimension of the frame window
get_Busy//Retrieves whether or not something is still in progress

[TOC]

IInternetExplorer::Close [Beta]

TBD

HRESULT IInternetExplorer::Close(
TBD// TBD
);

Return Values

TBD

[TOC]

IInternetExplorer::get_Application [Beta]

Returns a pointer to this OC.

HRESULT IInternetExplorer::get_Application(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Busy [Beta]

Query to see if something is still in progress.

HRESULT IInternetExplorer::get_Busy(
boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Container [Beta]

Returns a pointer to the container.

HRESULT IInternetExplorer::get_Container(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Document [Beta]

Returns the active Document.

HRESULT IInternetExplorer::get_Document(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_FileName [Beta]

Returns the file name.

HRESULT IInternetExplorer::get_FileName(
BSTR * pbstrFileName // TBD
);

Parameters

pbstrFileName

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_FullName [Beta]

Returns the full path name.

HRESULT IInternetExplorer::get_FullName(
BSTR * pbstrFullName // TBD
);

Parameters

pbstrFullName

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_FullScreen [Beta]

Determines whether this control is full screen or not.

HRESULT IInternetExplorer::get_FullScreen(
boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Height [Beta]

The vertical dimension (pixels) of the frame window.

HRESULT IInternetExplorer::get_Height(
long * plHeight // TBD
);

Parameters

plHeight

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Left [Beta]

Returns the horizontal position (pixels) of the frame window relative to the screen.

HRESULT IInternetExplorer::get_Left(
long * pLeft // TBD
);

Parameters

pLeft

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Name [Beta]

Returns name of the application.

HRESULT IInternetExplorer::get_Name(
BSTR * pbstrName // TBD
);

Parameters

pbstrName

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Parent [Beta]

Returns a pointer to the parent Object.

HRESULT IInternetExplorer::get_Parent(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_StatusBar [Beta]

Returns the statusbar value.

HRESULT IInternetExplorer::get_StatusBar(
boolean * pbool // TBD
);

Parameters

pbool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_StatusText [Beta]

Returns the text of the status window.

HRESULT IInternetExplorer::get_StatusText(
BSTR * pbstr // TBD
);

Parameters

pbstr

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_ToolBar [Beta]

Returns whether the toolbar is on or off.

HRESULT IInternetExplorer::get_ToolBar(
boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Top [Beta]

Returns the vertical dimension (pixels) of the frame window relative to the screen.

HRESULT IInternetExplorer::get_Top(
long * plTop // TBD
);

Parameters

plTop

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_TopLevelContainer [Beta]

TBD

HRESULT IInternetExplorer::get_TopLevelContainer(
boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Type [Beta]

Returns the type of the contained object.

HRESULT IInternetExplorer::get_Type(
BSTR * pbstrType // TBD
);

Parameters

pbstrType

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Visible [Beta]

Returns whether this OC is visible or hidden.

HRESULT IInternetExplorer::get_Visible(
Boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::get_Width [Beta]

Returns the horizontal dimension (pixels) of the frame window.

HRESULT IInternetExplorer::get_Width(
long * plWidth // TBD
);

Parameters

plWidth

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::GoBack [Beta]

Navigates to the previous item in the history list.

HRESULT IInternetExplorer::GoBack(
);

Return Values

TBD

[TOC]

IInternetExplorer::GoForward [Beta]

Navigates to the next item in the history list.

HRESULT IInternetExplorer::GoForward(

);

Return Values

TBD

[TOC]

IInternetExplorer::GoHome [Beta]

Navigates to the home/start page.

HRESULT IInternetExplorer::GoHome(

);

Return Values

TBD

[TOC]

IInternetExplorer::GoSearch [Beta]

Navigates to the Search Page.

HRESULT IInternetExplorer::GoSearch(

);

Return Values

TBD

[TOC]

IInternetExplorer::Navigate [Beta]

Navigates to a hyperlink.

HRESULT IInternetExplorer::Navigate(
DHyperlink * Hlink // TBD
VARIANT * OpenInNewWindow // TBD
VARIANT * NoHistory// TBD
);

Parameters

Hlink

[in] TBD

OpenInNewWindow

[in] TBD

NoHistory

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::Open [Beta]

Opens a file.

HRESULT IInternetExplorer::Open(
BSTR Target // TBD
VARIANT * Location// TBD
VARIANT * NoHistory// TBD
);

Parameters

Target

[in] TBD

Location

[in] TBD

NoHistory

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::PrintOut [Beta]

Prints the current document.

HRESULT IInternetExplorer::PrintOut(
long What // TBD
VARIANT Numbering// TBD
VARIANT FirstPage// TBD
VARIANT Sections// TBD
VARIANT FileName// TBD
VARIANT PrinterName// TBD
VARIANT DriverName// TBD
VARIANT PortName// TBD
VARIANT NoPrinting// TBD
);

Parameters

What

[in] TBD

Numbering

[in] TBD

FirstPage

[in] TBD

Sections

[in] TBD

FileName

[in] TBD

PrinterName

[in] TBD

DriverName

[in] TBD

PortName

[in] TBD

NoPrinting

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_FullScreen [Beta]

Sets this control to be full screen or not.

HRESULT IInternetExplorer::put_FullScreen(
boolean bValue // TBD
);

Parameters

bValue

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Height [Beta]

Sets the vertical dimension (pixels) of the frame window.

HRESULT IInternetExplorer::put_Height(
long lHeight // TBD
);

Parameters

lHeight

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Left [Beta]

Sets the horizontal position (pixels) of the frame window relative to the screen.

HRESULT IInternetExplorer::put_Left(
long Left // TBD
);

Parameters

Left

[out] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Location [Beta]

Sets location in namespace to view.

HRESULT IInternetExplorer::put_Location(
BSTR bstrLocation // TBD
);

Parameters

bstrLocation

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_StatusBar [Beta]

Sets the status bar on or off.

HRESULT IInternetExplorer::put_StatusBar(
boolean bValue // TBD
);

Parameters

bValue

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_StatusText [Beta]

Sets the text of the status window.

HRESULT IInternetExplorer::put_StatusText(
BSTR bstr // TBD
);

Parameters

bstr

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_ToolBar [Beta]

Turns the toolbar on or off.

HRESULT IInternetExplorer::put_ToolBar(
boolean bValue // TBD
);

Parameters

bValue

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Top [Beta]

Sets the vertical dimension (pixels) of the frame window relative to the screen.

HRESULT IInternetExplorer::put_Top(
long lTop // TBD
);

Parameters

lTop

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Visible [Beta]

Sets whether this OC is visible or hidden.

HRESULT IInternetExplorer::put_Visible(
Boolean bValue // TBD
);

Parameters

bValue

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::put_Width [Beta]

Sets the horizontal dimension (pixels) of the frame window

HRESULT IInternetExplorer::put_Width(
long lWidth // TBD
);

Parameters

lWidth

[in] TBD

Return Values

TBD

[TOC]

IInternetExplorer::Refresh [Beta]

Refreshes the current file.

HRESULT IInternetExplorer::Refresh(
);

Return Values

TBD

[TOC]

IInternetExplorer::Stop [Beta]

Stops opening a file.

HRESULT IInternetExplorer::Stop(

);

Return Values

TBD

[TOC]

IMoniker - URL Moniker Implementation [Beta]

The URL moniker implementation of IMoniker is found on a URL moniker object, which also supports IUnknown, IMonikerAsync, IPersist, and IPersistStream. (IMonikerAsync is simply IUnknown (there are no actual methods), and is used to allow clients to determine transparently if a moniker supports asynchronous binding.) To get a pointer to the IMoniker interface on this object, call the CreateURLMoniker function.

When to Use

If you're a moniker client (that is, you're using a moniker to get an interface pointer to an object), you typically don't need to know the class of the moniker you're using; you simply call methods using an IMoniker interface pointer.

If you're a moniker provider (that is, you're handing out monikers that identify your objects to make them accessible to moniker clients), you must use item monikers if the objects you're identifying are contained within another object and can be individually identified using a string. You'll also need to use another type of moniker (for example, file monikers) in order to identify the container object.

To use item monikers, you must use the CreateItemMoniker API function to create the monikers. In order to allow your objects to be loaded when an item moniker is bound, the container of your objects must implement the IOleItemContainer interface.

The most common example of moniker providers are OLE applications that support linking. If your OLE application supports linking to objects smaller than a file-based documents, you need to use item monikers. For a server application that allows linking to a selection within a document, you use the item monikers to identify those objects. For a container application that allows linking to embedded objects, you use the item monikers to identify the embedded objects.

Remarks

IMoniker::BindToObject

Since the URL Moniker supports asynchronous binding, the actual return value of its BindToObject may vary depending on the object parameters established in the bind-context, however the semantics of the bind operation are identical regardless of synchronous or asynchronous usage, and are as follows:

1. URL Moniker first looks in the bind-context for SZ_ASYNC_CALLEE to determine if asynchronous options apply to its bind.

2. If they do, it pulls further information for the bind operation from the bind-context (for example, the IBindStatusCallback and IEnumFORMATETC interfaces).

3. It next checks the Running Object Table of the bind-context to determine if it is already running, with the following calls:

IBindCtx::GetRunningObjectTable(&prot)
prot->IsRunning(this)

If it is already running, it retrieves the running object with

prot->GetObject(this, &punk)

and calls QueryInterface for the requested interface.

4. Otherwise, it next initiates the binding with the transport's IBindProtocol and passes the resulting IBinding to the client via IBindStatusCallback::OnStartBinding .

5. If in step 1 it was determined that this was an asynchronous bind, BindToObject returns MK_S_ASYNCHRONOUS at this point with NULL in ppv. The caller will receive the actual object pointer during IBindStatusCallback::OnObjectAvailable at some later point. The following steps then occur asynchronously to the caller, typically on another thread of execution.

6. The class of the resource designated by the URL Moniker is next determined in one of the following ways:

· In the case of HTTP, the initial HTTP response packet header may contain the CLSID of the actual (Get) or referred to (Head) resource as an extension-header to the Entity Header section of the Full-Response message of the form:

CLSID = "CLSID" ": " stringized-clsid

where stringized-clsid can be created using StringFromCLSID and interpreted using CLSIDFromString. New HTTP servers can support this functionality readily.

· URL Moniker examines the media type of the data. If the media type is "application/x-oleobject" the first 16-bytes of the actual data (Content-Body) contain the CLSID of the resource and subsequent data is to be interpreted by the class itself. For all other media types, URL Moniker looks in the system registry for the HKEY_CLASSES_ROOT\MIME\Database\Content-Type\\CLSID key.

· URL Moniker matches portions of arriving data to patterns registered in the system registry under HKEY_CLASSES_ROOT\FileTypes.

· Finally, if all else fails, URL Moniker correlates the trailing extension of the resource, if any, to a CLSID using the HKEY_CLASSES_ROOT\.??? keys in the system registry, as is done by GetClassFile and the shell.

7. Having determined the class, URL moniker creates an instance using CoCreateInstance of CLSCTX_SERVER asking for the IUnknown interface. When the class code does not exist on the machine, URL Moniker may attempt to locate and download appropriate class code in a manner TBD.

8. URL Moniker next QueryInterfaces the newly created object for IPersistMoniker and if successful calls IPersistMoniker::Load passing itself (this) as the moniker parameter. The object typically turns around and calls IMoniker::BindToStorage asking for the storage interface that they're interested in.

9. Otherwise, URL Moniker QueryInterfaces for IPersistStream and if successful calls IPersistStream::Load, passing the object an IStream which is being filled asynchronously by the transport. If the class being called is not marked with the category CATID_AsyncAware, calls to IStream::Read or IStream::Write which reference data not yet available block until the data becomes available. If the class is marked with the category CATID_AsyncAware, calls to IStream::Read or IStream::Write which reference data not yet available return E_PENDING.

10. Otherwise, URL Moniker calls QueryInterface for IPersistStorage, and if successful calls IPersistStorage::Load, passing the object an IStorage which is being filled asynchronously by the transport. If the class being called is not marked with the category CATID_AsyncAware, calls to IStorage and underlying IStream interfaces that reference data not yet available block until the data becomes available. If the class is marked with the category CATID_AsyncAware, calls to IStorage and underlying IStream's which reference data not yet available return E_PENDING.

11. Otherwise, URL Moniker asks for QueryInterfaces for IPersistFile, and if successful completes the download into a temporary file and then calls IPersistFile::Load. URL Moniker creates the temporary file using the CreateFile API and specifying FILE_FLAG_DELETE_ON_CLOSE. It releases its handle (CloseHandle) to the temporary file upon return from IPersistFile::Load, so the one called must open a handle on the file during this call or the file will disappear. When the one called closes its last handle on the file, the file will automatically be deleted. See the Microsoft® Win32® documentation for further details about the behavior of FILE_FLAG_DELETE_ON_CLOSE.

12. Otherwise, URL Moniker calls QueryInterface for IPersistMemory, and, if successful, completes the download into a memory buffer and calls IPersistMemory::Load. It is the responsibility of the one called to free the memory when it is finished with it using CoTaskMemFree.

13. When the object returns from one of the various IPersistXXX::Load calls above, URL Moniker returns the client the interface pointer originally requested in IMoniker::BindToObject using the callback IBindStatusCallBack::OnObjectAvailable .

IMoniker::BindToStorage

The system implementation of URL Moniker supports BindToStorage for IStream on all URLs and for IStorage in the case where the designated resource is in fact a compound file.

Since the URL Moniker supports asynchronous binding, the actual return value of its BindToStorage may vary depending on the object parameters established in the bind-context, however the semantics of the bind operation are identical regardless of synchronous or asynchronous usage, and are as follows:

1. URL Moniker first looks in the bind-context for SZ_ASYNC_CALLEE to determine if asynchronous options apply to its bind.

2. If they do, it pulls further information for the bind operation from the bind context (for example, the IBindStatusCallback and the IEnumFORMATETC interfaces). The moniker then initiates the binding with the transport's IBindProtocol and passes the resulting IBinding to the client via IBindStatusCallback::OnStartBinding.

3. If the caller requested an asynchronous IStream or IStorage via the ABINDF_ASYNCSTORAGE flag in the BINDINFO retrieved from IBindStatusCallback::GetBindInfo , the URL moniker returns the object as soon as possible. Calls to these IStorage or IStream objects which reference data not yet available return E_PENDING.

4. If the caller does not specify asynchronous IStream or IStorage as described above, URL Moniker will still return an object through IBindStatusCallback::OnDataAvailable as soon as possible. However calls to these objects which reference data not yet available will block until the data becomes available. For some applications this will require the least modification of their existing I/O code, yet may still result in improved performance depending on their access-patterns.

IMoniker::Reduce

Returns MK_S_REDUCED_TO_SELF and itself (this) in ppmkReduced.

IMoniker::ComposeWith

URL Monikers only support generic composition. If fOnlyIfNotGeneric==TRUE, returns MK_E_NEEDGENERIC, otherwise this method simply returns CreateGenericComposite(this, pmkRight, ppmkComposite). May in the future properly compose two URL monikers. See the Win32 documentation about IMoniker::ComposeWith for details.

IMoniker::Enum

Returns S_OK and sets ppenumMoniker to NULL, indicating that the moniker does not contain sub-monikers.

IMoniker::IsEqual

Returns S_FALSE if the other moniker (pmkOtherMoniker) is not a URL moniker, which it checks using IPersist::GetClassID to see if the CLSID is CLSID_URLMoniker. If the other moniker is an URL moniker, it compares the display names of the monikers for equality, returning either S_OK if they are identical or S_FALSE if not.

IMoniker::Hash

Creates a hash value based on the URL string of the moniker. This hash value is identical when URL strings are identical, although it may also be identical for different URL strings. This method is used to speed up comparisons by reducing the amount of time that it is necessary to call IsEqual.

IMoniker::IsRunning

Returns S_OK if this moniker is currently "running", otherwise returns S_FALSE. URL Moniker determines if it is running by first checking if it is equal to the newly running moniker by calling the IMoniker::IsEqual method on pmkNewlyRunning, which is typically an inexpensive operation) and next by checking if it is registered with the Running Object Table of the passed-in bind-context.

IMoniker::GetTimeOfLastChange

Returns E_NOTIMPL.

IMoniker::Inverse

Returns MK_E_NOINVERSE.

IMoniker::CommonPrefixWith

Returns E_NOTIMPL

IMoniker::RelativePathTo

Returns E_NOTIMPL.

IMoniker::GetDisplayName

URL Moniker attempts to return its full URL string. If the moniker was created with a partial URL string (see CreateURLMoniker ), it will first attempt to find an URL moniker in the bind-context under SZ_URLCONTEXT, and will next look to the moniker to its left for contextual information. If it can not return its full URL string, it will return its partial URL string.

IMoniker::ParseDisplayName

Parses a full or partial URL string into a result moniker (ppmkOut). If szDisplayName represents a full URL string (i.e. "http://foo.com/default.html"), the result is a new full URL moniker. If szDisplayName represents a partial URL string (i.e. "..\default.html"), the result is a full URL that takes its context from either the bind-context's SZ_URLCONTEXT object-parameter or from this URL moniker (i.e., if the context moniker was "http://foo.com/pub/list.html" and szDisplayName was "..\default.html", the resulting URL moniker would represent "http://foo.com/default.html").

IMoniker::IsSystemMoniker

Returns S_FALSE and MKSYS_NONE in *pdwMksys. To determine if a moniker is a URL moniker, call IPersist::GetClassID and compare the result with CLSID_URLMoniker.

See Also

CreateURLMoniker, IMoniker, IOleItemContainer

[TOC]

IObjectWithSite [Beta]

Often an object needs to communicate directly with a container site, that is managing the object itself. Outside of IOleObject::SetClientSite, there is no generic means through which an object becomes aware of its site. IObjectWithSite provides simple objects with a lightweight means (lighter than IOleObject) with a siting mechanism. This interface should only be used when IOleObject is not already in use.

Through IObjectWithSite, a container can pass the IUnknown pointer of its site to the object through IObjectWithSite::SetSite. Callers can also retrieve the latest site passed to IObjectWithSite::SetSite through IObjectWithSite::GetSite. This latter method is included as a hooking mechanism, allowing a third party to intercept calls from the object to the site.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IObjectWithSite Methods Description
SetSiteProvides the site's IUnknown pointer to the object being managed.
GetSiteRetrieves the last site set with IObjectWithSite::SetSite.

[TOC]

IObjectWithSite::GetSite [Beta]

Retrieves the last site set with IObjectWithSite::SetSite . If there's no known site, the object return a failure code.

HRESULT GetSite(
REFIID riid, // IID of interface pointer being requested
void ** ppvSite// Receives an indirect pointer to caller's void
);

Parameters

riid

[in] The IID of the interface pointer that should be returned in ppvSite.

ppvSite

[out] The address of the caller's void * variable in which the object stores the interface pointer of the site last seen in IObjectWithSite::SetSite . The specific interface returned depends on the riid argument¾in essence, the two arguments act identically to those in IUnknown::QueryInterface. If the appropriate interface pointer is available, the object must call IUnknown::AddRef on that pointer before returning successfully. If no site is available, or the requested interface is not supported, the object sets this argument to NULL and returns a failure code.

Return Values

S_OK

The site was returned successfully and the caller is responsible for calling IUnknown::Release when the site is no longer needed.

E_FAIL

There is no site in which case *ppvSite contains NULL on return.

E_NOINTERFACE

There is a site but it does not support the interface requested by riid.

Remarks

E_NOTIMPL is not allowed¾any object implementing this interface must be able to return the last site seen in IObjectWithSite::SetSite .

[TOC]

IObjectWithSite::SetSite [Beta]

Provides the site's IUnknown pointer to the object. The object should hold onto this pointer, calling IUnknown::AddRef in doing so. If the object already has a site, it should call that existing site's IUnknown::Release, save the new site pointer, and call the new site's IUnknown::AddRef.

HRESULT SetSite(
IUnknown * pUnkSite // Pointer to IUnknown of the site managing this object
);

Parameter

pUnkSite

[in] The interface pointer of the site managing this object. If NULL, the object should call IUnknown::Release on any existing site at which point the object no longer knows its site.

Return Value

S_OK

Returned in all circumstances.

Remarks

E_NOTIMPL is not allowed¾without implementation of the SetSite method, the IObjectWithSite interface is unnecessary.

See Also

IObjectWithSite::GetSite

[TOC]

IOleCommandTarget [Beta]

The IOleCommandTarget interface defines a simple and extensible mechanism whereby objects and their containers can dispatch commands to each other. For example, an object's toolbars may contain buttons for commands such as Print, Print Preview, Save, New, and Zoom. 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 document objects. The IOleCommandTarget interface provides a simpler means to achieve the same ends.

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

Methods in VTable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces
AddRefIncrements reference count
ReleaseDecrements reference count

IOleCommandTarget Methods Description
QueryStatus Queries object for status of commands
Exec Execute a command

[TOC]

IOleCommandTarget::Exec [Beta]

Executes a specified command or displays help for a command.

HRESULT Exec(
const GUID *pguidCmdGroup // Pointer to command group
DWORD nCmdID// Identifier of command to execute
DWORD nCmdExecOpt// Options for executing the command
VARIANTARG *pvaIn// Input arguments
VARIANTARG *pvaOut// Pointer to output return values
);

Parameters

pguidCmdGroup

[unique][in] Unique identifier of the command group; can be NULL to specify the standard group. The command passed in nCmdID must belong to this group.

nCmdID

[in] The command to execute, which must be in the group specified with pguidCmdGroup.

nCmdExecOpt

[in] One or more values from the OLECMDEXECOPT enumeration describing how the object should execute the command.

pvaIn

[unique][in] Pointer to a VARIANTARG containing input arguments. Can be NULL.

pvaOut

[unique][in,out] Pointer to a VARIANTARG to receive the output return values. Can be NULL.

Return Values

S_OK

The command was executed successfully.

E_UNEXPECTED

An unexpected error occurred.

E_FAIL

An error occurred

OLECMDERR_E_UNKNOWNGROUP

pguidCmdGroup is non-NULL but does not specify a recognized command group.

OLECMDERR_E_NOTSUPPORTED

The nCmdID argument is not recognized as a valid command in the group identified with pguidCmdGroup.

OLECMDERR_DISABLED

The command identified with nCmdID is currently disabled and cannot be executed.

OLECMDERR_NOHELP

The caller has asked for help on the command identified by nCmdID but no help is available.

OLECMDERR_CANCELED

The user canceled the execution of the action.

Remarks

The list of in and out 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 Zoom command later in this section). 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 arguments together uniquely identify the command to invoke. The nCmdExecOpt parameter specifies the exact action to take (see the OLECMDEXECOPT enumeration for more details).

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

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 then the object can store that value directly in pvaOut. If the command has multiple output values then it will package those in some way appropriate for the VARIANTARG.

Because pvaIn and pvOut 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 OLE documentation in the Win32 SDK.

Notes to Implementers

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

See Also

OLECMDEXECOPT

[TOC]

IOleCommandTarget::QueryStatus [Beta]

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

[input_sync] HRESULT QueryStatus(
const GUID *pguidCmdGroup // Pointer to command group
ULONG cCmds// Number of commands in prgCmds array
OLECMD *prgCmds// Array of OLECMD structures
OLECMDTEXT *pCmdText// Pointer to structure containing name or status of command
);

Parameters

pguidCmdGroup

[unique][in] 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 pguidCmdGroup.

cCmds

[in] The number of commands in the prgCmds array.

prgCmds

[in,out][size_is(cCmds)] A caller-allocated array of OLECMD structures, where the object receiving the call fills the cmdID field of each command with bits taken from the OLECMDF enumeration, specifying the status of each command.

pCmdText

[unique][in,out] Pointer to the structure in which to return name and/or status information. Can be NULL to indicate that the caller is not interested in such information.

Return Values

S_OK

The command status as any optional strings were returned successfully.

E_POINTER

The prgCmds argument is NULL.

E_UNEXPECTED

An unexpected error occurred.

E_FAIL

An error occurred

OLECMDERR_E_UNKNOWNGROUP

The pguidCmdGroup parameter is non-NULL but does not specify a recognized command group.

Remarks

Callers use IOleCommandTarget::QueryStatus 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 describe the commands of interest from the group specified in pguidCmdGroup, where each structure's cmdID is set to a command identifier and the cmdf field is set to zero.

Notes to Implementers

The object receiving the call the fills the cmdf field for each command with bits 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 OLECMDTEXT structure. If the OLECMDFTEXF_NAME flag is specified, then the object should copy the localized name of the command (for example, "Open", "Copy", etc.) into the rgwz field of OLECMDTEXT, paying attention to the size specified by the cwBuf field in that same structure.

If the caller specifies OLECMDFTEXTF_STATUS, the object should copy a localized status string for the command into the rgwz field. 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 then 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(s), that it attempted to copy, via the cwActual field.

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

Because 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. Therefore, E_NOTIMPL is not a valid return value.

See Also

OLECMD , OLECMDF , OLECMDTEXT

[TOC]

IOleDocument [Beta]

The IOleDocument interface enables a document object to communicate to prospective containers its ability to create views of its data. This interface also enables a document object 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 a document object at the very least must implement this interface. If an application exposes more than one type of document object, each type must implement IOleDocument. A document's view frame provider, which

When to Use

A container of document objects calls the methods of this interface to ask a document object to create views of itself, enumerate the views it supports, or provide miscellaneous information about its capabilities.

Methods in VTable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IOleDocument Methods Description
CreateView Creates a new view object.
GetDocMiscStatus Returns status bits about the document object.
EnumViews Enumerates views supported by the document object.

See Also

IOleCommandTarget , IOleContinueCallback, IOleDocumentView , IOleDocumentSite , IPrint

[TOC]

IOleDocument::CreateView [Beta]

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

HRESULT CreateView(
IOleInPlaceSite * pIPSite // Pointer to container's view-site object
IStream * pstm// Pointer to a stream object
DWORD dwReserved// Reserved for future use
IOleDocumentView * ppView // Indirect pointer to the new document view object
);

Parameters

pIPSite

[in] Pointer to the view-site object to be associated with the new document view object. May be NULL, as when creating a new, uninitialized document object, in which case the caller must initialize the view with a subsequent call to IOleDocumentView::SetInPlaceSite .

pstm

[in] Pointer to a stream containing data from which the new document view object should initialize itself. Normally will be NULL when the specified view is for a new, uninitialized document object. If NULL, the document object initializes the new document view object with a default state.

dwReserved

[in] Reserved for future use. In the future this parameter could be used to specify the type of view that needs to be created. Currently there are no defined values for this argument.

ppView

[out] Indirect pointer to the new document view object. If CreateView succeeds, the caller is responsible for calling Release through this pointer when the view object is no longer needed.

Return Values

S_OK

The view was created successfully.

E_POINTER

The address in ppView is NULL.

E_OUTOFMEMORY

Out of memory.

E_UNEXPECTED

An unexpected error occurred.

E_FAIL

An unspecified error occurred.

Remarks

A document-object container's document site calls IOleDocumentView::CreateView to instruct a document object to create a new view of itself in the container's process, either from scratch or by using the contents of an existing stream.

Calling CreateView does not cause the new view to display itself. To do so, the view must wait for calls to either IOleDocumentView::Show or IOleDocumentView::UIActivate .

Notes to Callers

The call to CreateView normally occurs in the container's implementation of IOleDocumentSite::ActivateMe . If a document object passes an IOleDocumentView pointer in its call to ActivateMe, the container has no need to call CreateView and instead can call IOleDocumentView::SetInPlaceSite, followed by AddRef. If a document object returns a NULL view pointer in its call to ActivateMe, then the container calls CreateView to retrieve a view pointer.

The container has the option of passing a pointer to a stream containing data to be used to initialize the requested view. If the container passes a NULL stream pointer, then the document object will initialize the new view using its default settings.

Notes to Implementers

This method must be completely implemented for any document object. Therefore E_NOTIMPL is not an acceptable return value.

If pIPSite is non-NULL, then the document object should pass the pointer to the new view through IOleDocumentView::SetInPlaceSite . If pIPSite is NULL, the caller is responsible for making this same call. In addition, if pstm is non-NULL, then the object should initialize the view object by passing pstm to IOleDocumentView::ApplyViewState .

As with all new interface pointers, CreateView should call AddRef on the pointer in *ppView before returning. The caller is responsible for calling Release through this pointer when it is no longer needed.

See Also

IOleDocumentSite::ActivateMe , IOleDocumentView::ApplyViewState , IOleDocumentView::SetInPlaceSite , IOleDocumentView::Show , IOleDocumentView::UIActivate

[TOC]

IOleDocument::EnumViews [Beta]

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

HRESULT EnumViews(
IEnumOleDocumentViews ** ppEnum // On return, pointer to interface pointer to an enumerator
IOleDocumentView ** ppView // On return, pointer to interface pointer to a single view
);

Parameters

ppEnum

[out] Indirect pointer to the enumerator's IEnumOleDocumentViews interface.

ppView

[out] Indirect pointer to a single view object's IOleDocumentView interface.

Return Value

S_OK

If the object supports multiple views, then *ppEnum contains the enumerator pointer. Otherwise *ppEnum is NULL and *ppView contains the interface pointer to the single view.

E_POINTER

The address in ppEnum or ppView is invalid. The caller must pass pointers for both arguments.

E_OUTOFMEMORY

The enumerator could not be created because there is insufficient memory.

Comments

If a document object supports multiple views of its data, it must also implement IEnumOleDocumentViews and return that interface's pointer in the out-parameter * ppEnum. Using this pointer, the container can enumerate the views supported by the document object.

If the document object supports only a single view, IOleDocument::EnumViews returns that view's IOleDocumentView pointer in the out parameter *ppView.

Notes to Callers

Call this method to determine if a document object supports more than one view of its data. If it does, the caller can use the pointer returned in *ppEnum to specify which view to activate. When finished with the pointer, the caller must free it by calling Release.

Notes to Implementers

This method must be completely implemented on all document objects; E_NOTIMPL is not an acceptable return value. The way in which this method should be implemented depends on whether the document object in question supports multiple views or only a single view.

See Also

IEnumOleDocumentViews , IOleDocumentView

[TOC]

IOleDocument::GetDocMiscStatus [Beta]

Returns information about whether a document object supports behaviors specified in the DOCMISC enumerator. Values from this enumerator are also stored in the registry as the value of the "DocObject" key.

HRESULT GetDocMiscStatus(
DWORD *pdwStatus // Pointer to information about the document object
);

Parameters

pdwStatus

[out] On return, a pointer to the information on supported behaviors; may be NULL. Values written to this pointer are taken from the DOCMISC enumeration.

Return Values

S_OK

The status bits were returned successfully

E_POINTER

The address in pdwStatus is NULL.

Comments

This method provides a way for containers to ascertain whether a document object 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 a document object, containers can take whatever steps are necessary to support, or otherwise accommodate, the specified behaviors.

Notes to Implementers

This function must be completely implemented in any document object even if a zero is returned; therefore E_NOTIMPL is not an acceptable return value. Normally, the returned DOCMISC value should be hard-coded for performance.

See Also

DOCMISC

[TOC]

IOleDocumentSite [Beta]

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

For each document object to be hosted, a container must provide a corresponding document site, which is an OLE Documents client site that, in addition to implementing IOleClientSite and IAdviseSink, implements IOleDocumentSite . Each document site implements a separate document view site 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 and every client site that is to host a document object. In addition to this interface, a document site must also implement IOleClientSite, IOleInPlaceSite, and IAdviseSink. IContinueCallback is optional.

When to Use

A document object 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
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IOleDocumentSite Methods Description
ActivateMe Activates an OLE Document Object

[TOC]

IOleDocumentSite::ActivateMe [Beta]

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

HRESULT ActivateMe(
IOleDocumentView * pViewToActivate // Pointer to the view to be activated
);

Parameters

pViewToActivate

[in] Pointer to the document view to be used in activating the document object. Can be NULL, in which case the container should call IOleDocument::CreateView to obtain a document view pointer.

Return Value

S_OK

The container activated the view successfully.

E_OUTOFMEMORY

pViewToActivate is NULL and the container's call to IOleDocument::CreateView failed with E_OUTOFMEMORY.

E_FAIL

Another error occurred in either view creation or activation.

Remarks

When a container calls IOleObject::DoVerb to request a document to activate, a document object bypasses the usual in-place activation sequence by calling IOleDocumentSite::ActivateMe.

When calling IOleObject::DoVerb on a document object, containers will usually find OLEIVERB_SHOW to be the most appropriate activation verb. Other allowable verbs include OLEIVERB_PRIMARY and OLEIVERB_UIACTIVATE. OLEIVERB_OPEN is discouraged because it implies opening an embedded object in a separate window, which is contrary to the intent of document object activation.

Notes to Callers

Only OLE document objects should call this method. A normal in-place active OLE document should respond to a container's call to IOleObject::DoVerb by calling IOleInPlaceSite.

A document object should initiate its activation by calling IOleDocumentSite::ActivateMe. If the container does not implement IOleDocumentSite, then the document should default to the normal in-place activation sequence.

A document object that supports more than one view of its data can specify which view to activate by passing a pointer to that view's IOleDocumentView interface in pViewToActivate.

However the IOleDocumentView pointer is obtained, the container should release the pointer when it is no longer needed.

Notes to Implementers

This function must be completely implemented in a document object container; E_NOTIMPL is not an acceptable return value.

If a document object passes an IOleDocumentView pointer in pViewToActivate, the container's implementation of ActivateMe should call IOleDocumentView::SetInPlaceSite and pass a pointer to its IOleInPlaceSite interface back to the document. If the container is holding onto the IOleDocumentView pointer, which will normally be the case, it should follow the call to SetInPlaceSite with a call to AddRef.

If a document object sets the value of pViewToActivate to NULL, the container can obtain a pointer to a document view by querying the document for IOleDocument, then calling IOleDocument::CreateView and passing its IOleInPlaceSite pointer.

See Also

IOleClientSite, IOleDocument::CreateView , IOleDocumentView::SetInPlaceSite , IOleInPlaceSite, IOleObject::DoVerb

[TOC]

IOleDocumentView [Beta]

The IOleDocumentView interface enables a container to communicate with each view supported by a document object. A document object that supports multiple views of its data represents each view as a separate object. Each document view object implements IOleDocumentView, along with IOleInPlaceObject, IOleInPlaceActiveObject, and optional interfaces such as IPrint and IOleCommandTarget. A document object 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.

The IOleDocumentView interface provides all the necessary methods for a container to manipulate, manage, and activate a document view object.

The SetInPlaceSite method enables a container to hand a document object an IOleInPlaceSite pointer to its view site in the container. The method GetInPlaceSite enables a container to retrieve a document object's IOleInPlaceSite pointer.

The GetDocument method provides a container with access to the IUnknown pointer of the document object containing the view object to which the call is made.

The SetRect and GetRect methods manage the simple rectangle that a view will occupy in the container. SetRectComplex enables a container to specify not only the simple rectangle but also the spaces that should be occupied by the view's scrollbars and size box.

The Show, UIActivate, and Open methods enable a container to manipulate a document view object's visual state. Show instructs a document view object to activate or deactivate itself in-place. When a view object is active, UIActivate instructs it to activate or deactivate its user interface elements, such as menus, toolbars, and accelerators. IOleDocumentView::Show provides document objects with the same functionality that the IOleInPlaceObject methods InPlaceActivate and InPlaceDeactivate provide to normal in-place-active objects; IOleDocumentView::UIActivate, the same functionality as UIActivate and UIDeactivate.

The Open method activates a document object in a separate window, as is the case with an embedded OLE Document that does not support in-place activation.

The Close method instructs a document view object to deactivate itself and release its document view site pointer. If the view is active in a separate window, the document view object should also close that window

The SaveViewState method enables a container to save a view's internal state to a stream. The ApplyViewState method enables a container to reload a previously saved view state.

The Clone method enables a container to create a duplicate of the current view object.

When to Implement

All document objects must implement IOleDocumentView for each and every view they support. If a document object supports multiple views, each view must be implemented as a separate class object. If a document object supports only a single view, the document object 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
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IOleDocumentView Methods Description
SetInPlaceSite Associates a container site with this view.
GetInPlaceSite Retrieves the last site passed in SetInPlaceSite.
GetDocument Returns the IUnknown pointer of the document object that owns this view.
SetRect Sets the coordinates of the view port.
GetRect Retrieves the coordinates last passed in SetRect
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 view in a separate pop-up window
Close Instructs view to close
SaveViewState Saves view state into stream
ApplyViewState Initializes view with view state previously saved in call to SaveViewState.
Clone Creates a duplicate view object.

See Also

[TOC]

IOleDocumentView::ApplyViewState [Beta]

Instructs a view to reinitialize itself according to the data in a stream that was previously written by means of a call to IOleDocumentView::SaveViewState .

HRESULT ApplyViewState(
IStream *pstm // Pointer to stream
);

Parameters

pstm

[in] Pointer to the stream from which the view should load its state.

Return Values

S_OK

The view successfully loaded its state from the specified stream.

E_POINTER

The value in pstm is NULL.

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.

Comments

Typically, this function 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 view-state stream data.

The semantics of ApplyViewState are encompassed in the pstm argument of IOleDocument::CreateView .

See Also

IOleDocument::CreateView , IOleDocumentView_SaveViewState

[TOC]

IOleDocumentView::Clone [Beta]

Creates a duplicate view object with an identical internal state to the current view.

HRESULT Clone(
IOleInPlaceSite *pIPSiteNew // Pointer to view site
IOleDocumentView **ppViewNew // On return, pointer to interface pointer to view object
);

Parameters

pIPSiteNew

[in] Pointer to the in-place site in which the view to be cloned will be activated. The view being cloned should pass this pointer to the cloned view's IOleDocumentView::SetInPlaceSite method. This pointer can be NULL, in which case the caller is responsible for calling SetInPlaceSite on this new view directly.ppViewNew

[out] Indirect pointer to the new view object's IOleDocumentView interface. The caller is responsible for this pointer any must release it when it is no longer needed.

Return Values

S_OK

The view was successfully cloned.

E_POINTER

The value in ppViewNew is NULL.]

E_NOTIMPL

The view object does not implement this interface.

E_FAIL

The document object does not implement this interface.

This is useful for creating a new view with a different view port and view site but with the same view context as the view being cloned. Typically this will be used to implement the "Window-New window" functionality.

Comments

This method is useful for creating a new view with a different view port and view site but with the same view context as the view being cloned. Typically, containers hosting an MDI application will call this method to provide "Window/New window" capability.

See Also

IOleDocumentView , IOleDocumentView::SetInPlaceSite

[TOC]

IOleDocumentView::Close [Beta]

Asks a document view to close and release its IOleInPlaceSite pointer.

HRESULT Close(
DWORD dwReserved // Reserved. Must be zero
);

Return Values

S_OK

The view successfully closed itself.

Comments

The container must call this method before it wants to delete the view (that is, release its last reference to the view). In general, implementaion of this method will call IOleDocumentView::Show (FALSE) to hide the view if it is not already, then call IOleDocumentView::SetInPlaceSite (NULL) to deactivate itself and release the view site pointer.

Because Close is called when a container is going to completely shut down a view, this method must be implemented and has no reason to fail.

See Also

IOleDocumentView::Show , IOleDocumentView::SetInPlaceSite

[TOC]

IOleDocumentView::GetDocument [Beta]

Returns the IUnknown interface pointer of the document object that owns this view.

HRESULT GetDocument(
IUnknown **ppunk // On return, pointer to the IUnknown pointer of the document object that owns this view
);

Parameters

ppunk

[out] Pointer to the IUnknown pointer of the document object.

Return Value

S_OK

The document object's interface pointer was successfully returned. This is the only valid return value for this function.

The caller is responsible incrementing the reference count on the interface pointer returned by this method. The caller must call Release through this pointer when it is no longer needed.

Because a document owning the view must always exist, this method will always succeed. Before returning, this method should call AddRef on the pointer stored in *ppunk.

See Also

IUnknown

[TOC]

IOleDocumentView::GetInPlaceSite [Beta]

Retrieves the most recent view site associated with this view of the document.

HRESULT GetInPlaceSite(
IOleInPlaceSite **ppIPSite // On return, Indirect pointer to the document's view site
);

Parameters

ppIPSite

[out] Pointer to the view site's IOleInPlaceSite interface pointer.

Return Value

S_OK

The interface pointer was returned successfully.

E_FAIL

Another error occurred.

Returns the most recent IOleInPlaceSite pointer passed in IOleDocumentView::SetInPlaceSite , or NULL if SetInPlaceSite has not yet been called. The view will call AddRef on this pointer before returning it, thus the caller must later call Release.

Notes to Callers

The caller is responsible incrementing the reference count on the interface pointer returned by this method. The caller must call Release through this pointer when it is no longer needed.

Notes to Implementers

A document view must implement this method completely. Therefore E_NOTIMPL is not an acceptable return value.

See Also

IOleDocumentView::SetInPlaceSite , IOleInPlaceSite

[TOC]

IOleDocumentView::GetRect [Beta]

Returns the rectangular coordinates of the view port in which the view is to be activated.

HRESULT GetRect(
LPRECT prcView // Pointer to the current view coordinates
);

Parameters

prcView

[out] Pointer to a RECT structure to which the document view object will write the coordinates of its current view port.

Return Value

S_OK

The view was successfully resized to the rectangle.

E_UNEXPECTED

This view has not yet seen a call to IOleDocumentView::SetRect or IOleDocumentView::SetRectComplex and therefore has no rectangle to return.

Remarks

For an SDI application, the view port is the client area of the frame window minus the space allocated for tool bars, status bar, and such. For an MDI window, the view port is the client area of the MDI document window minus any other frame-level user-interface elements.

The view port coordinates returned by this method are those set in the last previous call to either IOleDocumentView::SetRect or IOleDocumentView::SetRectComplex.

A document view must implement this method completely. Therefore E_NOTIMPL is not an acceptable return value.

See Also

IOleDocumentView::SetRect , IOleDocumentView::SetRectComplex

[TOC]

IOleDocumentView::Open [Beta]

Asks a document view to display itself in a separate pop-up window with semantics equivalent to IOleObject::DoVerb(OLEIVERB_OPEN).

HRESULT Open();

Return Values

S_OK

The view successfully created its separate window.

E_OUTOFMEMORY

There was not enough memory to activate the view in a separate window.

E_FAIL

Some other error occurred that prevented success.

E_NOTIMPL

The document object that owns this view does not support separate window activation.

E_UNEXPECTED

This method was called before a call to IOleDocumentView::SetInPlaceSite .

Remarks

A user viewing a document object in a container application such as a browser or "binder" may want to see two or more views or documents at once. Because the browser displays only one view at a time, the container needs a way to instruct the other views or documents to display themselves, as required, in separate windows. The IOleDocumentView::Open interface provides that way.

Notes to Callers

A successful call to IOleDocumentView::Open should be followed by a call to IOleDocumentView::Show (FALSE) to hide the window or IOleDocumentView::Show(TRUE) to show the window and bring it to the foreground. While the view is active in its separate window, a container can show or hide the window as many times as it may require.

Notes to Implementers

A document object that does not support activation in a separate window indicates as much by setting DOCMISC_CANTOPENEDIT in its DOCMISC enumeration and returning E_NOTIMPL to containers that nevertheless call this method in an attempt to open it. Objects that have a limited interface for activation purposes should be sure to set DOCMISC_CANTOPENEDIT.

Otherwise, implementation generally consists of calling the view's own interface, in response to which the view shows its separate pop-up window and brings that window to the foreground.

When the separate window is no longer needed, the container calls IOleDocumentView::Close , whereupon the view releases its site pointer to the separate window and destroys the window. Contrary to the normal in-place deactivation sequence for OLE Documents, however, a document view continues to hold the IOleInPlaceSite, pointer that it obtained from the container's call to IOleDocumentView::SetInPlaceSite. This pointer is only released when the view's container calls IOleDocumentView::SetInPlaceSite and sets pIPSite to NULL or calls IOleDocumentView::CloseView.

When a user closes a view's separate window, the view should not shut itself down. Instead, it should call IOleInPlaceSite::OnInPlaceActivate. The view site then decides whether to call IOleDocumentView::UIActivate (FALSE) immediately or later. In this way, a document view displayed in a separate window remains available for activation in the container's own window.

See Also

IOleDocumentView::Close , IOleDocumentView::Show , IOleDocumentView::UIActivate , IOleInPlaceObject::InPlaceDeactivate, IOleInPlaceSite, IOleInPlaceSite::OnInPlaceActivate

[TOC]

IOleDocumentView::SaveViewState [Beta]

Saves the view's state into the specified stream.

HRESULT SaveViewState(
IStream *pstm // Pointer to stream
);

Parameters

pstm

[in] Pointer to stream in which the view is to save its state.

Return Values

S_OK

The view successfully saved its state to the specified stream.

E_POINTER

The value in pstm is NULL.

E_NOTIMPL

This view has no meaningful state to save. This error should be rare because most views have at least some state information worth saving.

Comments

The view's state includes properties such as the view type, zoom factor, and insertion point. The container typically calls this function before deactivating the view. The stream can then later be used to reinitialize a view of the same document to this saved state through IOleDocumentView_ApplyViewState .

According to the rules governing IPersistStream, a view must write its CLSID as the first element in the stream. Any cross-platform file format compatibility issues that apply to the document's storage representation also apply to this context.

See Also

IOleDocumentView_ApplyViewState , IPersistStream

[TOC]

IOleDocumentView::SetInPlaceSite [Beta]

Associates a container's document view site with a document's document view object.

HRESULT SetInPlaceSite(
IOleInPlaceSite * pIPSite // Pointer to document view site's IOleInPlaceSite interface
);

Parameters

pIPSite

[in] Pointer to the document view site's IOleInPlaceSite interface. Can be NULL, in which case the document view object loses all asociation with the container.

Return Value

S_OK

A document view site was successfully associated (or disassociated if pIPSite is NULL) with a document view object.

E_FAIL

An unspecified error occurred.

Comments

As part of activating a document object, a container must hand the object a pointer to the container's implementation of IOleInPlaceSite. This pointer designates the document view site that is to be associated with the particular view of the document to be activated.

A container normally passes this pointer in response to a document's request to be activated. A document makes such a request by calling IOleDocumentSite::ActivateMe and handing the container a pointer to the view to be activated. The container, in turn, uses this pointer to call IOleDocumentView::SetInPlaceSite.

Notes to Callers

If the container is requesting creation and activation of a new instance of a document object, rather than merely the activation of a loaded instance of a document object, the semantics of SetInPlaceSite are encompassed in the pIPSite argument of IOleDocument::CreateView . Therefore, an explicit call to SetInPlaceSite is unnecessary.

Notes to Implementers

If this method is called on a view that already has an associated view site, the view must do some housekeeping in preparation for activating itself in the new site. First, the view must deactivate itself in the current site. Second, the view must release its pointer to that site. Third, if the new IOleInPlaceSite pointer is not NULL, the view should both save the pointer and call AddRef on it. Having completed these steps, the view should then wait for the container to tell it when to activate itself in the new view site.

A document view must implement this method completely. Therefore E_NOTIMPL is not an acceptable return value.

See Also

IOleDocumentView::GetInPlaceSite

[TOC]

IOleDocumentView::SetRect [Beta]

Sets the rectangular coordinates of the view port in which a view is to be activated.

[input_sync] HRESULT SetRect(
LPRECT prcView // Pointer to a RECT structure
);

Parameters

prcView

[in] Pointer to a RECT structure containing the coordinates of the view port.

Return Value

S_OK

The view was successfully resized.

E_FAIL

Some other critical error occurred that prevented the view from being resized.

Comments

For an SDI application, the view port is the client area of the frame window minus the space allocated for tool bars, status bar, and such. For an MDI window, the view port is the client area of the MDI document window minus any other frame-level user-interface elements.

Notes to Callers

Calling IOleDocumentView::SetRect (or SetRectComplex ) is part of the normal activation sequece for document objects, usually following a call to IOleDocumentView::UIActivate and preceding a call to IOleDocumentView::Show . In addition, whenever the window used to display a document object is resized, the container should call SetRect (or SetRectComplex) to tell the document object to resize itself to fit the new window dimensions.

Notes to Implementers

The coordinates of the view port are within the coordinates of the view window, which is obtained through IOleInPlaceSite::GetWindow. The view must resize itself to fit the new coordinates.

This method is defined with the [input_sync] attribute, which means that the implementing object cannot yield or make another, non input_sync RPC call while executing this method.

A document view must implement this method completely. Therefore E_NOTIMPL is not an acceptable return value.

See Also

IOleInPlaceSite::GetWindow

[TOC]

IOleDocumentView::SetRectComplex [Beta]

Sets the rectangular coordinates of the view port, horizontal and vertical scroll bars, and the size box.

[input_sync] HRESULT SetRectComplex(
LPRECT prcView // Pointer to coordinates of view port
LPRECT prcHScroll// Pointer to coordinates of horizontal scroll bar
LPRECT prcVScroll// Pointer to coordinates of vertical scroll bar
LPRECT prcSizeBox// Pointer to coordinates of size box
);

Parameters

prcView

[in] Pointer to a RECT structure containing the coordinates of the view port.

prcHScroll

[in] Pointer to a RECT structure containing the coordinates of the horizontal scroll bar.

prcVScroll

[in] Pointer to a RECT structure containing the coordinates of the vertical scroll bar.

prcSizeBox

[in] Pointer to a RECT structure containing the coordinates of the size box.

Return Value

S_OK

The view was successfully resized to the rectangle.

E_NOTIMPL

The document object that owns this view does not support complex rectangles.

E_FAIL

Some other critical error occurred that prevented resizing the view or placing the scrollbars and size box.

Remarks

View frames that support a workbook metaphor, in which a single document comprises multiple sheets or pages, typically call this method to set the coordinates to be used in common by all the sheets or pages.

Notes to Callers

Calling IOleDocumentView::SetRectComplex is part of the normal activation sequece for document objects that support complex rectangles, usually following a call to IOleDocumentView::UIActivate and preceding a call to IOleDocumentView::Show . In addition, whenever the window used to display a document object is resized, the container should call SetRectComplex (or IOleDocumentView::SetRect ) to tell the document object to resize itself to fit the new window dimensions.

Notes to Implementers

Document objects that support complex rectangles mark themselves with DOCMISC_SUPPORTCOMPLEXRECTANGLES, as described in DOCMISC and IOleDocument::GetDocMiscStatus . Document objects that do not support this method can return E_NOTIMPL.

Upon receiving a call to this method, a view should resize itself to fit the coordinates specified in prcView and fit its scrollbars and size box to the areas described in prcHScroll, prcVScroll, and prcSizeBox.

This method is defined with the [input_sync] attribute, which means that the implementing object cannot yield or make another, non input_sync RPC call while executing this method.

See Also

DOCMISC , IOleDocument::GetDocMiscStatus

[TOC]

IOleDocumentView::Show [Beta]

Instructs a view to in-place activate or in-place deactivate itself.

HRESULT Show(
BOOL fShow // Boolean value specifying whether to activate or deactivate the view
);

Parameters

fShow

[in] TRUE instructs the view to show itself; FALSE instructs the view to hide itself.

Return Value

S_OK

The view was successfully shown or hidden.

E_OUTOFMEMORY

There was not enough memory to activate or hide the view.

E_FAIL

Some other critical error occurred that prevented activation or hiding.

E_UNEXPECTED

This method was called before a call to IOleDocumentView::SetInPlaceSite .

Comments

Calling IOleDocumentView::Show is the last step in the activation sequence because before showing itself a document object must know exactly what space it occupies and have all its tools available.

Notes to Callers

A call to this method for the purpose of activating a view should follow calls to IOleDocumentView::SetInPlaceSite, IOleDocumentView::UIActivate , and IOleDocumentView::SetRect (or SetRectComplex ).

Notes to Implementers

Implementations of this method should embody the following pseudo-code:

if (fShow)
{
In-place activate the view but do not UI activate it.
Show the view window.
}
else
{
Call IOleDocumentView::UIActivate(FALSE) on this view
Hide the view window
}

All views of a document object must at least support the in-place activation mode, therefore E_NOTIMPL is not allowed as a return value.

See Also

IOleDocumentView::SetInPlaceSite , IOleDocumentView::UIActivate , IOleDocumentView::SetRect , IOleDocumentView::SetRectComplex

[TOC]

IOleDocumentView::UIActivate [Beta]

Activates or deactivates a document view's user-interface elements, such as menus, toolbars, and accelerators.

HRESULT UIActivate(
BOOL fUIActivate // Boolean value specifying whether to activate or deactivate view
);

Parameters

fUIActivate

[in] TRUE instructs the view to activate its user interface; FALSE instructs the view to deactivate its user interface.

Return Value

S_OK

The view's user interface was successfully activated or deactivated.

E_OUTOFMEMORY

There was not enough memory to activate the view's user interface.

E_FAIL

Some other critical error occurred that prevented activation or deactivation of the user interface.

E_UNEXPECTED

This method was called before a call to IOleDocumentView::SetInPlaceSite .

Comments

Calling this method is part of the normal activation and deactivation sequences of a document object.

Notes to Callers

Calling this method before calling IOleDocumentView::SetInPlaceSite returns an error because the view must know where it is activating itself before it can proceed to do so. When calling IOleDocumentView::UIActivate as part of the activation sequence, the call should precede one to IOleDocumentView::SetRect (or SetRectComplex ) because otherwise the container would send to the view dimensions that would be incorrect because they would not account for toolbar space.

When deactivating a view, the container should call IOleDocumentView::Show (FALSE), followed by IOleDocumentView::UIActivate (FALSE).

Notes to Implementers

Implementations of this method should embody the following pseudo-code:

if (fActivate)

{

UI activate the view (do menu merging, show frame level tools, process accelerators)

Take focus, and bring the view window forward.

}

else

call IOleInPlaceObject::UIDeactivate on this view

In addition, the view may, and should, participate in extended Help menu merging.

All views of a document object must at least support the in-place activation mode. Therefore, E_NOTIMPL is not allowed as a return value.

See Also

IOleDocumentView::SetInPlaceSite , IOleDocumentView::SetRect , IOleDocumentView::SetRectComplex , IOleDocumentView::Show , IOleInPlaceObject::UIDeactivate

[TOC]

IOleScript [Beta]

The scripting engine must implement this interface in order to be an OLE Scripting engine.

[TOC]

IOleScript::AddNamedItem [Beta]

Adds a root-level name (an object with properties/methods, an event source, or both) to the scripting engine's name space.

HRESULT IOleScript::AddNamedItem(
LPCOLESTR pstrName, // Item name as viewed from script
DWORD dwFlags// Item flags
);

Parameters

pstrName

[in] Name of the item as viewed from the script. Must be unique and persistable.

dwFlags

Flags associated with item. The following flags are defined:

SCRIPTIEM_ISPERSITENT

Indicates that the item is to become part of the scripting engine's persistent state. Provided the scripting engine's state is saved after the item is added, it will not be necessary to add the item again the next time the script is loaded. Since only authoring environments allow a dirty script state to be saved, this flag is really only usefully set in an authoring situation. Items added in this way by an authoring tool, however, will be present and useable when the script is later loaded by a non-authoring host.

SCRIPTIEM_ISSOURCE

Indicates that the item sources events that the script can sink. Children (properties of the object which are in themselves objects) can also source events to the script. This is not recursive, but provides a convenient mechanism for the common case, for example, of adding a container and all of its member controls.

SCRIPTIEM_ISVISIBLE

Indicates that the item's name is available in the namespace of the script, allowing access to the properties, methods, and events of the item. Since, by convention, the properties of the item include the item's children, all child object properties and methods (and their children, recursively), will be accessible.

SCRIPTIEM_ISSCRIPTBASE

Indicates that the item is the base object associated with the script. For the HTML browser, for example, this flag would be associated with the page object in which the script is running. Scripting engines which implement name scoping within their programming model can use this flag to identify object scope relative to the running script. This flag should be set for only one item in the namespace; adding another item with this flag set overrides any previous item.

SCRIPTIEM_GLOBALMEMBERS

Indicates that the item is a collection of global properties and methods associated with the script. Normally, a scripting engine would ignore the object name (other than for the purpose of using it as a cookie for IOleScriptSite:: GetItemInfo , or for resolving explicit scoping), and expose its members as global variables and methods. This allows the host to extend the library of runtime functions, etc. available to the script. It is left up to the scripting engine how to deal with name conflicts (e.g. when two SCRIPTITEM_GLOBALMEMBERS items have methods of the same name), although an error should not be returned because of this situation.

Return Values

S_OK

Success, named item has been added to the script's namespace.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

TBD

See Also

IOleScriptSite:: GetItemInfo

[TOC]

IOleScript::AddTypeLib [Beta]

Adds a type library to the namespace for the script.

HRESULT IOleScript::AddTypeLib(
REFGUID rguidTypeLib, // Type library GUID
DWORD dwMajor,// Major version number
DWORD dwMinor,// Minor version number
DWORD dwFlags// Option flags
);

Parameters

rguidTypeLib

[in] GUID of the Type library to add.

dwMajor

[in] Major version number.

dwMinor

[in] Minor version number.

dwFlags

[in] Option flags:

SCRIPTTYPELIB_ISPERSITENT

Indicates that the type library is to become part of the scripting engine's persistent state. Provided the script is saved after the item is added, it will not be necessary to add the type library again the next time the script is loaded. Since only authoring environments allow a dirty script state to be saved, this flag is really only usefully set in an authoring situation. The contents of type libraries added in this way by an authoring tool, however, will be present and useable when the script is later loaded by a non-authoring host.

SCRIPTTYPELIB_ISCONTROL

Indicates that the type library describes an OLE Control used by the host.

Return Values

S_OK

Success, the specified type library has been added.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

TYPE_E_CANTLOADLIBRARY

The specified type library could not be loaded.

E_INVALIDARG

An invalid argument was passed.

Remarks

This is similar to #include in C/C++. It allows a set of predefined class definitions, typedefs, named constants, etc., to be added to the runtime environment available to the script. As an optimization, this method is called by the host once for each relevant type library, only if IOleScriptSite::RequestTypeLibs is called. For some scripting engines (such as compilers), this may be an expensive operation, requiring the compilation of the script.

See Also

IOleScriptSite::RequestTypeLibs

[TOC]

IOleScript::Clone [Beta]

Clones the current scripting engine, minus any current execution state, returning a loaded, but un-sited scripting engine in the current thread.

HRESULT IOleScript::Clone(
IOleScript **ppscript // Returned, unsited cloned scripting engine
);

Parameters

ppscript

[out] The returned, unsited, cloned scripting engine. The host must create a site and call SetScriptSite on the new scripting engine before it will be usable.

Return Values

S_OK

Success.

E_NOTIMPL

Method not supported.

E_POINTER

An invalid pointer was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Named items will be duplicated in the cloned scripting engine, but specific object pointers for each item will be forgotten and will be obtained with GetItemInfo. This allows an identical object model, but per-thread entry points (apartment model) to be used. This method is used for multi-threaded server hosts which may run multiple instances of the same script. The scripting engine may return E_NOTIMPL, in which case the host can achieve the same result by duplicating the persistent state and creating a new instance of the scripting engine with IPersist. This method may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite .

See Also

IOleScript::SetScriptSite , IPersist, IOleScriptSite::GetItemInfo

[TOC]

IOleScript::Close [Beta]

Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a zombied state.

HRESULT IOleScript::Close();

Return Values

S_OK

Success, the script has been zombied.

S_FALSE

Success, but the script was already zombied.

OLESCRIPT_S_PENDING

The function was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IOleScriptSite::OnStateChange .

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Event sinks, immediately executed script text, and macro invocations that are already in progress are completed before the state changes (use InterruptScriptThread to cancel a running script thread). This method must be called by the creating host before it calls Release, to prevent circular reference problems.

See Also

IOleScriptSite::OnStateChange , Release

[TOC]

IOleScript::Disconnect [Beta]

Moves the scripting engine from the connected or loaded state to the disconnected state.

HRESULT IOleScript::Disconnect();

Return Values

S_OK

Success, the script has been suspended.

S_FALSE

Success, but the script was already suspended.

OLESCRIPT_S_PENDING

The function was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IOleScriptSite::OnStateChange .

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Event sinks that are in progress are completed before the state changes (use InterruptScriptThread to cancel a running script thread). The script's execution state is maintained, but it is logically disconnected from sinking events in the host's object model. Whether the scripting engine actually choose to UnAdvise the connection points or not is up to the scripting engine. Those that do UnAdvise simply ignore the event. Disconnect might be called by the host when the associated document becomes inactive. For example, an HTML browser may call this method when a scripted HTML page is moved into the LRU cache, before the page is actually destroyed.

See Also

IOleScript::InterruptScriptThread , IOleScriptSite::OnStateChange , UnAdvise

[TOC]

IOleScript::GetCurrentScriptThreadID [Beta]

Returns a scripting engine defined identifier for the currently executing thread. This identifier can then be used in subsequent calls to script thread execution control methods such as InterruptScriptThread , etc.

HRESULT IOleScript::GetCurrentScriptThreadID(
SCRIPTTHREADID *pstidThread // Returned script thread ID
);

Parameters

pstidThread

[out] Returned script thread ID associated with the current thread. The interpretation of this identifier is left to the scripting engine, and may in fact, just be a copy of the Windows thread id. Note that if the Win32 thread terminates, this ID becomes unassigned and may subsequently be assigned to another thread. This method may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite.

Return Values

S_OK

Success.

E_POINTER

An invalid pointer was passed.

Remarks

TBD

See Also

IOleScript::InterruptScriptThread , IOleScriptSite

[TOC]

IOleScript::GetExensibilityObject [Beta]

Returns the IDispatch for methods/properties associated with scripting engine dependent extensions. This is the dispinterface through which automation of the scripting engine itself (not the script) is accomplished.

HRESULT IOleScript::GetExensibilityObject(
IDispatch **ppdisp // Returned object
);

Parameters

ppdisp

[out] The returned object to be added to the host's object model. If there is no extensibility object for this scripting engine, NULL is returned.

Return Values

S_OK

Success.

S_FALSE

There is no extensibility object. NULL is returned in ppdisp.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

TBD

See Also

IDispatch

[TOC]

IOleScript::GetScriptMacroObject [Beta]

Returns the IDispatch for methods/properties associated with the running script itself.

HRESULT IOleScript::GetScriptMacroObject(
LPCOLESTR pstrItemName, // TBD
IDispatch **ppdisp// Returned object
);

Parameters

pstrItemName

[in] TBD

ppdisp

[out] The returned object associated with the script's global methods/properties. If the scripting engine does not support such an object, NULL is returned.

Return Values

S_OK

Success.

S_FALSE

The scripting engine does not support a macro object. NULL is returned in ppdisp.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

Normally, this object contains as its members all of the global methods and properties defined by the script. Through this interface (and its associated ITypeInfo), the host can invoke script methods or view/modify script variables. Note that this is a dynamic interface in that methods and properties can be added and removed via IOleScriptParse , etc.

See Also

ITypeInfo, ITypeInfo, IDispatch , IOleScriptParse

[TOC]

IOleScript::GetScriptSite [Beta]

Retrieves the site object associated with the OLE Scripting engine.

HRESULT IOleScript::GetScriptSite(
REFIID iid, // Interface IID
void **ppvSiteObject// Returned interface pointer
);

Parameters

iid

[in] The IID of the requested interface.

ppvSiteObject

[out] The returned interface pointer to the site object.

Return Values

S_OK

Success.

S_FALSE

Success, but no site has yet been set, so ppvSiteObject is NULL.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

E_NOINTERFACE

The specified interface is not supported.

Remarks

TBD

See Also

TBD

[TOC]

IOleScript::GetScriptState [Beta]

Returns the current state of the scripting engine.

HRESULT IOleScript::GetScriptState(
SCRIPTSTATE *pssState // Script state
);

Parameters

pssState

[out] The script has not yet been initialized using an IPersist interface.

Return Values

SCRIPTSTATE

Returned state of the indicated thread, as:

SCRIPTSTAT_UNITIALIZED

The script has not yet been initialized using an IPersist interface.

SCRIPTSTAT_LOADED

The script has been initialized with IPersist, but is not running (connected to other objects, sourcing or sinking events). Note that this state simply means that IPersist*::Load has completed and that Run may be called. It is possible that further background initialization (progressive loading) is still ongoing, and that calling Run may cause the script to block until initialization is complete.

SCRIPTSTATE_CONNECTED

The script is loaded and connected for sinking events.

SCRIPTSTATE_DISCONNECTED

The script is loaded and has a runtime execution state, but is temporarily disconnected from sinking events.

SCRIPTSTAE_ZOMBIED

The script has been closed. The scripting engine will no longer work, returning errors for most methods.

S_OK

Success.

E_POINTER

An invalid pointer was passed.

Remarks

This method may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite .

See Also

IOleScriptSite , IPersist, IPersist::Load, IOleScript::Run

[TOC]

IOleScript::GetScriptThreadID [Beta]

Returns a scripting engine defined identifier for the currently executing thread. This identifier can then be used in subsequent calls to script thread execution control methods such as InterruptScriptThread, etc.

HRESULT IOleScript::GetScriptThreadID(
DWORD dwWin32ThreadID, // Thread ID
SCRIPTTHREADID *pstidThread // Returned script thread ID
);

Parameters

dwWin32ThreadID

[in] The thread ID of a running Win32 thread in the current process. Use GetCurrentThreadID for this parameter to get the thread ID of the currently executing thread.

pstidThread

[out] Returned script thread ID associated with the indicated Win32 thread. The interpretation of this identifier is left to the scripting engine, and may in fact, just be a copy of the Windows thread id. Note that if the Win32 thread terminates, this ID becomes unassigned and may subsequently be assigned to another thread. This method may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite .

Return Values

S_OK

Success.

E_POINTER

An invalid pointer was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

TBD

See Also

IOleScript::InterruptScriptThread , IOleScript::InterruptScriptThread , IOleScript::GetCurrentScriptThreadID , IOleScriptSite

[TOC]

IOleScript::GetScriptThreadState [Beta]

Returns the current state of a script thread.

HRESULT IOleScript::GetScriptThreadState(
SCRIPTTHREADID stidThread, // ID of desired thread
SCRIPTTHREADSTATE *pstsState // Sate of dersired thread
);

Parameters

stidThread

[in]

SCRIPTTHREADID

Thread ID of thread for which state is desired. The following special thread IDs can be used:

SCRIPTTHREADID_CURRENT

The currently executing thread.

SCRIPTTHREADID_BASE

The base thread (the thread in which the scripting engine was instantiated)

pstsState

[out]

SCRIPTTHREADSTATE

Returned state of the indicated thread, as:

SCRIPTTHREADSTATE_NOTINSCRIPT

The specified thread is not currently servicing a scripted event, processing immediately executed script text, or running a script macro.

SCRIPTTHREADSTATE_RUNNING

The specified thread is actively servicing a scripted event, processing immediately executed script text, or running a script macro.

SCRIPTTHREADSTATE_BLOCKED

The specified thread is servicing a scripted event, processing immediately executed script text, or running a script macro, but is currently blocked on an asynchronous (and potentially time-consuming) task, such as I/O.

Return Values

S_OK

Success.

E_POINTER

An invalid pointer was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Note that if this is not the current thread, the state may of course change at any time. This method may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite .

See Also

IOleScriptSite

[TOC]

IOleScript::InterruptScriptThread [Beta]

Interrupts the execution of a running script thread, either an event sink, an immediate execution, or a macro invocation.

HRESULT IOleScript::InterruptScriptThread(
SCRIPTTHREADID stidThread, // ID of thread to interrupt
const EXCEPINFO *pexcepinfo // Error information
DWORD dwflags// Option flags
);

Parameters

stidThread

SCRIPTTHREADID

[in] Thread ID of thread to interrupt. The following special thread IDs can be used:

SCRIPTTHREADID_CURRENT

The currently executing thread.

SCRIPTTHREADID_BASE

The base thread (the thread in which the scripting engine was instantiated).

SCRIPTTHREADID_ALL

All threads. The interrupt is applied to all script methods currently in progress. Note that unless the caller has requested that the script be disconnected (with Disconnect or Stop ), the next scripted event will cause script code to run again.

pexcepinfo

[in] Error information associated with the error condition (for macro invocations and immediate execution, this is returned to the caller).

dwflags

[in]Option flags associated with the interruption.

SCRIPTINTERRUPT_DEBUG

If supported, enter the scripting engine's debugger at the current script execution point.

SCRIPTINTERRUPT_RAISEEXCEPTION

If supported by the scripting engine's language, let the script handle the exception. Otherwise, the script method is aborted and the error code is returned to the caller (the event source or macro invoker).

Return Values

S_OK

Success, indicated thread will be interrupted.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

This method can be used to terminate a script that is stuck in an infinite loop, etc. It may be called from non-base threads without resulting in a non-base callout to host objects or to IOleScriptSite.

See Also

IOleScriptSite , IOleScript::Disconnect , IOleScript::Stop

[TOC]

IOleScript::RemoveItem [Beta]

Removes an item previously added with AddNamedItem.

HRESULT IOleScript::RemoveItem(
LPCOLESTR pstrname // Item name from AddNamedItem
);

Parameters

pstrname

[in] Name of the item as supplied to AddNamedItem .

Return Values

S_OK

Success, the item has been removed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

TYPE_E_ELEMENTNOTFOUND

The name was not found.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

TBD

See Also

IOleScript::AddNamedItem

[TOC]

IOleScript::RemoveTypeLib [Beta]

Removes a type library previously added with AddTypeLib .

HRESULT IOleScript::RemoveTypeLib(
REFGUID rguidTypeLib // Type library GUID
);

Parameters

rguidTypeLib

[in] GUID of the Type library, as specified in AddTypeLib.

Return Values

S_OK

Success, the specified type library has been removed.

S_FALSE

The specified type library has not been added with AddTypeLib .

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_INVALIDARG

An invalid argument was passed.

Remarks

For some scripting engines, such as compilers, this may be an expensive operation, requiring the compilation of the script.

See Also

IOleScript::AddTypeLib

[TOC]

IOleScript::RenameItem [Beta]

Notifies the scripting engine that a specific item has changed names.

HRESULT IOleScript::RenameItem(
LPCOLESTR pstrNameOld, // Previous item name
LPCOLESTR pstrNewName // New item name
);

Parameters

pstrNameOld

[in] Previous name of the item, as supplied to AddNamedItem .

pstrNameNew

[in] New name of the item. Must be unique.

Return Values

S_OK

Success, item name has been changed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

TYPE_E_ELEMENTNOTFOUND

The old name was not found.

TYPE_E_NAMECONFLICT

The new name conflicts with an existing name in the script's namespace.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

TBD

See Also

IOleScript::AddNamedItem

[TOC]

IOleScript::Run [Beta]

Moves the scripting engine from the loaded to the connected state.

HRESULT IOleScript::Run();

Return Values

S_OK

Success, the script has been started.

S_FALSE

Success, but the script was already running.

OLESCRIPT_S_PENDING

The function was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IOleScriptSite::OnStateChange .

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Causes the scripting engine to source/sink events, and runs a script initialization procedure, if any. In VBA, for example, this will cause the Page_Initialize event to be fired.

See Also

IOleScriptSite::OnStateChange

[TOC]

IOleScript::SetScriptSite [Beta]

Informs scripting engine of its IOleScriptSite site provided by the host.

HRESULT IOleScript::SetScriptSite(
IOleScriptSite *pioss // Host supplied script site
);

Parameters

pioss

[in] The host-supplied script site to be associated with this instance of the scripting engine. This site must be uniquely assigned to this scripting engine instance; it can not be shared with other scripting engines.

Return Values

S_OK

Success

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

E_FAIL

Unspecified error. The scripting engine was unable to complete its site initialization.

E_UNEXPECTED

The call was not expected. (E.g. a site has already been set.)

Remarks

This method must be called before any other IOleScript methods may be used.

See Also

IOleScriptSite

[TOC]

IOleScript::Stop [Beta]

Moves scripting engine from the connected or disconnected states to the loaded state.

HRESULT IOleScript::Stop();

Return Values

S_OK

Success, the script has been stopped.

S_FALSE

Success, but the script was already stopped.

OLESCRIPT_S_PENDING

The function was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IOleScriptSite::OnStateChange .

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

Remarks

Event sinks that are in progress are completed before the state changes (use InterruptScriptThread to cancel a running script thread). Causes the scripting engine to stop sinking events. Any execution state is lost; when Run is subsequently called, the script will be reinitialized.

See Also

IOleScript::InterruptScriptThread , IOleScript::Run

[TOC]

IOleScriptParse [Beta]

If the OLE Scripting engine allows raw text code "sniplets" to be added to the script, or allows expression text to be evaluated at runtime, it implements IOleScriptParse . For interpreted scripting languages which have no independent authoring environment, such as JavaScript, this provides an alternate mechanism (other than IPersist and IOleScriptAuthor) to get script code into the scripting engine, and to attach script fragments to various object events.

[TOC]

IOleScriptParse::AddScriptText [Beta]

Adds a code "sniplet" to the script.

HRESULT IOleScriptParse::AddScriptText(
LPCOLESTR pstrDefaultName, // Default name for code sniplet
LPCOLESTR pstrCode,// Code sniplet to add
LPCOLESTR pstrItemName, // Named item associated with this sniplet
LPCOLESTR pstrSubItemName, // Subobject of named item associated with this sniplet
LPCOLESTR pstrEventName, // Event for which this sniplet is the event handler
LPCOLESTR pstrDelimiter // TBD
DWORD dwFlags,// SCRIPTTEXT flags associated with this sniplet
BSTR *pbstrName, // Name of sniplet
EXCEPINFO *pexcepinfo // Pointer to structure for exception information
);

Parameters

pstrDefaultName

[in] A default name to associate with the code sniplet. If the code sniplet does not contain naming information (as it does not in the ONCLICK example above), this name will be used to identify the sniplet. If this parameter is NULL, the scripting engine will manufacture a unique name if necessary.

pstrCode

[in] The code sniplet, in OLE textual form, to add. The interpretation of this string is language dependent.

pstrItemName

[in] Identifies the named item this code sniplet is associated with. This parameter, in addition to pstrSubItemName, identify the specific object for which the code sniplet is an event handler.

pstrSubItemName

[in] Identifies a subobject of the named item with which this code sniplet is associated; this name must be found in the named item's type information. A NULL is passed if the code sniplet is to be associated with the named item instead of a sub-item. This parameter, in addition to pstrItemName, identify the specific object for which the code sniplet is an event handler.

pstrEventName

[in] Identifies for which event the code sniplet is an event handler.

pstrDelimiter

TBD

dwFlags

[in] Flags associated with the sniplet:

SCRIPTTEXT_ISPERSISTENT

Indicates that the sniplet (and its associated connection, if any) is to become part of the scripting engine's persistent state. Provided the script is saved after the item is added, it will not be necessary to add the text again (or connect to the connection point) the next time the script is loaded. Since only authoring environments allow a dirty script to be saved, this flag is really only usefully set in an authoring situation. Items added in this way by an authoring tool, however, will be present and useable when the script is later instantiated from a non-authoring host.

SCRIPTTEXT_ISVISIBLE

Indicates that the script text should be visible (and therefore, callable by name) as a global method in the namespace of the script.

pbstrName

[out] The actual name used to identify the sniplet. This will be, in order of preference: a name explicitly specified in the sniplet text, the default name provided in pstrDefaultName, or a unique name synthesized by the scripting engine.

pexcepinfo

[out] Pointer to a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.

Return Values

S_OK

Success, the sniplet has been added to the script, and its name is returned in pbstrName.

OLESCRIPT_E_INVALIDNAME

The default name supplied is invalid in this scripting language.

OLESCRIPT_E_SYNTAX

There was a unspecified syntax error in the code sniplet.

DISP_E_EXCEPTION

An exception occurred in the parsing of the sniplet. Exception information is returned in pexcepinfo.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_NOTIMPL

Method not supported, the scripting engine does not support adding event-sinking sniplets.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

Remarks

This method is used in environments where the persistent state of the script is intertwined with the host document and must be restored under the host's control, rather than though IPersist. The primary example is JavaScript, which allows sniplets of code imbedded in the HTML document to be attached to intrinsic events; e.g. ONCLICK="button1.text='Exit';".

See Also

IPersist

[TOC]

IOleScriptParse::EvaluateScriptText [Beta]

Evaluates a code "sniplet" immediately.

HRESULT IOleScriptParse::EvaluateScriptText(
LPCOLESTR pstrCode, // Code sniplet to evaluate
LPCOLESTR pstrItemName, // Context in which to evaluate sniplet
IUnknown *punkContext, // Reserved for use in debugging environment
LPCOLESTR pstrDelimiter // TBD
DWORD dwFlags, // SCRIPTTEXT flags associated with sniplet
VARIANT *pvarResult, // Pointer to result
EXCEPINFO *pexcepinfo // Pointer to structure for exception information
);

Parameters

pstrCode

[in] The code sniplet, in OLE textual form, to evaluate. The interpretation of this string is language dependent.

pstrItemName

[in] Identifies the context in which the code sniplet is to be evaluated. If NULL, then the code is evaluated in the scripting engine's global context.

punkContext

[in] Reserved for use in a debugging environment, where such a context may be provided by the debugger to represent an active runtime context. If NULL, pstrItemName is used to identify the context.

pstrDelimiter

TBD

dwFlags

[in] Flags associated with the sniplet:

SCRIPTTEXT_ISEXPRESSION

If the distinction between a computational expression and a statement is important but syntactically ambiguous in the script language, this flag specifies that the sniplet is to be interpreted as an expression, rather than as a statement or list of statements. By default, statements are assumed unless the correct choice can be determined from the syntax of the sniplet text.

SCRIPTTEXT_ KEEPDEFINITIONS

If this flag is set and the sniplet defines new global methods or objects, these items will become part of the script state for the life of the scripting engine. Unlike AddScriptText , EvaluateScriptText requires that such definitions to be explicitly named in the script text, since there may be multiple definitions and no single definition is associated with the entire script text fragment.

SCRIPTTEXT_ ISPERSISTENT

If this flag is set along with SCRIPTTEXT_KEEPDEFINITIONS, methods and objects defined by the sniplet will be come part of the scripting engine's persistent state. Provided the script state is saved after the item is added, it will not be necessary to evaluate the definitions again the next time the script is loaded. Since only authoring environments allow a dirty script to be saved, this flag is really only usefully set in an authoring situation. Items added in this way by an authoring tool, however, will be present and useable when the script is later loaded by a non-authoring host.

pvarResult

[out] Pointer to where the result is to be stored, or NULL if the caller expects no result.

pexcepinfo

[out] Pointer to a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.

Return Values

S_OK

Success, the expression or statement(s) have been evaluated. The result, if any, is returned in pvarResult.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

DISP_E_EXCEPTION

An exception occurred in the processing of the sniplet. Exception information is returned in pexcepinfo.

OLESCRIPT_E_SYNTAX

There was a unspecified syntax error in the code sniplet.

E_NOTIMPL

The function is not supported. The scripting engine does not support run-time evaluation of expressions or statements.

Remarks

The sniplet may be an expression, a list of statements, or anything allowed by the script language. For example, this method is used with JavaScript, which allows statements to be executed as the HTML page is being constructed, rather than just compiling them into the script state.

See Also

IOleScriptParse::AddScriptText

[TOC]

IOleScriptParse::RemoveScriptText [Beta]

Removes a code "sniplet" previously added with AddScriptText.

HRESULT IOleScriptParse::RemoveScriptText(
LPCOLESTR pstrName // Name of sniplet as returned from AddScriptText
);

Parameters

pstrName

[in] The name used to identify the sniplet, as returned from AddScriptText.

Return Values

S_OK

Success, code sniplet has been removed.

E_POINTER

An invalid pointer was passed.

E_UNEXPECTED

The call was not expected. (E.g. the scripting engine has not yet been loaded or initialized.)

E_INVALIDARG

An invalid argument was passed.

TYPE_E_ELEMENTNOTFOUND

A sniplet of the specified name was not found.

Remarks

TBD

See Also

IOleScriptParse::AddScriptText

[TOC]

IOleScriptSite [Beta]

The host must create a site for the OLE Scripting engine by implementing IOleScriptSite. Usually this site will be associated with the container of all the objects which will be visible to the script (OCXs, etc.). Typically, this container will correspond to the document or page being viewed. The Internet Explorer (IE), for example, would create such a container for each HTML page being displayed. Each OCX (or other OLE automation object) on the page, and the scripting engine itself, would be enumerable within this container.

[TOC]

IOleScriptSite::GetComponentManager [Beta]

Returns the IMsoComponentManager for the containing processes (usually, the host's message loop).

HRESULT IOleScript::GetComponentManager(
IComponentManager **ppicm // Returned component manager interface
);

Parameters

ppicm

[out] The returned component manager interface.

Return Values

S_OK

Success.

E_POINTER

An invalid pointer was passed.

Remarks

This may be NULL, but if it is, the scripting engine may fail to initialize if it requires this functionality, or may be unable to perform certain functions such as authoring, debugging, or displaying UI. The scripting engine uses this interface to get access to idle time, push the message loop (for example, to change accelerator key mappings), etc.

See Also

IMsoComponentManager

[TOC]

IOleScriptSite::GetDocVersionString [Beta]

Returns an host-defined string which uniquely identifies the current document version from the host's point of view.

HRESULT IOleScript::GetDocVersionString(
BSTR *pszVersion // Document version string
);

Parameters

pszVersion

[out] The host-defined document version string.

Return Values

S_OK

Success, the document version string is returned in pstrVersionString.

E_NOTIMPL

The method is not supported. The scripting engine should assume that the script is in sync with the document.

Remarks

The scripting engine may choose to save this along with its persisted state, forcing a recompile, etc., the next time the script is loaded if the related document has changed outside the scope of OLE Scripting (as in the case of an HTML page being edited with NotePad).

See Also

TBD

[TOC]

IOleScriptSite::GetItemInfo [Beta]

Allows the scripting engine to obtain information about an item added with IOleScript::AddNamedItem .

HRESULT IOleScript::GetItemInfo(
LPCOLESTR pstrName, // Name associated with item
DWORD dwReturnMask,// Bit mask specifying information to return about item
DWORD *pdwFlags,// SCRIPTINFO item flags for this item
IUnknown **ppunkItem, // Unknown associated with item
ITypeInfo **ppTypeInfo // ITypeInfo associated with item
);

Parameters

pstrName

[in] The name associated with the item, as specified in IOleScript::AddNamedItem.

dwReturnMask

[in] A bit mask specifying what information about the item should be returned. The scripting engine should take care to request the minimum needed information, since some of these return parameters (e.g., ITypeInfo) may take considerable time to load or generate.

pdwFlags

[out] Item flags, as set in IOleScript::AddNamedItem. NULL is returned if SCRIPTINFO_FLAGS is not set in dwReturnMask.

SCRIPTINFO_ FLAGS

Return the item flags for this item.

SCRIPTINFO_ IUNKNOWN

Return the IUnknown for this item.

SCRIPTINFO_ ITYPEINFO

Return the ITypeInfo for this item.

ppunkItem

[out] The IUnknown associated with the item. Through this, the scripting engine can QueryInterface for IDispatch, etc. NULL is returned if SCRIPTINFO_IUNKNOWN is not set in dwReturnMask. At design time, when there may not actually be an object instance associated with the name, this may be returned as NULL.

ppTypeInfo

[out] The ITypeInfo associated with the item. NULL is returned if SCRIPTINFO_ITYPEINFO is not set in dwReturnMask. NULL is also returned if type information is not available for this item. In this case, the object cannot source events, and name binding must be realized with IDispatch::GetIDsOfNames.

Return Values

S_OK

Success, the relevant out parameters have been set.

E_POINTER

An invalid pointer was passed.

E_INVALIDARG

An invalid argument was passed.

TYPE_E_ELEMENTNOTFOUND

An item of the specified name was not found.

Remarks

Note that if NULL is passed in for each out parameter pointer, the respective result is not returned. This improves performance, for example, in the case where an ITypeInfo is not needed for an item.

See Also

ITypeInfo, IDispatch, IUnknown, IUnknown::QueryInterface, IDispatch::GetIDsOfNames

[TOC]

IOleScriptSite::GetLCID [Beta]

Retrieves the Language ID associated with the script site.

HRESULT IOleScript::GetLCID(
LCID *plcid // Returned language ID
);

Parameters

plcid

[out] The returned language ID.

Return Values

S_OK

Success, lcid contains the appropriate LCID.

E_POINTER

An invalid pointer was passed.

E_NOTIMPL

Use the sytem LCID.

Remarks

This allows localizable scripts and scripting engines to be constructed. If this method returns E_NOTIMPL, the system LCID should be used.

See Also

TBD

[TOC]

IOleScriptSite::GetWindow [Beta]

Returns the HWND of the controlling window. This may be NULL, but if it is, certain UI support associated with the scripting engine may be disabled.

HRESULT IOleScript:Site::GetWindow(
HWND *phwnd) // Returned HWND of controlling window
);

Parameters

phwnd

[out] The returned HWND of the controlling window.

Return Values

S_OK

Success, the window handle is returned in phwnd.

E_POINTER

An invalid pointer was passed.

E_NOTIMPL

There is no controlling HWND. NULL is returned in phwnd.

Remarks

TBD

See Also

TBD

[TOC]

IOleScriptSite::OnExecutionError [Beta]

This method is called when an execution error occurs while running the script.

HRESULT IOleScriptSite::OnExecutionError(
EXCEPINFO *pexcepinfo // Exception information associated with error condition
);

Parameters

pexcepinfo

Error information associated with the error condition.

Return Values

S_OK

The scripting engine should continue running the script as best as as possible (perhaps abandoning the processing of this event).

S_FALSE

The scripting engine should continue running the script in the debugger, if a debugger is available. If a debugger is not available, then this should be treated just like E_FAIL.

E_FAIL

The scripting engine should abort execution of the script and return it to a loaded state. In this case, pexcepinfo is generally passed on to OnScriptTerminate.

Remarks

TBD

See Also

IOleScriptSite::OnScriptTerminate

[TOC]

IOleScriptSite::OnScriptTerminate [Beta]

Informs the host that the script has completed execution.

HRESULT IOleScript::OnScriptTerminate(
const VARIANT *pvarResult, // Pointer to script results
const EXCEPINFO *pexcepinfo // Pointer to structure for exception information
);

Parameters

pvarResult

[in] Pointer to where the script result is stored, or NULL if the script produced no result.

pexcepinfo

[in] Pointer to a structure containing exception information generated at script termination, or NULL if no exception was generated.

Return Values

S_OK

Success.

Remarks

This method is called before OnStateChange( SCRIPTSTATE_LOADED). It can be used to return completion status/results to the host. Note that many script languages, which are based on sinking events from the host, have lifespans which are defined by the host. In this case, this method may never be called.

See Also

IOleScriptSite::OnStateChange

[TOC]

IOleScriptSite::OnStateChange [Beta]

Informs the host that the scripting engine has changed states.

HRESULT IOleScript::OnStateChange(
SCRIPTSTATE ssScriptState // The new script state
);

Parameters

ssScriptState

SCRIPTSTATE

[in] The new script state:

SCRIPTSTATE_ UNINITIALIZED

The script has not yet been initialized using an IPersist interface.

SCRIPTSTATE_ LOADED

The script has been initialized with IPersist, but is not running (connected to other objects, sourcing or sinking events). Note that this state simply means that IPersist::Load has completed and that Run may be called. It is possible that further background intialization (progressive loading) is still ongoing, and that calling Run may cause the script to block until initialization is complete.

SCRIPTSTATE_ CONNECTED

The script is loaded and connected for sinking events.

SCRIPTSTATE_ DISCONNECTED

The script is loaded and has a runtime execution state, but is temporarily disconnected from sinking events..

SCRIPTSTATE_ ZOMBIED

The script has been closed. The scripting engine will no longer work, returning errors for most methods.

Return Values

S_OK

Success.

Remarks

TBD

See Also

IPersist, IPersist::Load, IOleScript::Run

[TOC]

IOleScriptSite::RequestItems [Beta]

Causes the script site to call IOleScript::AddNamedItem for each persistent named item associated with the script.

HRESULT IOleScript::RequestItems();

Return Values

S_OK

Success.

Remarks

When the scripting engine detects a synchronization problem between its persisted state and that of the host, it throws away it's persisted view of the namespace, and calls RequestItems.

See Also

IOleScript::AddNamedItem

[TOC]

IOleScriptSite::RequestTypeLibs [Beta]

Causes the script site to call IOleScript::AddTypeLib for each type library associated with the namespace.

HRESULT IOleScript::RequestTypeLibs();

Return Values

S_OK

Success.

Remarks

TBD

See Also

IOleScript::AddTypeLib

[TOC]

IPersistMemory [Beta]

IPersistMemory operates exactly as IPersistStreamInit, except that it allows the caller to provide a fixed-size memory block (identified with a void *) as opposed to IPersistStreamInit which involves an arbitrarily expandable IStream.

The cbSize argument to the Load and Save methods indicate the amount of memory accessible through pvMem.

The IsDirty, GetSizeMax, and InitNew methods are semantically and syntactically identical to those in IPersistStreamInit. Only Load and Save differ.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IPersist Method Description
GetClassIDReturns the class identifier (CLSID) for the component object.

IPersistMemory Methods Description
IsDirty Checks the object for changes since it was last saved.
Load Initializes an object from the memory block where it was previously saved.
Save Saves an object into the specified memory block and indicates whether the object should reset its dirty flag.
GetSizeMax Returns the size in bytes of the memory block needed to save the object.
InitNew Initializes an object to a default state.

[TOC]

IPersistMemory::GetSizeMax [Beta]

Returns the size in bytes of the memory block needed to save the object.

HRESULT GetSizeMax(
ULARGE_INTEGER *pcbSize // Pointer to size of memory needed to save object
);

Parameter

pcbSize

[out]Points to a 64-bit unsigned integer value indicating the size in bytes of the memory needed to save this object.

Return Value

S_OK

The size was successfully returned.

Remarks

This method returns the size needed to save an object. You can call this method to determine the size and set the necessary buffers before calling the IPersistMemory::Save method.

Notes to Implementors

The GetSizeMax implementation must return a conservative estimate of the necessary size because the IPersistMemory::Save method uses a fixed size memory block.

See Also

IPersistMemory::Save

[TOC]

IPersistMemory::InitNew [Beta]

Initializes the object to a default state. This method is called instead of IPersistMemory::Load.

HRESULT InitNew(void);

Return Values

S_OK

The object successfully initialized itself.

E_NOTIMPL

The object requires no default initialization. This error code is allowed because an object may choose to implement IPersistMemory simply for orthogonality or in anticipation of a future need for this method.

E_UNEXPECTED

This method was called after the object was already initialized with IPersistMemory::Load. Only one initialization is allowed per instance.

E_OUTOFMEMORY

There was not enough memory for the object to initialize itself.

Notes to Implementers

If the object has already been initialized with Load, then this method must return E_UNEXPECTED.

See Also

IPersistMemory::Load

[TOC]

IPersistMemory::IsDirty [Beta]

Checks the object for changes since it was last saved.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved. The dirty flag for an object is conditionally cleared in the IPersistMemory::Save method.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. In other words, unless this method explicitly returns S_FALSE, you must assume that the object needs to be saved.

See Also

IPersistMemory::Save

[TOC]

IPersistMemory::Load [Beta]

Instructs the object to load its persistent data from the memory pointed to by pvMem where cbSize indicates the amount of memory at pvMem. The object must not read past the address (BYTE*)((BYTE *)pvMem+cbSize).

HRESULT Load(
void *pvMem, // Pointer to the stream from which the object should be loaded
ULONG cbSize// Amount of memory from which the object can read its data
);

Parameters

pvMem

[in] The address of the memory from which the object can read up to cbSize bytes of its data.

cbSize

[in] The amount of memory available at pvMem from which the object can read its data.

Return Values

S_OK

The object successfully loaded its data.

E_UNEXPECTED

This method was called after the object was already initialized with IPersistMemory::Load. Only one initialization is allowed per instance.

E_POINTER

The pointer in pvMem is NULL.

Remarks

Any object that implements IPersistMemory has some information to load persistently, therefore E_NOTIMPL is not a valid return code.

See Also

IPersistMemory::InitNew

[TOC]

IPersistMemory::Save [Beta]

Instructs the object to save its persistent data to the memory pointed to by pvMem where cbSize indicates the amount of memory available at pvMem. The object must not write past the address (BYTE*)((BYTE *)pvMem+cbSize). The fClearDirty flag determines whether the object is to clear its dirty state after the save is complete.

HRESULT Save(
void *pvMem, // Pointer to the stream where the object is to be saved
BOOL fClearDirty,// Specifies whether to clear the dirty flag
ULONG cbSize// Amount of memory to which the object can write its data
);

Parameters

pvMem

[in] The address of the memory in which the object should save up to cbSize bytes of its data.

fClearDirty

[in] A flag indicating whether the object should clear its dirty state on return from Save or leave that state as-is.

cbSize

[in] The amount of memory available at pvMem to which the object can write its data.

Return Values

S_OK

The object successfully initialized itself.

E_UNEXPECTED

This method was called before the object was initialized with IPersistMemory::InitNew or IPersistMemory::Load.

E_INVALIDARG

The number of bytes indicated by cbSize is too small to allow the object to save itself completely.

E_POINTER

The pointer in pvMem is NULL.

Remarks

Any object that implements IPersistMemory has some information to save persistently, therefore E_NOTIMPL is not a valid return code.

The caller should ideally allocate as many bytes as the object returns from IPersistMemory::GetSizeMax.

See Also

IPersistMemory::InitNew , IPersistMemory::Load

[TOC]

IPersistMoniker [Beta]

Objects, especially asynchronous-aware objects may expose the IPersistMoniker interface to obtain more control over the way they bind to their persistent data.

Existing moniker implementations call QueryInterface on the client objectfor persistence interfaces such as IPersistFile, IPersistStream[Init], or IPersistStorage as part of their IMoniker::BindToObject implementation when they are instantiating and initializing the object. IPersistMoniker allows moniker implementations and other applications that instantiate objects from persistent data to give control to the object over binding to its persistent data. Objects could, for example implement IPersistMoniker::Load by calling IMoniker::BindToStorage for the interface they prefer - IStorage, IStream, asynchronously bound, etc.

The IPersistMoniker contract inherits its definition from the IPersist interface, and so the includes the GetClassID method of IPersist.

When to Implement

Implement IPersistMoniker on any object that can be saved persistently to multiple storage mediums or can take advantage of any of the asynchronous stream, storage, or IMoniker::BindToStorage behavior described above.

When to Use

Custom moniker implementations should support IPersistMoniker as the most flexible persistence interface in their implementation of IMoniker::BindToObject if they are instantiating an arbitrary class and need to initialize it from persistent data. Typically these monikers should use the published persistence interfaces in the following order: IPersistMoniker, IPersistStream[Init], IPersistStorage, IPersistFile, and IPersistMemory.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IPersist Method Description
GetClassIDReturns the class identifier (CLSID) for the object.

IPersistMoniker Methods Description
IsDirty Checks an object for changes since it was last saved.
Load Loads an object using a specified moniker.
Save Saves the object, specifying a destination moniker.
SaveCompleted Notifies the object that the save operation is complete.
GetCurMoniker Gets the current moniker for the object.

[TOC]

IPersistMoniker::GetCurMoniker [Beta]

Retrieves the moniker that refers to the object's persistent state.

HRESULT GetCurMoniker(
IMoniker ** ppmkCur // Location to return the moniker to the object's current persistent state.
);

Parameter

ppmkCur

[out]On return, points to a pointer to the moniker that indicates the object's current persistent state.

Return Values

S_OK

A valid absolute path was successfully returned.

E_INVALIDARG

The ppmkCur argument is invalid.

Remarks

Retrieves the moniker that refers to the object's persistent state. Typically, this is the moniker last passed to the object via IPersistMoniker::Load or IPersistMoniker::Save or SaveCompleted.

See Also

IPersistMoniker::Load , IPersistMoniker::Save , IPersistMoniker::SaveCompleted

[TOC]

IPersistMoniker::IsDirty [Beta]

Checks an object for changes since it was last saved.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

IPersistMoniker::IsDirty checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved.

See Also

IPersistMoniker::Save

[TOC]

IPersistMoniker::Load [Beta]

Loads the object indicated by a supplied moniker.

HRESULT Load(
IMoniker ** pmkSrc, // Points to source moniker pointer
DWORD grfMode// Specifies the access mode from the STGM enumeration
IBindCtx * pbc// Points to the moniker's bind context
);

Parameters

pmkSrc

[in]A reference to the persistent state to initialize this object from.

dwMode

[in] Specifies some combination of the values from the STGM enumeration which indicate the access mode to use when binding to the persistent state. The IPersistMoniker::Load method can treat this value as a suggestion, adding more restrictive permissions if necessary. If grfMode is zero, the implementation should bind to the persistent state using default permissions.

pbc

[in] IBindCtx pointer to the bind context to be used for any moniker binding during this method.

Return Values

S_OK

The object was successfully loaded.

E_INVALIDARG

One or more arguments are invalid.

Remarks

IPersistMoniker::Load loads an object from the persistent state referred to by pmkSrc. Typically the object will immediately bind to its persistent state through a call to the source moniker's IMoniker::BindToStorage method, requesting either the IStream or IStorage interface.

See Also

[TOC]

IPersistMoniker::Save [Beta]

Requests that the object save itself into the location referred to by pmkDst.

HRESULT Save(
IMoniker * pmkDst, // Pointer to destination moniker
BOOL fRemember// Specifies whether the destination moniker is to be the current working one
IBindCtx * pbc// Points to the moniker's bind context
);

Parameters

pmkDst

[in] IMoniker pointer to the moniker that indicates the location where the object should save itself persistently. The object typically binds to the location through a call to the destination monker's (pmkDst) IMoniker::BindToStorage, requesting either the IStream or IStorage interface. The parameter may be NULL, in which case the object is requested to save itself to the same location referred to by the moniker passed to it in IPersistMoniker::Load . This may act as an optimization to prevent the object from binding, since it has typically already bound to the moniker it was loaded from.

fRemember

[in]Indicates whether pmkDst is to be used as the reference to the current persistent state after the save. If TRUE, pmkDst becomes the reference to the current persistent state and the object should clear its dirty flag after the save. If FALSE, this save operation is a "Save A Copy As ..." operation. In this case, the reference to the current persistent state is unchanged and the object should not clear its dirty flag. If pmkDst is NULL, the implementation should ignore the fRemember flag.

pbc

[in] IBindCtx pointer to the bind context to be used for any moniker binding during this method.

Return Values

S_OK

The object was successfully saved.

E_INVALIDARG

One or more arguments are invalid.

See Also

IPersistMoniker::GetCurMoniker , IPersistMoniker::SaveCompleted , IPersistMoniker::Load

[TOC]

IPersistMoniker::SaveCompleted [Beta]

Notifies the object that it has been completely saved.

HRESULT SaveCompleted(
IMoniker * pmkNew // The moniker to the object's new persistent state
);

Parameter

pmkNew

[in]The moniker to the object's new persistent state, or NULL as an optimization if the moniker to the object's new persistent state is the same as the previous moniker to the object's persistent state. This is allowed only if there was a prior call to IPersistMoniker::Save with fRemember set to TRUE - in which case the object need not rebind to pmkNew.

Return Value

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

Remarks

Notifies the object that it has been completely saved and points it to its new persisted state. Typically the object will immediately bind to its persistent state through a call to the pmkNew IMoniker::BindToStorage method, requesting either the IStream or IStorage interface, as in IPersistMoniker::Load .

See Also

IPersistMoniker::Save

[TOC]

IPersistPropertyBag [Beta]

The IPersistPropertyBag interface works in conjunction with IPropertyBag and IErrorLog to define an individual property-based persistence mechanism. Whereas a mechanism like IPersistStream gives an object an IStream in which to store its binary data, IPersistPropertyBag provides an object with an IPropertyBag interface through which it can save and load individual properties. The implementor of IPropertyBag can then save those properties in whatever way it chooses, such as name/value pairs in a text file. Errors encountered in the process (on either side) are recorded in an error log through IErrorLog. This error reporting mechanism work on a per-property basis instead of an all properties as a whole basis through just the return value of IPersist*::Load or IPersist*::Save.

The basic mechanism is that a container tells the object to save or load its properties through IPersistPropertyBag. For each property, the object calls the container's IPropertyBag interface passed to the IPersistPropertyBag methods. IPropertyBag::Write saves a property in whatever place the container wants to put it, and IPropertyBag::Read retrieves a property.

This protocol is essentially a means of sequentially communicating individual property values from the object to the container, which is useful for doing save-as-text operations and the like. The object gives the container the choice of the format in which each property is saved, while retaining itself the decision as to which properties are saved or loaded.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IPersist Method Description
GetClassIDReturns the class identifier (CLSID) for the component object.

IPersistPropertyBag Methods Description
InitNew Informs the object that it is being initialized as a newly created object.
Load Instructs the object to initialize itself using the properties in the property bag and notifying the error log when errors occur.
Save Instructs object to save its properties to the specified property bag.

See Also

IErrorLog , IPropertyBag

[TOC]

IPersistPropertyBag::InitNew [Beta]

Informs the object that it is being initialized as a newly created object.

HRESULT InitNew(void);

Return Values

S_OK

The object successfully initialized itself. This should be returned even if the object doesn't do anything in the method.

E_UNEXPECTED

This method was called after IPersistPropertyBag::Load or IPersistPropertyBag::Save.

Remarks

E_NOTIMPL should not be returned¾use S_OK when the object has nothing to do in the method.

See Also

IPersistPropertyBag::Load

[TOC]

IPersistPropertyBag::Load [Beta]

Instructs the object to initialize itself using the properties available in the property bag, notifying the provided error log object when errors occur. All property storage must take place within this method call as the object cannot hold the IPropertyBag pointer.

HRESULT Load(
IPropertyBag *pPropBag, // Points to caller's property bag
IErrorLog *pErrorLog // Points to error log
);

Parameters

pPropBag

[in] A pointer to the caller's property bag through which the object can read properties. Cannot be NULL.

pErrorLog

[in] A pointer to the caller's error log in which the object stores any errors that occur during initialization. Can be NULL in which case the caller is not interested in errors.

Return Values

S_OK

The object successfully initialized itself.

E_UNEXPECTED

This method was called after IPersistPropertyBag::InitNew has already been called. They two initialization methods are mutually exclusive.

E_POINTER

The address in pPropBag is not valid (such as NULL) and therefore the object cannot initialize itself.

E_FAIL

The object was unable to retrieve a critical property that is necessary for the object's successful operation. The object was therefore unable to initialize itself completely.

Remarks

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPersistPropertyBag::InitNew

[TOC]

IPersistPropertyBag::Save [Beta]

Instructs the object to save its properties to the given property bag, optionally clearing the object's dirty flag. The caller can request that the object save all properties or that the object save only those that are known to have changed.

HRESULT Save(
IPropertyBag *pPropBag, // Points to the caller's property bag
BOOL fClearDirty,// Specifies whether to clear the dirty flag
BOOL fSaveAllProperties // Specifies whether to save all properties or just those that have changed
);

Parameters

pPropBag

[in] A pointer to the caller's property bag through which the object can write properties. Cannot be NULL.

fClearDirty

[in] A flag indicating whether the object should clear its dirty flag when saving is complete. TRUE means clear the flag, FALSE means leave the flag unaffected. FALSE is used when the caller wishes to do a Save Copy As type of operation.

fSaveAllProperties

[in] A flag indicating whether the object should save all its properties (TRUE) or only those that have changed since the last save or initialization (FALSE).

Return Values

S_OK

The object successfully saved the requested properties itself.

E_FAIL

There was a problem saving one of the properties. The object can choose to fail only if a necessary property could not be saved, meaning that the object can assume default property values if a given property is not seen through IPersistPropertyBag::Load at some later time.

E_POINTER

The address in pPropBag is not valid (such as NULL) and therefore the object cannot initialize itself.

Remarks

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPersistPropertyBag::InitNew , IPersistPropertyBag::Load

[TOC]

IPersistStream - URL Moniker Implementation [Beta]

The URL moniker implementation of IPersistStream is found on a URL moniker object, which also supports IUnknown, IMonikerAsync, and IMoniker. (IMonikerAsync is simply IUnknown (there are no actual methods), and is used to allow clients to determine transparently if a moniker supports asynchronous binding.) To get a pointer to the IMoniker interface on this object, call the CreateURLMoniker function. Then, to get a pointer to IPersistStream, call the QueryInterface method. IPersistStream, in addition to inheriting its definition from IUnknown, also inherits the single method of IPersist, GetClassID.

When to Use

Call to have the moniker manage its persistent storage.

Remarks

IPersistStream::GetClassID

Returns CLSID_URLMoniker.

IPersistStream::IsDirty

Returns S_OK if the Moniker has changed since it was last saved (IPersistStream::Save with fClearDirty==TRUE), S_FALSE otherwise.

IPersistStream::Load

Initializes a URL moniker from data within a stream, usually stored there previously using its IPersistStream::Save (via OleSaveToStream or OleSaveToStreamEx). The binary format of URL Moniker is its URL string in Unicode™ (may be a full or partial URL string, see CreateURLMoniker for details). This is represented as a ULONG (32-bit) count of characters followed by that many Unicode characters.

IPersistStream::Save

Saves a URL moniker to a stream. The binary format of URL Moniker is its URL string in Unicode (may be a full or partial URL string, see CreateURLMoniker for details). This is represented as a ULONG (32-bit) count of characters followed by that many Unicode™ characters.

IPersistStream::GetSizeMax

Returns the maximum number of bytes in the stream that will be required by a subsequent call to IPersistStream::Save. This value is SIZEOF(ULONG)==4 plus SIZEOF(WCHAR)*n where n is the length of the full or partial URL string including the NULL terminator.

See Also

IPersist, IPersistStream, IMoniker - URL Moniker Implementation

[TOC]

IPrint [Beta]

The IPrint interface enables OLE objects in general and document objects in particular to support programmatic printing. Once a document is loaded, containers and other clients can call IPrint::Print to instruct a document to print itself specifying printing control flags, the target device, the particular pages to print, and other options. The client can also control the continuation of printing by calling the IContinueCallback interface. In the future, additional print-related interfaces may be defined that will be available through QueryInterface where IPrint represents merely a base level of support.

An object that implements IPrint registers itself with the "Printable" key stored under its CLSID as follows:

HKEY_CLASSES_ROOT\CLSID\{...}\Printable

Callers determine whether a particular object class supports programmatic printing of its persistent state by looking in the registry for the "Printable" key.

When to Implement

Implementing IPrint is optional. You will usually implement IPrint on whatever object is able to load the persistent state of a given document type; that is, on the same object that also implements either IPersistFile or IPersistStorage for that type.

When to Use

Call IPrint when you want an object to print its current state. Using this interface, a caller can tell the object to print itself, set the initial page number of the printed document, and return both the number of pages and the number of the first page to be printed.

Methods in VTable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces
AddRefIncrements reference count
ReleaseDecrements reference count

IPrint Methods Description
SetInitialPageNum Sets number of first page
GetPageInfo Returns number of pages and number of first page
Print Prints object's persistent state

[TOC]

IPrint::GetPageInfo [Beta]

Retrieves the number of a document's first page as well as the total number of pages.

HRESULT GetPageInfo(
LONG *nFirstPage // Pointer to number of first page
LONG *pcPages// Pointer to total number of pages
);

Parameters

pnFirstPage

[out] Pointer to the page number of the first page. May be NULL, indicating the caller doesn't need this number. If IPrint::SetInitialPageNum has been called, this parameter should contain the same value passed to that method. Otherwise, the value is the document's internal first page number.

pcPages

Pointer to the total number of pages in this document. May be NULL, indicating the caller doesn't need this number.

Return Value

S_OK

The first page was set as requested.

E_UNEXPECTED

An unknown error occurred.

[TOC]

IPrint::Print [Beta]

Prints an object on the specified printer, using the specified job requirements.

HRESULT Print(
DWORD grfFlags // A bit field
DVTARGETDEVICE **pptd // On return, Indirect pointer to the target device
PAGESET **pppageset // On return, Indirect pointer to the set of pages to be printed
STGMEDIUM *pstgmOptions // Pointer to object-specific printing options
IContinueCallback *pcallback // Pointer to callback interface
LONG nFirstPage// Number of first page to be printed
LONG *pcPagesPrinted // Pointer to total number of pages printed
LONG *pnLastPage// Pointer to number of last page to be printed
);

Parameters

grfFlags

[in] A bit field whose values are taken from the enumeration PRINTFLAG.

pptd

[in, out]The target device on which the printing is to occur.

ppPageSet

[in, out] Indicates which pages are to be printed.

ppstgmOptions

[unique][in, out] Contains object-specific printing options in the form of a serialized OLE property set. May be NULL in one or both directions.

pCallback

[in] A callback interface which is to be periodically polled at human-response speeds to determine whether printing should be abandoned. May be NULL.

nFirstPage

[in] The page number of the first page to be printed. This value overrides any value previously passed to IPrint::SetInitialPageNum .

pcPagesPrinted

[out] The place at which the object is to return the actual number of pages that were successfully printed.

pnLastPage

[out] The place at which the object is to return the last legal page number.

Return Values

S_OK

Success

PRINT_E_CANCELED

The print process was canceled. *pcPagesPrinted indicates the number of pages that were in fact successfully printed before this error occurred.

PRINT_E_NOSUCHPAGE

An attempt has been made to print a page which does not exist.

E_UNEXPECTED

An unexpected error occurred.

Remarks

The printer on which the object is to be printed is indicated by the DVTARGETDEVICE structure in ptd. The DEVMODE structure in the target device indicates whole-job printer-specific options, such as number of copies, paper size, print quality, and other options. The DEVMODE structure may or may not also contain orientation information in the dmOrientation field (this is indicated in the dmFields field). If present, then this paper orientation should be used; if absent, then natural orientation as determined by the object content is to be used.

Due to the possibility of user input, the parameters pptd and ppPageSet are both [in,out] structures. In the absence of user interaction (that is, without PRINTFLAG_PROMPTUSER), both the target device and the page set will necessarily be the same for input and output. However, if the user is prompted for print options, then the object returns target device and page-set information appropriate to what the user has actually chosen.

The ppstgmOptions parameter is also [in,out]. On exit, the object should return through *ppstgmOptions any object-specific information that it would need to reproduce this exact print job. Examples might include whether the user selected "sheet, notes, or both" in a spreadsheet application. The data returned is in the format of a serialized property set. The returned data is normally useful only when passed back in a subsequent call to the same object. Because a subsequent call may specify different user interaction flags, target device, or other settings, the caller can cause the exact same document to be printed multiple times in slightly different printing contexts.

See Also

[TOC]

IPrint::SetInitialPageNum [Beta]

Attempts to set the number of the first page of a document.

HRESULT SetInitialPageNum(
LONG nFirstPage // Number of first page
);

Parameters

nFirstPage

[in] The desired first page number

Return Value

S_OK

The first page was set as requested.

E_FAIL

The first page could not be set to the indicated value.

E_UNEXPECTED

An unknown error occurred.

Remarks

Note that setting a negative first page number is legal: this may be useful in printing a portion of the document with offset page numbers from what it would normally print. Note also that not all implementations permit the initial page number to be set, as some implementations simply lack the information as to how this page information should be reflected in the final output.

[TOC]

IPropertyBag [Beta]

When a client wishes to have exact control over how individually named properties of an object are saved, it would attempt to use an object's IPersistPropertyBag interface as a persistence mechanism. In that case the client supplies a property bag to the object in the form of an IPropertyBag interface.

When the object wishes to read a property in IPersistPropertyBag::Load it will call IPropertyBag::Read. When the object is saving properties in IPersistPropertyBag::Save it will call IPropertyBag::Write. Each property is described with a name in pszPropName whose value is exchanged in a VARIANT. This information allows a client to save the property values as text, for instance, which is the primary reason why a client might choose to support IPersistPropertyBag.

The client records errors that occur during reading into the supplied error log.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IPropertyBag Methods Description
Read Asks the property bag to read the specified property into a caller-initialized VARIANT.
Write Asks the property bag to save the specified property using the type and value in the caller-initialized VARIANT.

See Also

IErrorLog , IPersistPropertyBag

[TOC]

IPropertyBag::Read [Beta]

Asks the property bag to read the property named with pszPropName into the caller-initialized VARIANT in pVar. Errors that occur are logged in the error log pointed to by pErrorLog. When pVar->vt specifies another object pointer (VT_UNKNOWN) then the property bag is responsible for creating and initializing the object described by pszPropName.

HRESULT Read(
LPCOLESTR pszPropName, // Points to the property to be read
VARIANT * pVar,// Points to the VARIANT to receive the property value
IErrorLog * pErrorLog // Points to the caller's error log
);

Parameters

pszPropName

[in] The name of the property to read. Cannot be NULL.

pVar

[in, out] The address of the caller-initialized VARIANT that is to receive the property value on output. The method must set both type and value fields in the VARIANT before returning. If the caller initialized the pVar->vt field on entry, the property bag should attempt to coerce the value it knows into this type. If the caller sets pVar->vt to VT_EMPTY, the property bag can use whatever type is convenient.

pErrorLog

[in] A pointer to the caller's error log in which the property bag stores any errors that occur during reads. Can be NULL in which case the caller is not interested in errors.

Return Values

S_OK

The property was read successfully. The caller becomes responsible for any allocations that are contained in the VARIANT in pVar.

E_POINTER

The address in pszPropName is not valid (such as NULL).

E_INVALIDARG

The property named with pszPropName does not exist in the property bag.

E_FAIL

The property bag was unable to read the specified property, such as if the caller specified a data type to which the property bag could not coerce the known value. If the caller supplied an error log, a more descriptive error was sent there.

Remarks

E_NOTIMPL is not a valid return code since any object implementing this interface must support the entire functionality of the interface.

See Also

IPropertyBag::Write

[TOC]

IPropertyBag::Write [Beta]

Asks the property bag to save the property named with pszPropName using the type and value in the caller-initialized VARIANT in pVar. In some cases the caller may be asking the property bag to save another object, that is, when pVar->vt is VT_UNKNOWN. In such cases, the property bag queries this object pointer for some persistence interface, like IPersistStream or even IPersistPropertyBag again and has that object save its data as well. Usually, this results in the property bag having some byte array for this object which can be saved as encoded text (hex string, MIME, etc.). When the property bag is later used to reinitialize a control, the client that owns the property bag must recreate the object when the caller asks for it, initializing that object with the previously saved bits.

This allows very efficient persistence operations for large BLOB properties like a picture, where the owner of the property bag itself directly asks the picture object (managed as a property in the control being saved) to save into a specific location. This avoids potential extra copy operations that would be involved with other property-based persistence mechanisms.

HRESULT Write(
LPCOLESTR pszPropName, // Points to the property to be written
VARIANT * pVar// Points to the VARIANT containing the property value and type
);

Parameters

pszPropName

[in] The name of the property to write. Cannot be NULL.

pVar

[in] The address of the caller-initialized VARIANT that holds the property value to save. The caller owns this VARIANT and is responsible for all allocations therein. That is, the property bag itself does not attempt to free data in the VARIANT.

Return Values

S_OK

The property bag successfully saved the requested property.

E_FAIL

There was a problem writing the property. It is possible that the property bag does not understand how to save a particular VARIANT type.

E_POINTER

The address in pszPropName or pVar is not valid (such as NULL). The caller must supply both.

Remarks

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPropertyBag::Read

[TOC]

IProvideClassInfo2 [Beta]

IProvideClassInfo2 is a simples extension to IProvideClassInfo for the purpose of making it quick and easy to retrieve an object's outgoing interface IID for its default event set. The mechanism, the added GetGUID method, is extensible for other types of GUIDs as well.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IProvideClassInfo Method Description
GetClassInfoReturns the ITypeInfo interface for the object's coclass type information.

IProvideClassInfo2 Method Description
GetGUID Returns the GUID for the object's outgoing IID for its default event set.

[TOC]

IProvideClassInfo2::GetGUID [Beta]

Returns a GUID corresponding to the specified dwGuidKind. The dwGuidKind parameter has several values defined. See GUIDKIND . Additional flags can be defined at a later time and will be recognized by an IProvideClassInfo2 implementation. See IProvideClassInfo3 .

HRESULT GetGUID(
DWORD dwGuidKind, // Specifies the desired GUID
GUID *pGUID// Receives a pointer to the desired GUID
);

Parameters

dwGuidKind

[in] Specifies the GUID desired on return. This parameter takes a value from the GUIDKIND enumeration.

pGUID

[out] The address of the caller's variable in which to store the GUID associated with dwGuidKind.

Return Values

S_OK

The GUID was successfully returned in *pGUID.

E_POINTER

The address in pGUID is not valid (such as NULL).

E_UNEXPECTED

An unknown error occurred.

E_INVALIDARG

The dwGuidKind value does not correspond to a supported GUID kind.

Remarks

E_NOTIMPL is not a valid return code since it would be pointless to implement this interface without implementing this method. E_INVALIDARG is not valid when dwGuidKind is GUIDKIND_DEFAULT_SOURCE_DISP_IID and the object is not implementing IProvideClassInfo2 as part of its implementation of IProvideClassInfo3.

Any object implementing IProvideClassInfo3 should support at least GUIDKIND_DEFAULT_IID through this method, so E_NOTIMPL is not a valid return code for IProvideClassInfo3 as it is for IProvideClassInfo2.

See Also

GUIDKIND , IProvideClassInfo3

[TOC]

IProvideClassInfo3 [Beta]

This interface is an extension to IProvideClassInfo2 to provide various pieces of object-level information directly from the object (as opposed to using the registry or some other means that does not involve the object). As such it is intended to be a generic object-information interface. This interface also corrects the absence of an LCID in IProvideClassInfo::GetClassInfo.

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IProvideClassInfo Method Description
GetClassInfoReturns the ITypeInfo interface for the object's coclass type information.

IProvideClassInfo2 Method Description
GetGUID Returns the GUID for the object's outgoing IID for its default event set.

IProvideClassInfo3 Method Description
GetGUIDDwordArraysProvides a caller with easy access to a substantial amount of object information that generally exists or can be expressed at arrays of GUIDs and/or DWORDs.
GetClassInfoLocaleReturns an LCID locale identifier for the specified type.
GetFlagsReturns a DWORD containing up to 32 mutually-inclusive (generally) bit flags that are all related to the flag group identified by guidGroup.

See Also

GUIDKIND , IProvideClassInfo2::GetGUID

[TOC]

IProvideClassInfo3::GetClassInfoLocale [Beta]

Returns a pointer to the ITypeInfo interface for the object's type information. The type information for an object corresponds to the object's coclass entry in a type library. This method also uses a locale identifier (LCID) to specify the locale so that locale-specific type information is returned. This method is similar to IProvideClassInfo::GetClassInfo.

HRESULT GetClassInfoLocale(
ITypeInfo **ppTypeInfo, // Receives an indirect pointer to the ITypeInfo interface
LCID lcid// Specifies the locale identifier
);

Parameters

ppTypeInfo

[out] The address of the caller's ITypeInfo * variable in which to store the object's type information. The caller is responsible for calling ITypeInfo::Release on the returned pointer if this method returns successfully.

lcid

[in] Specifies the locale.

Return Values

S_OK

The type information was successfully returned.

E_POINTER

The address in ppTypeInfo is not valid. For example, it may be NULL.

E_UNEXPECTED

An unexpected error occurred.

E_OUTOFMEMORY

The type information could not be retrieved.

Remarks

The caller is responsible for calling ITypeInfo::Release when the returned interface pointer is no longer needed.

[TOC]

IProvideClassInfo3::GetFlags [Beta]

Returns a DWORD containing up to 32 mutually-inclusive (generally) bit flags that are all related to the flag group identified by guidGroup. This method is extensible as the owner of a particular group can add new bit flags at any time to that group (provided there are enough bits remaining) and that anyone can create a new group GUID and assign flags as desired.

This method is designed to handle many future uses of bit flags that have traditionally been limited to the MiscStatus bits as returned from IOleObject::GetMiscStatus. At the time of writing, only one group has been defined, FLAGID_Internet, with only one bit in that group, INTERNETFLAG_USESDATAPATH. This bit indicates that the object uses one or more data path properties to manage BLOB data storage. See INTERNETFLAG .

HRESULT GetFlags(
REFGUID guidGroup, // Specifies the flag group requested by the caller
DWORD *pdwFlags// Receives a pointer to the flag values
);

Parameters

guidGroup

[in] Unique identifier of the flag group desired by the caller.

pdwFlags

[out] The address of the caller's variable in which to store the DWORD containing the bit flags associated with guidGroup.

Return Values

S_OK

The DWORD was successfully returned in *pdwFlags.

E_POINTER

The address in pdwFlags is not valid (such as NULL).

E_UNEXPECTED

An unknown error occurred.

E_INVALIDARG

The guidGroup value does not correspond to a group known by this object.

E_NOTIMPL

The object supports no flag groups and therefore has no reason to implement this method.

[TOC]

IProvideClassInfo3::GetGUIDDwordArrays [Beta]

Provides a caller with easy access to a substantial amount of object information that generally exists or can be expressed at arrays of GUIDs and/or DWORDs. Through this method a caller can obtain an array of GUIDs, an array of DWORDs, or both. When this method returns information in both arrays, then there is a relationship between the elements of both arrays, that is, pcaUUID[0] and pcadw[0] are related in some way, depending on the kind of array in question as described by rguidArray.

HRESULT GetGUIDDwordArrays(
REFGUID rguidArray, // Specifies requested GUID or DWORDs
CAUUID *pcaUUID,// Points to CAUUID structure in which to store requested GUIDs
CADWORD *pcadw// Points to CADWORD structure in which to store requested DWORDs
);

Return Values

rguidArray

[in] Identifier of the GUIDs or DWORDs desired on return. This parameter can have the following values. Additional array types can be defined by anyone at any time by simply defining another ARRAYID for use with this method.

ARRAYID_Interfaces_Incoming

On return, pcaUUID contains the interface identifiers of all the object's possible incoming interfaces that a client might access through QueryInterface. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero). These IIDs are only suggestions of what the object supports and in no way guarantee support at run-time. A client must always request an interface through QueryInterface(riid) and must be able to handle the E_NOINTERFACE failure code even if riid was specified in this array.

ARRAYID_Interfaces_Outgoing

On return, pcaUUID contains the interface identifiers of all the object's outgoing interfaces, that is, those that would be marked as [source] in an object's type library. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero). These IIDs are only suggestions of what the object supports and in no way guarantee support at run-time. A client must always connect to an outgoing interface through IConnectionPointContainer::FindConnectionPoint(riid) must handle the possible failure of this call even if riid in question was specified in this array.

ARRAYID_Categories_Implemented

On return, pcaUUID contains the CATIDs of the object's supported categories. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero).

ARRAYID_Categories_Required

On return, pcaUUID contains the CATIDs of the object's required categories, that is, the necessary container-side support without which the object cannot operate. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero).

ARRAYID_PathProperties

On return, pcadw contains the dispIDs of the object's data path properties, and pcaUUID contains the GUIDs identifying the OLE_DATAPATH_ type of the corresponding property in pcadw. The object must allocate and fill both arrays in this case, and both arrays must container the same number of elements.

ARRAYID_Methods_Primary

On return, pcadw contains the dispIDs of the object's primary methods that best describe its user-level functionality¾such methods would be displayed in the caller's user interface for providing features like event binding. In this case, pcaUUID.cElems must be zero.

ARRAYID_Methods_Secondary

On return, pcadw contains the dispIDs of the object's seconday methods that is exactly the list of all object methods excluding those returned from ARRAYID_Methods_Primary. In this case, pcaUUID.cElems must be zero.

pcaUUID

[in, out] The address of the caller-allocated and initialized CAUUID structure in which to store the GUIDs associated with rguidArray, if applicable. The caller is responsible for freeing any allocated memory returned in this structure.

pcadw

[in, out] The address of the caller-allocated and initialized CADWORD structure in which to store the DWORDs associated with rguidArray, if applicable. The caller is responsible for freeing any allocated memory returned in this structure.

Return Values

This method can return several success codes that identify which array was or was not filled. This provides an alternate means for the caller to identify which arrays contain allocated data and which do not. On failure the object must return zero and NULL in the cElems and pElems fields of both structures, respectively. That is, the caller need not free any allocations on failure.

S_OK

Both CAUUID and CADWORD arrays were successfully allocated and filled.

CLASSINFO_S_ONLYGUIDS

Only the CAUUID array was allocated and filled whereas the CADWORD array was not needed. In this case CADWORD::cElems must be zero and CADWORD::pElems must be NULL.

CLASSINFO_S_ONLYDWORDS

Only the CADWORD array was allocated and filled whereas the CAUUID array was not needed. In this case CAUUID::cElems must be zero and CAUUID::pElems must be NULL.

E_OUTOFMEMORY

One of the arrays could not be allocated.

E_POINTER

The address in either pcaUUID or pcadw is not valid (such as NULL).

E_UNEXPECTED

An unknown error occurred.

E_INVALIDARG

The rguidArray value does not correspond to a supported array.

Remarks

E_NOTIMPL is not a valid return code for this method as all objects can at least support ARRAYID_Interfaces_Incoming.

The data structures CAUUID and CADWORD were originally defined for other OLE Controls interfaces like ISpecifyPropertyPages and IPerPropertyBrowsing. These structures are defined as follows:

typedef struct tagCAUUID
{
ULONG cElems;
GUID *pElems;
} CAUUID;

typedef struct tagCADWORD
{
ULONG cElems;
DWORD *pElems;
} CADWORD;

In these definitions, cElems is the number of entries in the array pointed to by pElems. The structures themselves are caller-allocated and caller-initialized so cElems is zero and pElems is NULL. The structures are filled on output by the object implementing the method, where cElems describes the number of elements that the object stored in pElems, where the pElems array itself is object-allocated using CoTaskMemAlloc. On successful return, the caller is responsible for freeing any allocated memory in these structures. That is, if pElems is non-NULL (cElems is non-zero) then the caller must call CoTaskMemFree(pElems) when the array is no longer needed.

[TOC]

IShellExplorer [Beta]

The IShellExplorer interface TBD

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements reference count.
ReleaseDecrements reference count.

IDispatch Methods Description
GetIDsOfNamesReturns the number of type descriptions for object
GetTypeInfoRetrieves a description of objects programmable interface
GetTypeInfoCountMaps name of method or property to DISPID
InvokeCalls one of the object's methods, or gets/sets one of its properties

IShellExplorer Methods Description
get_Value //Retrieves the friendly name of the location
get_Location //Retrieves location in namespace to view
put_Location //Sets location in namespace to view
get_FolderFlags //Retrieves FWF folder flags
put_FolderFlags //Sets FWF folder flags
get_FolderViewMode //Retrieves FVM folder view mode
put_FolderViewMode //Sets FVM folder view mode
get_AutoSize //Retrieves auto-size mode
put_AutoSize //Sets auto-size mode
get_BorderVisible //Retrieves border-visible flag
put_BorderVisible //Retrieves border-visible flag
Browse //Browse for a new folder to view
Navigate //Navigates to a hyperlink
Refresh //Refreshes the current file
GoBack //Navigates to the previous item in history list
GoForward //Navigates to the next item in history list
GoHome //Navigates to the home/start page
GoSearch //Navigates to the search page
Open //Opens a file
Stop //Stops opening a file
PrintOut //Prints the current document
get_Application //Retrieves a pointer to this OC
get_Container //Retrieves a pointer to the container
get_Document //Retrieves the active document
get_Parent //Retrieves a pointer to the parent object
get_TopLevelContainer //TBD
get_Type //Retrieves the type of the contained object
get_Visible //Retrieves whether or not this OC is visible
put_Visible //Sets whether or not this OC is visible
get_Width //Retrieves the horizontal dimension of the frame window
put_Width //Sets the horizontal dimension of the frame window
get_Height //Retrieves the vertical dimension of the frame window
put_Height //Sets the vertical dimension of the frame window
get_Busy //Retrieves whether or not something is still in progress

[TOC]

IShellExplorer::Browse [Beta]

Browse for a new folder to view.

HRESULT IShellExplorer::Browse(
);

Return Values

TBD

[TOC]

IShellExplorer::Close [Beta]

TBD

HRESULT IShellExplorer::Close(
TBD// TBD
);

Return Values

TBD

[TOC]

IShellExplorer::get_Application [Beta]

TBD

HRESULT IShellExplorer::get_Application(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_AutoSize [Beta]

Returns auto-size mode.

HRESULT IShellExplorer::get_AutoSize(
boolean * pfAutoSize // TBD
);

Parameters

pfAutoSize

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_BorderVisible [Beta]

Returns border-visible flag.

HRESULT IShellExplorer::get_BorderVisible(
boolean * pfBorderVisible // TBD
);

Parameters

pfBorderVisible

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Busy [Beta]

Query to see if something is still in progress.

HRESULT IShellExplorer::get_Busy(
boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Container [Beta]

Returns a pointer to the container.

HRESULT IShellExplorer::get_Container(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Document [Beta]

Returns the active Document.

HRESULT IShellExplorer::get_Document(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_FolderFlags [Beta]

Returns FWF_ folder flags.

HRESULT IShellExplorer::get_FolderFlags(
int * pfFlags // TBD
);

Parameters

pfFlags

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_FolderViewMode [Beta]

Returns FVM_ folder view mode.

HRESULT IShellExplorer::get_FolderViewMode(
int * pnViewMode // TBD
);

Parameters

pnViewMode

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Height [Beta]

The vertical dimension (pixels) of the frame window.

HRESULT IShellExplorer::get_Height(
long * plHeight // TBD
);

Parameters

plHeight

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Location [Beta]

Returns location in namespace to view.

HRESULT IShellExplorer::get_Location(
BSTR * pbstrLocation // TBD
);

Parameters

pbstrLocation

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Parent [Beta]

Returns a pointer to the parent Object.

HRESULT IShellExplorer::get_Parent(
IDispatch ** ppDisp // TBD
);

Parameters

ppDisp

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_TopLevelContainer [Beta]

TBD

HRESULT IShellExplorer::get_TopLevelContainer(
Boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Type [Beta]

Returns the type of the contained object.

HRESULT IShellExplorer::get_Type(
BSTR * pbstrType // TBD
);

Parameters

pbstrType

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Value [Beta]

Returns the friendly name of the Location

HRESULT IShellExplorer::get_Value(
BSTR * pbstrLocation // TBD
);

Parameters

pbstrLocation

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Visible [Beta]

Determines whether this OC is visible or hidden.

HRESULT IShellExplorer::get_Visible(
Boolean * pBool // TBD
);

Parameters

pBool

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::get_Width [Beta]

The horizontal dimension (pixels) of the frame window

HRESULT IShellExplorer::get_Width(
long * plWidth // TBD
);

Parameters

plWidth

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::GoBack [Beta]

Navigates to the previous item in the history list.

HRESULT IShellExplorer::GoBack(
);

Return Values

TBD

[TOC]

IShellExplorer::GoForward [Beta]

Navigates to the next item in the history list.

HRESULT IShellExplorer::GoForward(

);

Return Values

TBD

[TOC]

IShellExplorer::GoHome [Beta]

Go to home/start page.

HRESULT IShellExplorer::GoHome(

);

Return Values

TBD

[TOC]

IShellExplorer::GoSearch [Beta]

Go Search Page.

HRESULT IShellExplorer::GoSearch(

);

Return Values

TBD

[TOC]

IShellExplorer::Navigate [Beta]

Navigates to a hyperlink.

HRESULT IShellExplorer::Navigate(
DHyperlink * Hlink // TBD
VARIANT * OpenInNewWindow // TBD
VARIANT * NoHistory// TBD
);

Parameters

Hlink

[in] TBD

OpenInNewWindow

[in] TBD

NoHistory

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::Open [Beta]

Opens a file.

HRESULT IShellExplorer::Open(
BSTR Target // TBD
VARIANT * Location// TBD
VARIANT * NoHistory// TBD
);

Parameters

Target

[in] TBD

Location

[in] TBD

NoHistory

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::PrintOut [Beta]

Prints the current document.

HRESULT IShellExplorer::PrintOut(
long What // TBD
VARIANT Numbering// TBD
VARIANT FirstPage// TBD
VARIANT Sections// TBD
VARIANT FileName// TBD
VARIANT PrinterName// TBD
VARIANT DriverName// TBD
VARIANT PortName// TBD
VARIANT NoPrinting// TBD
);

Parameters

What

[in] TBD

Numbering

[in] TBD

FirstPage

[in] TBD

Sections

[in] TBD

FileName

[in] TBD

PrinterName

[in] TBD

DriverName

[in] TBD

PortName

[in] TBD

NoPrinting

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_AutoSize [Beta]

Sets auto-size mode.

HRESULT IShellExplorer::put_AutoSize(
boolean fAutoSize // TBD
);

Parameters

fAutoSize

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_BorderVisible [Beta]

Sets border-visible flag.

HRESULT IShellExplorer::put_BorderVisible(
boolean fBorderVisible // TBD
);

Parameters

fBorderVisible

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_FolderFlags [Beta]

Sets FWF_ folder flags.

HRESULT IShellExplorer::put_FolderFlags(
int fFlags // TBD
);

Parameters

fFlags

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_FolderViewMode [Beta]

Sets FVM_ folder view mode.

HRESULT IShellExplorer::put_FolderViewMode(
int nViewMode // TBD
);

Parameters

nViewMode

[out] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_Height [Beta]

Sets the vertical dimension (pixels) of the frame window.

HRESULT IShellExplorer::put_Height(
long lHeight // TBD
);

Parameters

lHeight

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_Location [Beta]

Sets location in namespace to view.

HRESULT IShellExplorer::put_Location(
BSTR bstrLocation // TBD
);

Parameters

bstrLocation

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_Visible [Beta]

Sets whether this OC is visible or hidden.

HRESULT IShellExplorer::put_Visible(
Boolean bValue // TBD
);

Parameters

bValue

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::put_Width [Beta]

Sets the horizontal dimension (pixels) of the frame window

HRESULT IShellExplorer::put_Width(
long lWidth // TBD
);

Parameters

lWidth

[in] TBD

Return Values

TBD

[TOC]

IShellExplorer::Quit [Beta]

Exits Shell Explorer and closes the open window.

HRESULT IShellExplorer::Quit(
);

Return Values

TBD

[TOC]

IShellExplorer::Refresh [Beta]

Refreshes the current file.

HRESULT IShellExplorer::Refresh(

);

Return Values

TBD

[TOC]

IShellExplorer::Stop [Beta]

Stops opening a file.

HRESULT IShellExplorer::Stop(

);

Return Values

TBD

[TOC]

IWinINetInfo [Beta]

A protocol component which uses standard WinINet APIs as its implementation may support IWinINetInfo. Callers can retrieve the HINTERNET and use the handle directly with Win32 WinINet APIs. Such low-level manipulation should be used with extreme caution so as not to interfere with the higher-level functionality of the binding process that URL monikers and the protocol component provide.

When to Implement

Only custom protocol component writers need to implement this interface.

When to Use

It is unusual to need to use these low-level services, however a client may QueryInterface for IBinding whenever an IBinding is available (for example, as received by the highest-level client in IBindStatusCallback::OnStartBinding ).

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IWinINetInfo Methods Description
GetConnectionHandle Retrieves the WinInet HINTERNET handle of the transport.

[TOC]

IWinINetInfo::GetConnectionHandle [Beta]

Retrieves the WinInet HINTERNET handle of the transport. This low-level hook allows callers of the URL moniker near-WinSock level control over the binding process.

HRESULT GetConnectionHandle(
HINTERNET phinternet // The location in which to return the HINTERNET of the current binding
);

Parameter

phinternet

[out]The location in which to return the HINTERNET (internet handle) of the current binding

Return Values

S_OK

Success.

E_FAIL

This transport is not implemented using WinINet, and so can not return an HINTERNET.

E_INVALIDARG

The phinternet argument is invalid.

Remarks

Retrieves the WinInet HINTERNET handle of the transport. This low-level hook allows callers of the URL moniker near-WinSock level control over the binding process.

Note The HINTERNET handle is valid only for the duration of the binding. Once the client's IBindStatusCallback::OnStopBinding is called, this handle is no longer valid and must not be used.

See Also

IBindStatusCallback::OnStopBinding

[TOC]

IWinSockInfo [Beta]

A protocol component which uses standard WinSock APIs as its implementation may support IWinSockInfo. Callers can retrieve the SOCKET and use the handle directly with Win32 WinSock APIs. Such low-level manipulation should be used with extreme caution so as not to interfere with the higher-level functionality of the binding process that URL monikers and the protocol component provide.

When to Implement

Only custom protocol component writers need to implement this interface.

When to Use

It is unusual to need to use these low-level services, however a client may QueryInterface for IBinding whenever an IBinding is available (for example, as received by the highest-level client in IBindStatusCallback::OnStartBinding ).

Methods in Vtable Order
IUnknown Methods Description
QueryInterfaceReturns pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.

IWinSockInfo Methods Description
GetSocket Retrieves the socket handle.

[TOC]

IWinSockInfo::GetSocket [Beta]

Retrieves the socket handle.

HRESULT GetSocket(
SOCKET * psocket // Location to return the SOCKET of the current binding.
);

Parameter

psocket

[in]Location to return the SOCKET of the current binding. May not be NULL.

Return Values

S_OK

Success.

E_FAIL

This transport is not implemented using WinSock, and so can not return a SOCKET.

E_INVALIDARG

The psocket argument is invalid.

Remarks

This allows the caller to party on the SOCKET handle. This is the lowest-level hook that gives clients of the URL moniker WinSock-level control over the binding process.

Note The SOCKET handle is valid only for the duration of the binding. Once the client's IBindStatusCallback::OnStopBinding is called, this handle is no longer valid and must not be used.

See Also

IBindStatusCallback::OnStopBinding