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 |
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
DHyperLink::get_Target [Beta]
Returns the target of a hyperlink.
HRESULT DHyperLink::get_Target(
BSTR * pbstrTarget | // TBD |
); |
Parameters
pbstrTarget
[out] TBD
Return Values
TBD
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
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
DHyperLink::put_Target [Beta]
Sets the target for the hyperlink.
HRESULT DHyperLink::put_Target(
BSTR bstrTarget | // TBD |
); |
Parameters
bstrTarget
[in] TBD
Return Values
TBD
IBasicAuthentication [Beta]
The single method of IBasicAuthentication provides basic authentication information from a bind client.
Only custom protocol writers need to implement this interface.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements the reference count. |
IBasicAuthentication Methods | Description |
Authenticate | Supplies basic authentication to a URL moniker from a bind client. |
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
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IBindHost Methods | Description |
ParseDisplayName | Turns a text name into a moniker. |
GetBindContext | Supplies a pointer to an implementation of IBindCtx. |
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.
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.
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.
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements 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. |
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
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
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
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
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
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.
Only custom protocol writers need to implement this interface. They typically register their component with the system as described above.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements the reference count. |
IBindProtocol Methods | Description |
CreateBinding | Checks an object for changes since it was last saved. |
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
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.
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements 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. |
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
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
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
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
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
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
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
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
ICatInformation [Beta]
The ICatInformation interface provides methods for obtaining information about available categories.
Implement ICatInformation to manipulate the Registry keys under the CLSID root key.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements 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
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
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
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
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
ICatRegister [Beta]
The ICatRegister interface provides methods for registering and unregistering component category information in the Registry.
Implement ICatRegister to manipulate the Registry keys under the CLSID root key.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements 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
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
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
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
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
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 |
QueryInterface | Returns pointers to supported interfaces |
AddRef | Increments reference count |
Release | Decrements reference count |
IContinueCallback Methods | Description |
FContinue | Answers whether an operation should continue |
FContinuePrinting | Answers whether a printing operation should continue |
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
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
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IDataPathBrowser Methods | Description |
BrowseType | Invokes a browsing user interface for the specified type. |
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.
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.
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.
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
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
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
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
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.
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IErrorLog Method | Description |
AddError | Logs an error (an EXCEPINFO structure) in the error log for a named property. |
See Also
IPersistPropertyBag , IPropertyBag
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.
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.
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IHlink Methods | Description |
SetHlinkSite | Saves the interface pointer on the site object. |
GetHlinkSite | Retrieves the interface pointer on the site object. |
GetMonikerReference | Retrieves the moniker and location portions of the target. |
GetStringReference | Retrieves the name and location portions of the target. |
GetFriendlyName | Retrieves the friendly name of the target. |
SetFriendlyName | Sets the friendly name of the target. |
GetTargetFrameName | Retrieves the name of the target frame. |
SetTargetFrameName | Sets the name of the target frame. |
GetAdditionalParams | Retrieves additional hyperlink parameters. |
SetAdditionalParams | Sets additional hyperlink parameters. |
Navigate | Navigates to the given target. |
GetMiscStatus | Queries if hyperlink is absolute or relative. |
See Also
HlinkSimpleNavigateToMoniker , HlinkSimpleNavigateToString , HlinkNavigateToStringReference
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::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
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::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
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
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
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::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
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::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::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::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
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.
The system provides a default implementation.
Methods in Vtable Order
IUnknown Methods | Description |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IHlinkBrowseContext Methods | Description |
Register | Registers an object with the browse context. |
GetObject | Retrieves an object previously registered in the browse context under the given name. |
Revoke | Revokes an object previously registered with this browse context. |
SetBrowseWindowInfo | Establishes the browse window info structure of this browse context. |
GetBrowseWindowInfo | Retrieves the browse window info structure associated with this browse context. |
EnumNavigationStack | Retrieves an enumerator which can be used to enumerate the current contents of the navigation stack. |
QueryHlink | Tests the validity of a hyperlink ID value. |
GetHlink | Retrieves a hyperlink from this browse context. |
SetCurrentHlink | Sets the current hyperlink in this browse context's navigation stack. |
OnNavigateHlink | Notifies a browse context that a hyperlink has been navigated. |
Clone | Duplicates a browse context. |
Close | Closes the hyperlink browse context. |
See Also
HlinkCreateBrowseContext , IHlink , IHlinkFrame , IHlinkTarget
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.
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::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
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
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
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::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
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
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
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::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
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
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IHlinkFrame Methods | Description |
GetBrowseContext | Retrieves the browse context of the hyperlink frame |
Navigate | Navigates to the target hyperlink |
OnNavigate | Notifies the hyperlink frame of a hyperlink navigation |
SetBrowseContext | Sets the browse context of the hyperlink frame |
See Also
HlinkNavigate , HlinkNavigateToStringReference , HlinkSimpleNavigateToString , HlinkSimpleNavigateToMoniker , IHlink
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
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
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
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
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IHlinkSite Methods | Description |
GetMoniker | Retrieves the moniker to the hyperlink target. |
GetInterface | Retrieves the interface to the hyperlink target. |
OnNavigationComplete | Notifies the hyperlink site that hyperlink navigation is complete. |
See Also
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 [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
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
IHlinkTarget [Beta]
A hyperlink target implements the IHlinkTarget interface and gives out hyperlink references to its contents.
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.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IHlinkTarget Methods | Description |
SetBrowseContext | Establishes the current browse context for this hyperlink target. |
GetBrowseContext | Retrieves the current browse context within which this hyperlink target is currently running. |
Navigate | If the given location is not visible, navigates to and shows that position within the target. |
GetMoniker | Returns a moniker to the hyperlink target object. |
GetFriendlyName | Returns a friendly name for the given hyperlink location within this target. |
See Also
HlinkNavigate , HlinkSimpleNavigateToMoniker , HlinkSimpleNavigateToString , IHlink , IHlinkBrowseContext
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
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
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
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
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
IHttpNegotiate [Beta]
The single method of IHttpNegotiate provides basic authentication information from a bind client.
Only custom protocol writers need to implement this interface.
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 |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements the reference count. |
IHttpNegotiate Methods | Description |
BeginningTransaction | Notifies a client of a URL being bound to at the beginning of the HTTP transaction. |
OnHeadersAvailable | Provides the client with the HTTP response header information. |
OnError | Allows the client to add HTTP headers that are used to respond to the error. |
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
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
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
IInternetExplorer [Beta]
The IInternetExplorer interface TBD
Methods in Vtable Order
IUnknown Methods | Description |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments reference count. |
Release | Decrements reference count. |
IDispatch Methods | Description |
GetIDsOfNames | Returns the number of type descriptions for object |
GetTypeInfo | Retrieves a description of objects programmable interface |
GetTypeInfoCount | Maps name of method or property to DISPID |
Invoke | Calls 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 |
Close | TBD |
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 |
IInternetExplorer::Close [Beta]
TBD
HRESULT IInternetExplorer::Close(
TBD | // TBD |
); |
Return Values
TBD
IInternetExplorer::get_Application [Beta]
Returns a pointer to this OC.
HRESULT IInternetExplorer::get_Application(
IDispatch ** ppDisp | // TBD |
); |
Parameters
ppDisp
[out] TBD
Return Values
TBD
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
IInternetExplorer::get_Container [Beta]
Returns a pointer to the container.
HRESULT IInternetExplorer::get_Container(
IDispatch ** ppDisp | // TBD |
); |
Parameters
ppDisp
[out] TBD
Return Values
TBD
IInternetExplorer::get_Document [Beta]
Returns the active Document.
HRESULT IInternetExplorer::get_Document(
IDispatch ** ppDisp | // TBD |
); |
Parameters
ppDisp
[out] TBD
Return Values
TBD
IInternetExplorer::get_FileName [Beta]
Returns the file name.
HRESULT IInternetExplorer::get_FileName(
BSTR * pbstrFileName | // TBD |
); |
Parameters
pbstrFileName
[out] TBD
Return Values
TBD
IInternetExplorer::get_FullName [Beta]
Returns the full path name.
HRESULT IInternetExplorer::get_FullName(
BSTR * pbstrFullName | // TBD |
); |
Parameters
pbstrFullName
[out] TBD
Return Values
TBD
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
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
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
IInternetExplorer::get_Name [Beta]
Returns name of the application.
HRESULT IInternetExplorer::get_Name(
BSTR * pbstrName | // TBD |
); |
Parameters
pbstrName
[out] TBD
Return Values
TBD
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
IInternetExplorer::get_StatusBar [Beta]
Returns the statusbar value.
HRESULT IInternetExplorer::get_StatusBar(
boolean * pbool | // TBD |
); |
Parameters
pbool
[out] TBD
Return Values
TBD
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
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
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
IInternetExplorer::get_TopLevelContainer [Beta]
TBD
HRESULT IInternetExplorer::get_TopLevelContainer(
boolean * pBool | // TBD |
); |
Parameters
pBool
[out] TBD
Return Values
TBD
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
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
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
IInternetExplorer::GoBack [Beta]
Navigates to the previous item in the history list.
HRESULT IInternetExplorer::GoBack(
); |
Return Values
TBD
IInternetExplorer::GoForward [Beta]
Navigates to the next item in the history list.
HRESULT IInternetExplorer::GoForward(
); |
Return Values
TBD
IInternetExplorer::GoHome [Beta]
Navigates to the home/start page.
HRESULT IInternetExplorer::GoHome(
); |
Return Values
TBD
IInternetExplorer::GoSearch [Beta]
Navigates to the Search Page.
HRESULT IInternetExplorer::GoSearch(
); |
Return Values
TBD
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
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
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
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
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
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
IInternetExplorer::put_Location [Beta]
Sets location in namespace to view.
HRESULT IInternetExplorer::put_Location(
BSTR bstrLocation | // TBD |
); |
Parameters
bstrLocation
[in] TBD
Return Values
TBD
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
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
IInternetExplorer::put_ToolBar [Beta]
Turns the toolbar on or off.
HRESULT IInternetExplorer::put_ToolBar(
boolean bValue | // TBD |
); |
Parameters
bValue
[in] TBD
Return Values
TBD
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
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
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
IInternetExplorer::Refresh [Beta]
Refreshes the current file.
HRESULT IInternetExplorer::Refresh(
); |
Return Values
TBD
IInternetExplorer::Stop [Beta]
Stops opening a file.
HRESULT IInternetExplorer::Stop(
); |
Return Values
TBD
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.
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\
· 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
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
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(
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
.
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(
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
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
IOleCommandTarget::Exec [Beta]
Executes a specified command or displays help for
a command.
HRESULT Exec(
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.
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.
A command target must implement this function; therefore
E_NOTIMPL is not a valid return value.
See Also
IOleCommandTarget::QueryStatus [Beta]
Queries the object for the status of one or more
commands generated by user interface events.
[input_sync] HRESULT QueryStatus(
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.
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.
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
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.
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
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
See Also
IOleCommandTarget
, IOleContinueCallback,
IOleDocumentView , IOleDocumentSite
, IPrint
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(
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
.
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.
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
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(
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.
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
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(
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.
S_OK
The status bits were returned successfully
E_POINTER
The address in pdwStatus is NULL.
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.
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
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 .
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.
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
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(
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.
IOleClientSite, IOleDocument::CreateView , IOleDocumentView::SetInPlaceSite
, IOleInPlaceSite, IOleObject::DoVerb
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.
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.
A container calls the methods of this interface to
activate, deactivate, close, and generally communicate with a
document view object.
Methods in VTable Order
See Also
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(
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.
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
IOleDocumentView::Clone [Beta]
Creates a duplicate view object with an identical
internal state to the current view.
HRESULT Clone(
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.
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
IOleDocumentView::Close [Beta]
Asks a document view to close and release its IOleInPlaceSite
pointer.
HRESULT Close(
Return Values
S_OK
The view successfully closed itself.
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
IOleDocumentView::GetDocument [Beta]
Returns the IUnknown interface pointer
of the document object that owns this view.
HRESULT GetDocument(
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
IOleDocumentView::GetInPlaceSite [Beta]
Retrieves the most recent view site associated with
this view of the document.
HRESULT GetInPlaceSite(
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.
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.
A document view must implement this method completely.
Therefore E_NOTIMPL is not an acceptable return value.
See Also
IOleDocumentView::SetInPlaceSite
, IOleInPlaceSite
IOleDocumentView::GetRect [Beta]
Returns the rectangular coordinates of the view port
in which the view is to be activated.
HRESULT GetRect(
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
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.
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.
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
IOleDocumentView::SaveViewState [Beta]
Saves the view's state into the specified stream.
HRESULT SaveViewState(
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.
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
IOleDocumentView::SetInPlaceSite [Beta]
Associates a container's document view site with
a document's document view object.
HRESULT SetInPlaceSite(
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.
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.
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.
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
IOleDocumentView::SetRect [Beta]
Sets the rectangular coordinates of the view port
in which a view is to be activated.
[input_sync] HRESULT SetRect(
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.
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.
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.
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
IOleDocumentView::SetRectComplex [Beta]
Sets the rectangular coordinates of the view port,
horizontal and vertical scroll bars, and the size box.
[input_sync] HRESULT SetRectComplex(
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
IOleDocumentView::Show [Beta]
Instructs a view to in-place activate or in-place
deactivate itself.
HRESULT Show(
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
.
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.
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
).
Implementations of this method should embody the
following pseudo-code:
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
IOleDocumentView::UIActivate [Beta]
Activates or deactivates a document view's user-interface
elements, such as menus, toolbars, and accelerators.
HRESULT UIActivate(
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
.
Calling this method is part of the normal activation
and deactivation sequences of a document object.
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).
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
IOleScript [Beta]
The scripting engine must implement this interface
in order to be an OLE Scripting engine.
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(
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
IOleScript::AddTypeLib [Beta]
Adds a type library to the namespace for the script.
HRESULT IOleScript::AddTypeLib(
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
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(
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
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
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
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(
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
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(
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
IOleScript::GetScriptMacroObject [Beta]
Returns the IDispatch for methods/properties
associated with the running script itself.
HRESULT IOleScript::GetScriptMacroObject(
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
IOleScript::GetScriptSite [Beta]
Retrieves the site object associated with the OLE
Scripting engine.
HRESULT IOleScript::GetScriptSite(
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
IOleScript::GetScriptState [Beta]
Returns the current state of the scripting engine.
HRESULT IOleScript::GetScriptState(
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
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(
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
IOleScript::GetScriptThreadState [Beta]
Returns the current state of a script thread.
HRESULT IOleScript::GetScriptThreadState(
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
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(
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
IOleScript::RemoveItem [Beta]
Removes an item previously added with AddNamedItem.
HRESULT IOleScript::RemoveItem(
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::RemoveTypeLib [Beta]
Removes a type library previously added with AddTypeLib .
HRESULT IOleScript::RemoveTypeLib(
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::RenameItem [Beta]
Notifies the scripting engine that a specific item
has changed names.
HRESULT IOleScript::RenameItem(
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::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
IOleScript::SetScriptSite [Beta]
Informs scripting engine of its IOleScriptSite
site provided by the host.
HRESULT IOleScript::SetScriptSite(
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
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
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.
IOleScriptParse::AddScriptText [Beta]
Adds a code "sniplet" to the script.
HRESULT IOleScriptParse::AddScriptText(
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
IOleScriptParse::EvaluateScriptText [Beta]
Evaluates a code "sniplet" immediately.
HRESULT IOleScriptParse::EvaluateScriptText(
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
IOleScriptParse::RemoveScriptText [Beta]
Removes a code "sniplet" previously added
with AddScriptText.
HRESULT IOleScriptParse::RemoveScriptText(
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
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.
IOleScriptSite::GetComponentManager [Beta]
Returns the IMsoComponentManager for the containing
processes (usually, the host's message loop).
HRESULT IOleScript::GetComponentManager(
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
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(
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
IOleScriptSite::GetItemInfo [Beta]
Allows the scripting engine to obtain information
about an item added with IOleScript::AddNamedItem
.
HRESULT IOleScript::GetItemInfo(
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
IOleScriptSite::GetLCID [Beta]
Retrieves the Language ID associated with the script
site.
HRESULT IOleScript::GetLCID(
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
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(
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
IOleScriptSite::OnExecutionError [Beta]
This method is called when an execution error occurs
while running the script.
HRESULT IOleScriptSite::OnExecutionError(
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
IOleScriptSite::OnScriptTerminate [Beta]
Informs the host that the script has completed execution.
HRESULT IOleScript::OnScriptTerminate(
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 [Beta]
Informs the host that the scripting engine has changed
states.
HRESULT IOleScript::OnStateChange(
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
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
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
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
IPersistMemory::GetSizeMax [Beta]
Returns the size in bytes of the memory block needed
to save the object.
HRESULT GetSizeMax(
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.
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::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.
If the object has already been initialized with Load,
then this method must return E_UNEXPECTED.
See Also
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.
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::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(
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::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(
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
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.
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.
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
IPersistMoniker::GetCurMoniker [Beta]
Retrieves the moniker that refers to the object's
persistent state.
HRESULT GetCurMoniker(
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
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::Load [Beta]
Loads the object indicated by a supplied moniker.
HRESULT Load(
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
IPersistMoniker::Save [Beta]
Requests that the object save itself into the location
referred to by pmkDst.
HRESULT Save(
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
IPersistMoniker::SaveCompleted [Beta]
Notifies the object that it has been completely saved.
HRESULT SaveCompleted(
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
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
See Also
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 [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(
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::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(
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
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.
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
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:
Callers determine whether a particular object class
supports programmatic printing of its persistent state by looking
in the registry for the "Printable" key.
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.
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
IPrint::GetPageInfo [Beta]
Retrieves the number of a document's first page as
well as the total number of pages.
HRESULT GetPageInfo(
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.
IPrint::Print [Beta]
Prints an object on the specified printer, using
the specified job requirements.
HRESULT Print(
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
IPrint::SetInitialPageNum [Beta]
Attempts to set the number of the first page of a
document.
HRESULT SetInitialPageNum(
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.
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
See Also
IErrorLog
, IPersistPropertyBag
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(
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 [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(
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
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
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(
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
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
See Also
GUIDKIND
, IProvideClassInfo2::GetGUID
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(
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.
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(
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.
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(
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_
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:
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.
IShellExplorer [Beta]
The IShellExplorer interface TBD
Methods in Vtable Order
IShellExplorer::Browse [Beta]
Browse for a new folder to view.
HRESULT IShellExplorer::Browse(
Return Values
TBD
IShellExplorer::Close [Beta]
TBD
HRESULT IShellExplorer::Close(
Return Values
TBD
IShellExplorer::get_Application [Beta]
TBD
HRESULT IShellExplorer::get_Application(
Parameters
ppDisp
[out] TBD
Return Values
TBD
IShellExplorer::get_AutoSize [Beta]
Returns auto-size mode.
HRESULT IShellExplorer::get_AutoSize(
Parameters
pfAutoSize
[out] TBD
Return Values
TBD
IShellExplorer::get_BorderVisible [Beta]
Returns border-visible flag.
HRESULT IShellExplorer::get_BorderVisible(
Parameters
pfBorderVisible
[out] TBD
Return Values
TBD
IShellExplorer::get_Busy [Beta]
Query to see if something is still in progress.
HRESULT IShellExplorer::get_Busy(
Parameters
pBool
[out] TBD
Return Values
TBD
IShellExplorer::get_Container [Beta]
Returns a pointer to the container.
HRESULT IShellExplorer::get_Container(
Parameters
ppDisp
[out] TBD
Return Values
TBD
IShellExplorer::get_Document [Beta]
Returns the active Document.
HRESULT IShellExplorer::get_Document(
Parameters
ppDisp
[out] TBD
Return Values
TBD
IShellExplorer::get_FolderFlags [Beta]
Returns FWF_ folder flags.
HRESULT IShellExplorer::get_FolderFlags(
Parameters
pfFlags
[out] TBD
Return Values
TBD
IShellExplorer::get_FolderViewMode [Beta]
Returns FVM_ folder view mode.
HRESULT IShellExplorer::get_FolderViewMode(
Parameters
pnViewMode
[out] TBD
Return Values
TBD
IShellExplorer::get_Height [Beta]
The vertical dimension (pixels) of the frame window.
HRESULT IShellExplorer::get_Height(
Parameters
plHeight
[out] TBD
Return Values
TBD
IShellExplorer::get_Location [Beta]
Returns location in namespace to view.
HRESULT IShellExplorer::get_Location(
Parameters
pbstrLocation
[out] TBD
Return Values
TBD
IShellExplorer::get_Parent [Beta]
Returns a pointer to the parent Object.
HRESULT IShellExplorer::get_Parent(
Parameters
ppDisp
[out] TBD
Return Values
TBD
IShellExplorer::get_TopLevelContainer [Beta]
TBD
HRESULT IShellExplorer::get_TopLevelContainer(
Parameters
pBool
[out] TBD
Return Values
TBD
IShellExplorer::get_Type [Beta]
Returns the type of the contained object.
HRESULT IShellExplorer::get_Type(
Parameters
pbstrType
[out] TBD
Return Values
TBD
IShellExplorer::get_Value [Beta]
Returns the friendly name of the Location
HRESULT IShellExplorer::get_Value(
Parameters
pbstrLocation
[out] TBD
Return Values
TBD
IShellExplorer::get_Visible [Beta]
Determines whether this OC is visible or hidden.
HRESULT IShellExplorer::get_Visible(
Parameters
pBool
[out] TBD
Return Values
TBD
IShellExplorer::get_Width [Beta]
The horizontal dimension (pixels) of the frame window
HRESULT IShellExplorer::get_Width(
Parameters
plWidth
[out] TBD
Return Values
TBD
IShellExplorer::GoBack [Beta]
Navigates to the previous item in the history list.
HRESULT IShellExplorer::GoBack(
Return Values
TBD
IShellExplorer::GoForward [Beta]
Navigates to the next item in the history list.
HRESULT IShellExplorer::GoForward(
);
Return Values
TBD
IShellExplorer::GoHome [Beta]
Go to home/start page.
HRESULT IShellExplorer::GoHome(
);
Return Values
TBD
IShellExplorer::GoSearch [Beta]
Go Search Page.
HRESULT IShellExplorer::GoSearch(
);
Return Values
TBD
IShellExplorer::Navigate [Beta]
Navigates to a hyperlink.
HRESULT IShellExplorer::Navigate(
Parameters
Hlink
[in] TBD
OpenInNewWindow
[in] TBD
NoHistory
[in] TBD
Return Values
TBD
IShellExplorer::Open [Beta]
Opens a file.
HRESULT IShellExplorer::Open(
Parameters
Target
[in] TBD
Location
[in] TBD
NoHistory
[in] TBD
Return Values
TBD
IShellExplorer::PrintOut [Beta]
Prints the current document.
HRESULT IShellExplorer::PrintOut(
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
IShellExplorer::put_AutoSize [Beta]
Sets auto-size mode.
HRESULT IShellExplorer::put_AutoSize(
Parameters
fAutoSize
[in] TBD
Return Values
TBD
IShellExplorer::put_BorderVisible [Beta]
Sets border-visible flag.
HRESULT IShellExplorer::put_BorderVisible(
Parameters
fBorderVisible
[in] TBD
Return Values
TBD
IShellExplorer::put_FolderFlags [Beta]
Sets FWF_ folder flags.
HRESULT IShellExplorer::put_FolderFlags(
Parameters
fFlags
[in] TBD
Return Values
TBD
IShellExplorer::put_FolderViewMode [Beta]
Sets FVM_ folder view mode.
HRESULT IShellExplorer::put_FolderViewMode(
Parameters
nViewMode
[out] TBD
Return Values
TBD
IShellExplorer::put_Height [Beta]
Sets the vertical dimension (pixels) of the frame window.
HRESULT IShellExplorer::put_Height(
Parameters
lHeight
[in] TBD
Return Values
TBD
IShellExplorer::put_Location [Beta]
Sets location in namespace to view.
HRESULT IShellExplorer::put_Location(
Parameters
bstrLocation
[in] TBD
Return Values
TBD
IShellExplorer::put_Visible [Beta]
Sets whether this OC is visible or hidden.
HRESULT IShellExplorer::put_Visible(
Parameters
bValue
[in] TBD
Return Values
TBD
IShellExplorer::put_Width [Beta]
Sets the horizontal dimension (pixels) of the frame window
HRESULT IShellExplorer::put_Width(
Parameters
lWidth
[in] TBD
Return Values
TBD
IShellExplorer::Quit [Beta]
Exits Shell Explorer and closes the open window.
HRESULT IShellExplorer::Quit(
Return Values
TBD
IShellExplorer::Refresh [Beta]
Refreshes the current file.
HRESULT IShellExplorer::Refresh(
);
Return Values
TBD
IShellExplorer::Stop [Beta]
Stops opening a file.
HRESULT IShellExplorer::Stop(
);
Return Values
TBD
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.
Only custom protocol component writers need to implement
this interface.
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
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(
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
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.
Only custom protocol component writers need to implement
this interface.
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
IWinSockInfo::GetSocket [Beta]
Retrieves the socket handle.
HRESULT GetSocket(
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
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IObjectWithSite Methods
Description SetSite Provides the site's IUnknown pointer to the object being managed.
GetSite Retrieves the last site set with IObjectWithSite::SetSite.
REFIID riid,
// IID of interface pointer being requested
void ** ppvSite // Receives an indirect pointer to caller's void
);
IUnknown * pUnkSite
// Pointer to IUnknown of the site managing this object
);
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces
AddRef Increments reference count
Release Decrements reference count
IOleCommandTarget Methods
Description QueryStatus
Queries object for status of commands
Exec
Execute a command
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
);
Notes to Callers
Notes to Implementers
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
);
Notes to Callers
Notes to Implementers
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements 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.
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
);
Notes to Callers
Notes to Implementers
IEnumOleDocumentViews ** ppEnum
// On return, pointer to interface pointer to an enumerator
IOleDocumentView ** ppView
// On return, pointer to interface pointer to a single view
);
Comments
DWORD *pdwStatus
// Pointer to information about the document object
); Parameters
Return Values
Comments
Notes to Implementers
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IOleDocumentSite Methods
Description ActivateMe
Activates an OLE Document Object
IOleDocumentView * pViewToActivate
// Pointer to the view to be activated
);
See Also
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements 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.
IStream *pstm
// Pointer to stream );
Comments
IOleInPlaceSite *pIPSiteNew
// Pointer to view site IOleDocumentView **ppViewNew
// On return, pointer to interface pointer to view object
);
Comments
DWORD dwReserved
// Reserved. Must be zero );
Comments
IUnknown **ppunk
// On return, pointer to the IUnknown pointer of the document object that owns this view
);
IOleInPlaceSite **ppIPSite
// On return, Indirect pointer to the document's view site
);
Notes to Callers
Notes to Implementers
LPRECT prcView
// Pointer to the current view coordinates
);
Notes to Callers
Notes to Implementers
IStream *pstm
// Pointer to stream );
Comments
IOleInPlaceSite * pIPSite
// Pointer to document view site's IOleInPlaceSite interface
);
Comments
Notes to Callers
Notes to Implementers
LPRECT prcView
// Pointer to a RECT structure );
Comments
Notes to Callers
Notes to Implementers
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
);
BOOL fShow
// Boolean value specifying whether to activate or deactivate the view
);
Comments
Notes to Callers
Notes to Implementers
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
}
BOOL fUIActivate
// Boolean value specifying whether to activate or deactivate view
);
Comments
Notes to Callers
Notes to Implementers
LPCOLESTR pstrName,
// Item name as viewed from script DWORD dwFlags // Item flags
);
REFGUID rguidTypeLib,
// Type library GUID DWORD dwMajor, // Major version number
DWORD dwMinor, // Minor version number
DWORD dwFlags // Option flags
);
IOleScript **ppscript
// Returned, unsited cloned scripting engine
);
SCRIPTTHREADID *pstidThread
// Returned script thread ID );
IDispatch **ppdisp
// Returned object );
LPCOLESTR pstrItemName,
// TBD IDispatch **ppdisp // Returned object
);
REFIID iid,
// Interface IID void **ppvSiteObject // Returned interface pointer
);
SCRIPTSTATE *pssState
// Script state );
DWORD dwWin32ThreadID,
// Thread ID SCRIPTTHREADID *pstidThread
// Returned script thread ID );
SCRIPTTHREADID stidThread,
// ID of desired thread SCRIPTTHREADSTATE *pstsState
// Sate of dersired thread );
SCRIPTTHREADID stidThread,
// ID of thread to interrupt const EXCEPINFO *pexcepinfo
// Error information DWORD dwflags // Option flags
);
LPCOLESTR pstrname
// Item name from AddNamedItem
);
REFGUID rguidTypeLib
// Type library GUID );
LPCOLESTR pstrNameOld,
// Previous item name LPCOLESTR pstrNewName
// New item name );
IOleScriptSite *pioss
// Host supplied script site );
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
);
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
);
LPCOLESTR pstrName
// Name of sniplet as returned from AddScriptText
);
IComponentManager **ppicm
// Returned component manager interface
);
BSTR *pszVersion
// Document version string );
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 );
LCID *plcid
// Returned language ID );
HWND *phwnd)
// Returned HWND of controlling window
);
EXCEPINFO *pexcepinfo
// Exception information associated with error condition
);
const VARIANT *pvarResult,
// Pointer to script results const EXCEPINFO *pexcepinfo
// Pointer to structure for exception information
);
SCRIPTSTATE ssScriptState
// The new script state );
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IPersist Method
Description GetClassID Returns 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.
ULARGE_INTEGER *pcbSize
// Pointer to size of memory needed to save object
);
Notes to Implementors
Notes to Implementers
Notes to Callers
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
);
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
);
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IPersist Method
Description GetClassID Returns 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.
IMoniker ** ppmkCur
// Location to return the moniker to the object's current persistent state.
);
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
);
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
);
IMoniker * pmkNew
// The moniker to the object's new persistent state
);
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IPersist Method
Description GetClassID Returns 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.
IPropertyBag *pPropBag,
// Points to caller's property bag
IErrorLog *pErrorLog
// Points to error log );
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
);
When to Use
HKEY_CLASSES_ROOT\CLSID\{...}\Printable
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces
AddRef Increments reference count
Release Decrements 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
LONG *nFirstPage
// Pointer to number of first page LONG *pcPages // Pointer to total number of pages
);
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
);
LONG nFirstPage
// Number of first page );
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements 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.
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 );
LPCOLESTR pszPropName,
// Points to the property to be written
VARIANT * pVar // Points to the VARIANT containing the property value and type
);
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IProvideClassInfo Method
Description GetClassInfo Returns 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.
DWORD dwGuidKind,
// Specifies the desired GUID
GUID *pGUID // Receives a pointer to the desired GUID
);
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IProvideClassInfo Method
Description GetClassInfo Returns 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 GetGUIDDwordArrays 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.
GetClassInfoLocale Returns an LCID locale identifier for the specified type.
GetFlags Returns a DWORD containing up to 32 mutually-inclusive (generally) bit flags that are all related to the flag group identified by guidGroup.
ITypeInfo **ppTypeInfo,
// Receives an indirect pointer to the ITypeInfo interface
LCID lcid // Specifies the locale identifier
);
REFGUID guidGroup,
// Specifies the flag group requested by the caller
DWORD *pdwFlags // Receives a pointer to the flag values
);
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
);
typedef struct tagCAUUID
{
ULONG cElems;
GUID *pElems;
} CAUUID;
typedef struct tagCADWORD
{
ULONG cElems;
DWORD *pElems;
} CADWORD;
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.
IDispatch Methods
Description GetIDsOfNames Returns the number of type descriptions for object
GetTypeInfo Retrieves a description of objects programmable interface
GetTypeInfoCount Maps name of method or property to DISPID
Invoke Calls 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
);
TBD // TBD
);
IDispatch ** ppDisp
// TBD );
boolean * pfAutoSize
// TBD );
boolean * pfBorderVisible
// TBD );
boolean * pBool
// TBD );
IDispatch ** ppDisp
// TBD );
IDispatch ** ppDisp
// TBD );
int * pfFlags
// TBD );
int * pnViewMode
// TBD );
long * plHeight
// TBD );
BSTR * pbstrLocation
// TBD );
IDispatch ** ppDisp
// TBD );
Boolean * pBool
// TBD );
BSTR * pbstrType
// TBD );
BSTR * pbstrLocation
// TBD );
Boolean * pBool
// TBD );
long * plWidth
// TBD );
);
DHyperlink * Hlink
// TBD VARIANT * OpenInNewWindow
// TBD VARIANT * NoHistory // TBD
);
BSTR Target
// TBD VARIANT * Location // TBD
VARIANT * NoHistory // TBD
);
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
);
boolean fAutoSize
// TBD );
boolean fBorderVisible
// TBD );
int fFlags
// TBD );
int nViewMode
// TBD );
long lHeight
// TBD );
BSTR bstrLocation
// TBD );
Boolean bValue
// TBD );
long lWidth
// TBD );
);
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IWinINetInfo Methods
Description GetConnectionHandle
Retrieves the WinInet HINTERNET handle of the transport.
HINTERNET phinternet
// The location in which to return the HINTERNET of the current binding
);
When to Implement
When to Use
IUnknown Methods
Description QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IWinSockInfo Methods
Description GetSocket
Retrieves the socket handle.
SOCKET * psocket
// Location to return the SOCKET of the current binding.
);