AsyncBindToObject [Beta]
Uses the asynchronous moniker to bind to the object it identifies. The binding process involves finding the object, putting it into the running state if necessary, and supplying the caller with a pointer to a specified interface on the identified object.
HRESULT AsyncBindToObject(
IMoniker * pmk | //Points to the moniker to bind to |
IBindCtx * pbc | //Bind context object to be used |
IMoniker * pmkLeft | //Moniker that precedes this one in the composite |
REFIID riid | //IID of interface pointer requested |
void ** ppv | //Indirect pointer to the requested interface |
); |
Parameters
pmk
[in] IMoniker pointer to the moniker to bind to. May not be NULL.
pbc
[in] IBindCtx pointer to the bind context to bind with. This is typically the one created by a previous call to CreateAsyncBindCtx .
pmkLeft
[in] If this moniker is part of a composite, this is an IMoniker pointer to the moniker to the left of this one in the composite. This parameter is primarily used by moniker implementors to enable cooperation between the various components of a composite moniker. Moniker clients can usually pass NULL.
riid
[in] Interface ID (IID) that identifies the interface for which a pointer is requested on the object.
ppv
[out] On return, points to the location for the pointer
to the interface requested in riid.
Return Values
S_OK
Success.
MK_S_ASYNCHRONOUS
If the caller's registered IBindStatusCallback::GetBindInfo specified BINDF_ASYNCHRONOUS, ppv will be set to NULL and the object will be returned in the BSCF_LASTDATANOTIFICATION call to IBindStatusCallback::OnObjectAvailable .
E_INVALIDARG
One or more arguments are invalid.
Remarks
Binds to pmk for its object and associates the asynchronous bind information in pbc with this bind. This function is simply a helper which encapsulates the common following sequence of calls:
pbc->RegisterObjectParam(SZ_ASYNC_CALLEE, pmk);
pmk->BindToObject(pbc, pmkLeft, riid, ppv);
pbc->RevokeObjectParam(SZ_ASYNC_CALLEE);
See Also
AsyncBindToStorage [Beta]
Binds to the specified moniker for its storage.
HRESULT AsyncBindToStorage(
IMoniker * pmk | //Points to the moniker to bind to |
IBindCtx * pbc | //Points to the bind context |
IMoniker * pmkLeft | //If this moniker is part of a composite, points to the moniker to the left |
REFIID riid | //IID of the requested storage interface |
void ** ppv | //Indirect pointer to the requested interface |
); |
Parameters
pmk
[in] IMoniker pointer to the moniker to bind to.
pbc
[in] IBindCtx pointer to the bind context to bind with. This is typically the one created by a previous call to CreateAsyncBindCtx .
pmkLeft
[in] If this moniker is part of a composite, this is an IMoniker pointer to the moniker to the left of this one in the composite. This parameter is primarily used by moniker implementors to enable cooperation between the various components of a composite moniker. Moniker clients can usually pass NULL.
riid
[in] Interface ID (IID) that identifies the storage interface for which a pointer is desired on the object associated with the moniker. This is typically IID_IStream or IID_IStorage. Sometimes IID_ILockBytes is convenient.
ppv
[out] On return, points to the location for the pointer
to the interface requested in riid.
Return Values
S_OK
Success.
MK_S_ASYNCHRONOUS
If the caller's registered IBindStatusCallback::GetBindInfo specified BINDF_ASYNCHRONOUS, ppv will be set to NULL and the object will be returned in a later call or calls to IBindStatusCallback::OnDataAvailable .
E_INVALIDARG
One or more arguments are invalid.
Remarks
Binds to pmk for its storage and associates the asynchronous bind information in pbc with this bind. This function is simply a helper which encapsulates the common following sequence of calls:
pbc->RegisterObjectParam(SZ_ASYNC_CALLEE, pmk);
pmk->BindToStorage(pbc, pmkLeft, riid, ppv);
pbc->RevokeObjectParam(SZ_ASYNC_CALLEE);
See Also
CommitUrlCacheEntry [Beta]
Caches data in the specified file in the cache storage and associates it with a specified URL.
BOOL CommitUrlCacheEntry (
LPCTSTR lpszUrlName | //Source name of the cache entry |
LPCTSTR lpszLocalFileName | //Name of the local file being cached |
FILETIME ExpiryTime | //Expire date and time (GMT) of the file being cached |
FILETIME LastModifiedTime | //Last modified date and time (GMT) of the file being cached |
DWORD CacheEntryType | //Type of the cache entry |
LPCBYTE lpHeaderInfo | //Pointer to the headerinfo data |
DWORD dwHeaderSize | //Size of the above header info |
LPCTSTR lpszFileExtension | //Points to the file extension |
DWORD dwReserved | //Reserved |
); |
Parameters
lpszUrlName
[in] Source name of the cache entry. This must be an unique name. The name string should not contain any escape character.
lpszLocalFileName
[in] Name of the local file that is being cached. The file will be moved to the cache storage if the storage is in the same volume of the local file otherwise the file is copied to the cache storage and then the local file is deleted. Typically this would be the same as is returned in the CreateUrlCacheEntry API, in which case the entry is marked as being committed.
ExpiryTime
[in] Expire date and time (GMT) of the file that is being cached. If it is unknown set it to zero.
LastModifiedTime
[in] Last modified date and time (GMT) of the file that is being cached. If it is unknown set it to zero.
CacheEntryType
[in] Type of the cache entry. This is a cache type bit mask. Values are taken from the following flags.
Flag | Value | Definition |
NORMAL_CACHE_ENTRY | 0x00000001 | Normal cache entry, may be deleted to recover space for new entries. |
STABLE_CACHE_ENTRY | 0x00000002 | stable cache entry such as graphic and audio/vedio files, may be deleted to recover space for the new entries only when there is no more NORMAL_CACHE_ENTRY. |
STICKY_CACHE_ENTRY | 0x00000004 | These entries will never be removed automatically by the cache management system. |
SPARSE_CACHE_ENTRY | 0x00010000 | indicate this cache entry is incomplete. |
OCX_CACHE_ENTRY | 0x00020000 | Special OCX type cache entry. |
lpHeaderInfo
[in] Pointer to the headerinfo data. If this is non-NULL, headerinfo is treated as extended attributes of the URL and is returned back in CACHE_ENTRY_INFO .
dwHeaderSize
[in] Size of the above header info. If lpHeaderInfo is non-NULL, this value is assumed to indicate the size of the headerinfo. Caller can maintain headers as part of the data and provide dwHeaderSize, together with a NULL value for lpHeaderInfo.
lpszFileExtension
[in] If not NULL, the cache system uses this extension to name the file in the local storage. It is recommended that the extension be kept less than three letters, for the sake of efficient handling of internal data.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
The CommitUrlCacheEntry function caches data in the specified file in the cache storage and associates it with the URL specified by lpszUrlName. If the storage is full then it invokes cache cleanup to make space for this new file. If the file size is bigger than the cache size, the API returns ERROR_DISK_FULL. If the cache entry already exists, the cache will overwrite it with this call. The user could specify SPARSE_CACHE_ENTRY in the Commit to indicate to himself that the size of the data is incomplete.
See Also
CreateAsyncBindCtx [Beta]
Creates an asynchronous bind context for use with asynchronous monikers.
HRESULT CreateAsyncBindCtx(
DWORD grfBSCOption | //BSCO_OPTION flags |
DWORD dwReserved | //Reserved. Must be 0 |
IBindStatusCallback * pbsc | //Pointer to callback |
IEnumFORMATETC* penumfmtetc | //Points to enumerator object for formats |
IBindCtx ** ppbc | //Location to return pointer to new bind context |
); |
Parameters
grfBSCOption
[in] Flags from the BSCO_OPTION enumeration, specifying which callback methods should be called.
dwReserved
[in] Reserved for future use. Must be zero.
pbsc
[in] IBindStatusCallback pointer to the callback used for receiving data availability and progress notification.
penumfmtetc
[in] IEnumFORMATETC pointer to object that can be used to enumerate formats to use for format negotiation during binding, if applicable. May be NULL, in which case the caller is not interested in format negotiation during binding and the default format of the object will be bound to.
ppbc
[out] On return, location for IBindCtx pointer
to the new bind-context.
Return Values
S_OK
Indicates success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
CreateAsyncBindCtx creates an asynchronous bind context for use with asynchronous monikers.
This function automatically registers the IBindStatusCallback and the IEnumFORMATETC interfaces with the bind context. The grfBSCOption parameter allows the client to specify flags that determine which callback methods the client is capable of receiving. If the client does not wish to receive certain notification, it can choose to implement those callback methods as empty function stubs (returning E_NOTIMPL), and they should not be called.
See Also
IBindStatusCallback , IEnumFORMATETC
CreateFormatEnumerator [Beta]
Creates an object that implements IEnumFORMATETC over a static array of cfmtetc FORMATETCs.
HRESULT CreateFormatEnumerator(
UINT cfmtetc | //The number of FORMATETCs in rgfmtetc |
CLIPFORMAT * rgfmtetc | //Static array of formats. |
IEnumFORMATETC ** ppenumfmtetc | //Indirect pointer enumerator object |
); |
Parameters
cfmtetc
[in] The number of FORMATETCs in rgfmtetc. May not be zero.
rgfmtetc
[in] Static array of formats.
ppenumfmtetc
[out] On return, points to the IEnumFORMATETC
interface pointer to the enumerator.
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
The CreateFormatEnumerator API function creates an object that implements IEnumFORMATETC over a static array of FORMATETC structures. The cfmtetc parameter specifies the number of these structures. With this pointer, you can call the standard enumeration methods to enumerate the structures, as described in the IEnumXXX reference.
See Also
IEnumXXX
CreateUrlCacheEntry [Beta]
Allocates requested cache storage and makes a local file name that will be used to save the cache entry corresponding to the source name.
BOOL CreateUrlCacheEntry(
LPCSTR lpszUrlName | //Points to the bind context from which the callback is to be revoked |
DWORD dwExpectedFileSize | //Points to the callback interface to revoke |
LPTSTR lpszFileName | //On return, contains the file name |
DWORD dwReserved | //Reserved |
); |
Parameters
lpszUrlName
[in] Name of the URL. The name string should not contain any escape character.
dwExpectedFileSize
[in] Expected size of the file needed to store the data corresponding to the source entity. If the expected size is unknown then set this value to zero.
lpszFileName
[out] Points to a buffer that, on return, contains a supplied file name. The buffer should be (MAX_PATH) large enough to store the file path name of the create file.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
The CreateUrlCacheEntry function allocates requested cache storage and make a local file name that will be used to save the cache entry corresponding to the source name. Internet services that use the cache should call this API to write directly into the cache storage. The caller should indicate the expected size of the file, but it is not guaranteed. Once the file is completely received, the caller should call CommitUrlCacheEntry to commit the entry in the cache.
See Also
CreateURLMoniker [Beta]
Creates a URL moniker from either a full URL string or from a base context URL moniker and a partial URL string.
HRESULT CreateURLMoniker(
IMoniker * pmkContext | //Points to the base context moniker |
LPWSTR szURL | //The display name to be parsed. |
IMoniker ** ppmk | //Location to return a moniker if successful. |
); |
Parameters
pmkContext
[in] The URL to use as the base context when szURL is a partial URL string. NULL when szURL is a full URL string or if this moniker will retrieve full URL context from its left or from the bind-context during IMoniker::BindToObject or IMoniker::BindToStorage.
szURL
[in] The display name to be parsed.
ppmk
On successful return, points to an IMoniker
pointer to the URL moniker.
Return Values
S_OK
Success - the format enumerator was removed..
MK_E_SYNTAX
A moniker could not be created because szURL
does not correspond to valid URL syntax for a full or partial
URL. This is uncommon, since most parsing of the URL occurs during
binding and also since the syntax for URLs is extremely flexible.
Remarks
Creates a URL moniker from either a full URL string or from a base context URL moniker and a partial URL string.
Partial URLs are similar to relative paths within file systems, in that resolution to an object requires context outside the partial string alone, whereas full URL strings are like fully-qualified paths - self-contained and often location-independent. When creating an URL moniker from a partial URL string, the caller may specify through pmkContext the URL moniker to draw context from when creating a full URL string from the partial URL string. In this case, CreateURLMoniker retrieves the display name of pmkContext (via IMoniker::GetDisplayName) and manually composes it with szURL according to URL composition rules. The caller may alternately create a moniker from a partial URL string without context (pmkContext set to NULL), in which case the resulting moniker will draw further context during binding (IMoniker::BindToObject and IMoniker::BindToStorage) by looking first in the passed IBindCtx for a contextual URL moniker object parameter by using the following call:
IBindCtx::GetObjectParam(SZ_URLCONTEXT, (IUnknown**)&pmkContext)
and next to its left for another URL Moniker from which to draw context.
See Also
IMoniker
DeleteUrlCacheEntry [Beta]
Removes the file associated with the source name from the cache, if it exists.
BOOL DeleteUrlCacheEntry (
LPCSTR lpszUrlName | //Name of the source corresponding to the cache entry. |
); |
Parameters
lpszUrlName
[in] Name of the source corresponding to the cache
entry.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value. If the entry corresponding to the
remote name is not in the cache GetLastError returns ERROR_FILE_NOT_FOUND.
If it is in use i.e. RetrieveUrlCacheEntry has been called
on it, then the call fails with ERROR_ACCESS_DENIED.
See Also
TBD
FindCloseUrlCache [Beta]
Closes the specified enumeration handle
BOOL FindCloseUrlCache (
HANDLE hEnumHandle | //Handle supplied by FindFirstUrlCacheEntry |
); |
Parameters
hEnumHandle
[in] Handle obtained through a call to FindFirstUrlCacheEntry
.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
After obtaining a handle to the enumerator through a call to FindFirstUrlCacheEntry , and completing the enumeration though calls to FindNextUrlCacheEntry , call FindCloseUrlCache to close the handle.
See Also
FindFirstUrlCacheEntry [Beta]
Begins the enumeration of the cache
HANDLE FindFirstUrlCacheEntry (
LPCSTR lpszUrlSearchPattern | //Source name pattern to search for |
LPCACHE_ENTRY_INFO lpFirstCacheEntryInfo | //Pointer to a buffer of the type CACHE_ENTRY_INFO |
LPDWORD lpdwFirstCacheEntryInfoBufferSize | //Size of the above buffer |
); |
Parameters
lpszUrlSearchPattern
[in] Source name pattern to search for. If NULL, *.* is assumed. (In this version we may implement only *.* semantics)..
lpFirstCacheEntryInfo
[out] Pointer to a buffer of the type CACHE_ENTRY_INFO.
lpdwFirstCacheEntryInfoBufferSize
[in,out] Pointer to a DWORD location that carries
the size of the above buffer. On return this location contains
the size of the data (in bytes) returned.
Return Values
handle
When successful, returns a valid handle (to be used to enumerate rest of the url entries).
INVALID_HANDLE_VALUE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
FindFirstUrlCacheEntry API begins the enumeration of the cache . The returned handle can be used in the FindNextUrlCacheEntry to get subsequent entries in the cache.
See Also
CACHE_ENTRY_INFO structure
FindNextUrlCacheEntry [Beta]
Retrieves the next entry in the cache.
BOOL FindNextUrlCacheEntry (
HANDLE hEnumHandle | //Enumeration handle obtained on FindFirstUrlCacheEntry call |
LPCACHE_ENTRY_INFO lpNextCacheEntryInfo | //Buffer to return the info about cache entry |
LPDWORD lpdwNextCacheEntryInfoBufferSize | //Size of the above buffer |
); |
Parameters
hEnumHandle
[in] Enumeration handle obtained on FindFirstUrlCacheEntry call.
lpNextCacheEntryInfo
[out] On successful return, points to the CACHE_ENTRY_INFO structure, containing information about cache entry.
lpdwNextCacheEntryInfoBufferSize
[in,out] Pointer to a DWORD location that carries
the size of the above buffer. On return this location contains
the size of the data (in bytes) returned.
Return Values
TRUE
Success, and the enumeration is not complete.
FALSE
Not successful;. and a call to GetLastError
returns the error code value. It will return ERROR_NO_MORE_FILES
when the enumeration is successful, but the enumeration is complete
Remarks
After calling FindFirstUrlCacheEntry to get the first cache entry, call FindNextUrlCacheEntry for each subsequent entry, until you get a return value of ERROR_NO_MORE_FILES, indicating that the enumeration is complete. Then call FindCloseUrlCache to close the enumeration handle.
See Also
FindFirstUrlCacheEntry , FindCloseUrlCache
FreeUrlCacheSpace [Beta]
Frees a percentage of the cache space.
BOOL FreeUrlCacheSpace (
LPCTSTR lpszCachePath | //Path from which to free up the cache space |
DWORD dwSize | //Amount of cache space to be freed |
DWORD dwSizeType | //Size type |
); |
Parameters
lpszCachePath
[in] Path from which to free up the cache space. If the path is a volume the cache will free up appropriate amount of space from the volume. If the parameter is NULL, the cache will make the decision about which cache path to use.
dwSize
[in] Amount of cache space to be freed.
dwSizeType
Size type, could be any of FCS_PERCENT_CACHE_SPACE,
FCS_PERCENT_DISK_SPACE, FCS_ABSOLUTE_SIZE
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
FreeUrlCacheSpace allows the caller to free a percentage of the cache space. This functionality is useful for managing the disk space.
See Also
TBD
GetClassURL [Beta]
Retrieves the CLSID associated with the specific resource.
HRESULT RevokeFormatEnumerator(
LPCWSTR szURL | //The display name to be parsed. |
CLSID * pclsid | //Points to the retrieved CLSID |
); |
Parameters
szURL
[in] The display name to be parsed.
pbsc
[in] On successful return, points to the CLSID associated
with the object indicated by the display name supplied in szURL.
Return Values
S_OK
Success.
MK_E_CANTOPENFILE
Indicates inability to attach to the specified resource.
Remarks
GetClassURL attempts to determine the CLSID of the resource using the following steps:
1. 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.
2. 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\
3. URL Moniker matches portions of arriving data
to patterns registered in the system registry under HKEY_CLASSES_ROOT\FileTypes.
4. Finally, 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.
See Also
GetClassFile
GetUrlCacheConfigInfo [Beta]
Retrieves the current cache configuration information.
BOOL GetUrlCacheConfigInfo
(
Parameters
lpCacheConfigInfo
[in] The buffer in which the cache info is to be
returned.
lpdwCacheInfoBufferSize
[in] Pointer to a DWORD location that carries the
size of the above buffer. On return this location contains the
size of the data (in bytes) returned.
dwFieldControl
[in] Bitmask that controls the fields to be returned
in the above buffer. See the Remarks for values
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
The cache management APIs provide controls to administrator
to manage the files that are cached on the client storage. The
management APIs are to be used only by a control panel applet
to configure the cache. GetUrlCacheConfigInfo API retrieves
the current cache configuration information. The dwFieldControl
parameter is a bitmask that specifies the fields to be retrieved.
The value consists of one or more of the following.
See Also
CACHE_CONFIG_INFO
structure
GetUrlCacheEntryInfo [Beta]
Retrieves the information of the specified cache
entry.
BOOL GetUrlCacheEntryInfo
(
Parameters
lpszUrlName
[in] Name of the cache entry. The name string should
not contain any escape character.
lpCacheEntryInfo
[in] Pointer to a CACHE_ENTRY_INFO
structure buffer.
lpdwCacheEntryInfoBufferSize
[in,out] Pointer to a DWORD location that carries
the size of the above buffer. On return this location contains
the size of the data (in bytes) returned.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value. This returns ERROR_FILE_NOT_FOUND
if the specified cache entry is not found in the cache.
Remarks
GetUrlCacheEntryInfo retrieves
the information of the specified cache entry.
See Also
CACHE_ENTRY_INFO
structure
HlinkCreateBrowseContext [Beta]
Creates an empty, default instance of the system
browse context object.
HRESULT HlinkCreateBrowseContext(
Parameters
punkOuter
[in] Pointer to the controlling IUnknown for
the new browse context. Typically NULL,
in which case the new browse context is not aggregated. This interface
must be derived from IUnknown.
riid
[in] Identifies the interface to return on the new
browse context. Typically IID_IHlinkBrowseContext, although it
must be IID_IUnknown when punkOuter is non-NULL
so that the aggregator can retrieve the new browse context's inner
IUnknown for future delegation of QueryInterface.
See the COM aggregation documentation for details.
ppv
[out] Location to return the riid interface.
Return Values
S_OK
The browse context was created and the interface
pointer retrieved.
Remarks
This helper API is identical to calling
See Also
IHlinkBrowseContext
, IHlinkFrame::GetBrowseContext
, IHlinkTarget::GetBrowseContext
HlinkCreateFromData [Beta]
Creates a standard hyperlink object from an OLE object
that supports the IDataObject interface. Typically, this
object originates from a data transfer operation, such as copy-paste
using the clipboard, or via drag-and-drop.
HRESULT HlinkCreateFromData(
Parameters
pdatobj
[in] Pointer to the IDataObject interface
pointer on the data object of interest. Used to access the methods
to retrieve the data from the object.
phlSite
[in] Pointer to the IHlinkSite
interface pointer for the new hyperlink within its container.
dwSiteData
[in] Additional site data associated with the hyperlink
site.
punkOuter
[in] Pointer to the controlling IUnknown interface
for the new hyperlink object. If NULL,
the new hyperlink object is not aggregated.
riid
[in] Identifies the interface to return on the new
hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter
is non-NULL.
ppv
[out] On return, pointer to the pointer to the requested
interface.
Return Values
S_OK
The new hyperlink object was created successfully.
E_NOINTERFACE
The object did not support the riid interface.
Remarks
HlinkCreateFromData is
one of three helper API's that you can use to create a hyperlink.
HlinkCreateFromData creates a hyperlink from an OLE object
which both supports the IDataObject interface and supports
a hyperlink format CF_HYPERLINK on that IDataObject interface.
HlinkQueryCreateFromData is typically called before the
call to HlinkCreateFromData to determine if both these
conditions are met. To create a hyperlink from an OLE object for
which you know the moniker, use HlinkCreateFromMoniker.
To create a hyperlink from an OLE object for which you have the
name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromData is
typically used by a hyperlink container as part of a user interface
that creates new hyperlinks via the clipboard or a drag-and-drop
operation.
See Also
HlinkCreateFromMoniker
, HlinkCreateFromString
, HlinkQueryCreateFromData
HlinkCreateFromMoniker [Beta]
Creates a new system hyperlink object from a moniker,
a location string, and a friendly name string (used for displaying
the hyperlink).
HlinkCreateFromMoniker(
Parameters
pmkTarget
[in] A pointer to the moniker to the hyperlink target
for the new hyperlink. May not be NULL.
szLocation
[in] A named location within the hyperlink target
which resolves to the hyperlink reference.
szFriendlyName
[in] A string to use as the display name for the
hyperlink.
phlSite
[in] Pointer to the IHlinkSite
object for the new hyperlink within the hyperlink container.
dwSiteData
[in] Additional site data for the new hyperlink object.
punkOuter
[in] Pointer to the controlling IUnknown interface
for the new hyperlink object. If NULL,
the new hyperlink object is not aggregated.
riid
[in] Identifies the interface to return on the new
hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter
is non-NULL.
ppv
[out] On return, pointer to the pointer to the requested
interface.
Return Values
S_OK
A new hyperlink object was created successfully.
Remarks
HlinkCreateFromData is
one of three helper API's that you can use to create a hyperlink.
HlinkCreateFromData creates a hyperlink from an OLE object
which both supports the IDataObject interface and supports
a hyperlink format CF_HYPERLINK on that IDataObject interface.
HlinkQueryCreateFromData is typically called before the
call to HlinkCreateFromData to determine if both these
conditions are met. To create a hyperlink from an OLE object for
which you know the moniker, use HlinkCreateFromMoniker.
To create a hyperlink from an OLE object for which you have the
name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromMoniker
creates new hyperlinks from an existing target moniker, a location
string within the target, and a friendly name string used to identify
how to display the hyperlink. This method's typical use is as
part of a user interface for creating new hyperlinks from existing
hyperlinks, or for editing existing hyperlinks, using a dialog
or form to prompt for the strings. This function is significantly
faster than HlinkCreateFromString.
See Also
HlinkCreateFromData
, HlinkCreateFromString
, HlinkQueryCreateFromData
HlinkCreateFromString [Beta]
Creates a new hyperlink object from strings representing
the hyperlink target, the location within the target, and a friendly
name.
HlinkCreateFromString(
Parameters
szTarget
[in] String to help identify the hyperlink target.
This string is resolved into a moniker via MkParseDisplayNameEx.
szLocation
[in] The string representing the location within
the hyperlink target for the new hyperlink. May not be NULL.
szFriendlyName
[in] The string to use as the friendly name for the
hyperlink. This is typically a display name referenced by the
user interface.
phlSite
[in] Pointer to the IHlinkSite
object for the new hyperlink within the hyperlink container.
dwSiteData
[in] Additional site data for the new hyperlink object.
punkOuter
[in] Points to the controlling IUnknown for
the new browse context. If NULL,
the new browse context is not aggregated.
riid
[in] Identifies the interface to return on the new
hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter
is non-NULL.
ppv
[out] On return, pointer to the pointer to the requested
interface.
Return Values
S_OK
A new hyperlink object was created.
Remarks
HlinkCreateFromData is
one of three helper API's that you can use to create a hyperlink.
HlinkCreateFromData creates a hyperlink from an OLE object
which both supports the IDataObject interface and supports
a hyperlink format CF_HYPERLINK on that IDataObject interface.
HlinkQueryCreateFromData is typically called before the
call to HlinkCreateFromData to determine if both these
conditions are met. To create a hyperlink from an OLE object for
which you know the moniker, use HlinkCreateFromMoniker.
To create a hyperlink from an OLE object for which you have the
name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromString
is typically used by hyperlink containers as part of the user-interface
for creating brand new hyperlinks, where the user fills in a form
or dialog of items -- target, location, friendly name -- which
are used to construct the hyperlink.
See Also
HlinkCreateFromData
, HlinkCreateFromMoniker
, HlinkQueryCreateFromData
HlinkGetSpecialReference [Beta]
For a given value from the HLSR
enumeration, this function returns the current user's default
global home, search, or history page for browsing as a string.
HlinkGetSpecialReference(
Parameters
dwReference
[in] A value taken from the HLSR enumeration.
pszReference
[out] Pointer to the location to return the special
reference string. May not be NULL.
See Also
HlinkSetSpecialReference
, HLSR
HlinkNavigate [Beta]
This helper API can be used to navigate a hyperlink
given a hyperlink object and an optional hyperlink frame object.
HlinkNavigate(
Parameters
phl
[in] Pointer to the IHlink
interface on the hyperlink to navigate to.
phlFrame
[in] Pointer to the IHlinkFrame
interface of the hyperlink container. May be NULL if the
hyperlink container does not have a hyperlink frame.
grfHLNF
[in] Value taken from the HLNF
enumeration.
pbc
[in] IBindCtx interface pointer to the bind
context to use for any moniker binding performed during the navigation.
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.
May be NULL, in which case the caller is not interested in progress
notification, cancellation, pausing, or low-level binding information.
phlbc
[in] Pointer to the IHlinkBrowseContext
interface pointer to use for this navigation. The browse
context includes history information in which this navigation
is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).
Remarks
HlinkNavigate encapsulates
the following common sequence of calls:
See Also
IHlinkBrowseContext
, IHlink::Navigate
, IHlinkFrame::Navigate
, IHlinkTarget::Navigate
HlinkNavigateToStringReference [Beta]
Creates a hyperlink site from strings representing
the hyperlink target, the location within the target, and a friendly
name, and then navigates to that site.
HlinkNavigateToStringReference(
Parameters
szTarget
[in] String which helps identify the hyperlink target.
This string is resolved into a moniker for underlying binding
operations via MkParseDisplayNameEx. May not be NULL.
szLocation
[in] Location within the hyperlink target of new
hyperlink object.
phlSite
[in] Pointer to the IHlinkSite
interface on the site object for the new hyperlink object.
This is optional, in which case szTarget must be an absolute
reference.
dwSiteData
[in] Additional site data for the new hyperlink object
phlFrame
[in] Pointer to IHlinkFrame
interface for the hyperlink frame object of the hyperlink
container object. May be NULL if the hyperlink container does
not have a hyperlink frame.
grfHLNF
[in] Value taken from the HLNF
enumeration.
pbc
[in] IBindCtx interface pointer to the bind
context object to use for any moniker binding performed during
the navigation. May not be NULL.
pbsc
[in] IBindStatusCallback
interface pointer to the bind-status-callback object to use
for any asynchronous moniker binding performed during the navigation.
May be NULL, in which case the caller is not interested in progress
notification, cancellation, pausing, or low-level binding information.
phlbc
[in] IHlinkBrowseContext
interface pointer to the browse context object to use for
this navigation. The browse context includes history information
in which this navigation is logged, if !(grfHLNF &
HLNF_CREATENOHISTORY).
Return Values
S_OK
A hyperlink site was created and navigated to.
Remarks
This helper API is identical to calling:
See Also
HLNF
, HlinkNavigate
, HlinkCreateFromString
, HlinkSimpleNavigateToString
HlinkOnNavigate [Beta]
Notifies a hyperlink browse context and hyperlink
frame, if it exists, that a hyperlink target has been navigated
to.
HlinkOnNavigate(
Parameters
phlFrame
[in] Pointer to the IHlinkFrame
interface of the hyperlink container. May be NULL if the
hyperlink container does not have a hyperlink frame.
phlbc
[in] Pointer to the IHlinkBrowseContext
interface for the browse context object to use for this navigation.
The browse context includes history information in which this
navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).
grfHLNF
[in] Value taken from the HLNF enumeration.
szTarget
[in] String which helps identify the hyperlink target.
This string is resolved into a moniker for underlying binding
operations via MkParseDisplayNameEx. May not be NULL.
szLocation
[in] Location within the hyperlink target of new
hyperlink object.
szFriendlyName
[in] The friendly name of the hyperlink.
Return Values
S_OK
The browse context and the frame, if it exists, have
been notified of the hyperlink navigation.
Remarks
HlinkOnNavigate is a helper
API typically called during IHlinkTarget::Navigate
which encapsulates the following calls:
See Also
IHlinkBrowseContext::OnNavigateHlink
, IHlinkFrame::OnNavigate
, IHlinkSite::OnNavigationComplete
HlinkQueryCreateFromData [Beta]
Determines if a new hyperlink can be created from
an IDataObject.
HRESULT HlinkQueryCreateFromData(
Parameters
pdatobj
[in] Pointer to the IDataObject supplying
the hyperlink formats.
Return Values
S_OK
A hyperlink can be created from the data object.
S_FALSE
A hyperlink can not be created from the data object.
Remarks
A hyperlink can be created from an IDataObject
in two ways:
· The IDataObject
offers the clip format CF_HYPERLINK on storage media type TYMED_ISTREAM
or TYMED_HGLOBAL, enumerations on TYMED
· The IDataObject
offers Win95 shortcut data
See Also
HlinkSetSpecialReference [Beta]
For a given value from the HLSR
enumeration, this function sets the current user's default
global home, search, or history page for browsing as a string.
HlinkSetSpecialReference(
Parameters
dwReference
[in] A value taken from the HLSR enumeration.
szReference
[in] The special reference string.
See Also
HlinkGetSpecialReference
, HLSR
HlinkSimpleNavigateToMoniker [Beta]
This helper function should be used by all application,
documents, and objects that have simple navigation needs. This
single function call that will "do the right thing"
depending on whether the navigation is originating from within
a hyperlink frame or within a hyperlink-unaware application.
HlinkSimpleNavigateToMoniker(
Parameters
szTarget
[in] String which helps identify the hyperlink target.
This string is resolved into a moniker for underlying binding
operations via MkParseDisplayNameEx.
May not be NULL.
szLocation
[in] Optional string representing the location within
the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for
the hyperlink navigation. This argument only affects navigation
within a document container that understands frame-sets.
szAdditionalParams
[in] Additional string parameters for the hyperlink
navigation (currently ignored).
IHlink::SetAdditionalParams and IHlink::GetAdditionalParams
describe the format.
pUnk
[in] The IUnknown pointer to the document
or object that is initiating the hyperlink. If NULL, it is assumed
the hyperlink originates from an OLE-unaware application.
grfHLNF
[in] Value taken from the HLNF
enumeration.
pbc
[in] Bind context to use for any moniker binding
performed during the navigation. May not be NULL.
pbsc
[in] Bind-status-callback to use for any asynchronous
moniker binding performed during the navigation. May be NULL,
in which case the caller is not interested in progress notification,
cancellation, pausing, or low-level binding information.
dwReserved
[in] Reserved for future use, must be set to NULL.
Return Values
S_OK
A hyperlink knowing the moniker of its target has
navigated to it successfully.
IHlink::Navigate
errors
See Also
HlinkNavigate
, HlinkNavigateToStringReference
, HlinkSimpleNavigateToString
, HLNF
HlinkSimpleNavigateToString [Beta]
This helper function should be used by all application,
documents, and objects that have simple navigation needs. This
single function call that will "do the right thing"
depending on whether the navigation is originating from within
a hyperlink frame or within a hyperlink-unaware application.
HlinkSimpleNavigateToString(
Parameters
szTarget
[in] String which helps identify the hyperlink target.
This string is resolved into a moniker for underlying binding
operations via MkParseDisplayNameEx. If NULL, then the
navigation is within a document. This parameter is required.
szLocation
[in] Optional string representing the location within
the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for
the hyperlink navigation. This argument only affects navigation
within a document container that understands frame-sets.
szAdditionalParams
[in] Additional string parameters for the hyperlink
navigation (currently ignored). IHlink::SetAdditionalParams
and IHlink::GetAdditionalParams describe the format.
pUnk
[in] The IUnknown pointer to the document
or object that is initiating the hyperlink. If NULL, it is assumed
the hyperlink originates from an OLE-unaware application.
grfHLNF
[in] Value taken from the HLNF
enumeration.
pbc
[in] IBindCtx interface pointer to the bind
context object to use for any moniker binding performed during
the navigation. May not be NULL.
pbsc
[in] IBindStatusCallback interface pointer
to the bind-status-callback object to use for any asynchronous
moniker binding performed during the navigation. May be NULL,
in which case the caller is not interested in progress notification,
cancellation, pausing, or low-level binding information.
dwReserved
[in] Reserved for future use, must be set to NULL.
Return Values
S_OK
A hyperlink knowing the name of its target has navigated
to it successfully.
IHlink::Navigate
errors
See Also
HlinkNavigate
, HlinkNavigateToStringReference
, HlinkSimpleNavigateToMoniker
, HLNF
, IHlink::Navigate
IsAsyncMoniker [Beta]
Tests if a moniker supports asynchronous binding.
HRESULT IsAsyncMoniker(
Parameters
pmk
[in] IMoniker pointer to the moniker to be
tested.
Return Values
S_OK
The specified moniker is asychronous.
E_INVALIDARG
The pmk argument is invalid.
See Also
TBD
MkParseDisplayNameEx [Beta]
Given a string, this function returns a moniker of
the object that the string denotes.
HRESULT MkParseDisplayNameEx(
Parameters
pbc
[in] The binding context in which to accumulate bound
objects.
szDisplayName
[in] The display name to be parsed.
pcchEaten
On exit the number of characters of the display name
that was successfully parsed. Most useful on syntax error, when
a non-zero value is often returned and therefore a subsequent
call to MkParseDisplayNameEx with the same pbc and
a shortened szDisplayName should return a valid moniker.
ppmk
On successful return, location to return a pointer
to a moniker.
Return Values
S_OK
Success.
MK_E_CANTOPENFILE
Indicates inability to attach to the specified resource.
Remarks
Given a string, this function returns a moniker of
the object that the string denotes. This operation is known as
parsing. A display name is parsed into a moniker; it is
resolved into its component moniker parts.
If a syntax error occurs, than an indication of how
much of the string was successfully parsed is returned in pcchEaten
and NULL is returned through ppmk. Otherwise, the value
returned through pcchEaten indicates the entire size of
the display name.
This API differs from the original MkParseDisplayName
in that it supports Universal Resource Indicator (URI)
syntax as established in IETF RFC1630 (http://ds.internic.net/rfc/rfc1590.txt).
Parsing a display name may in some cases be as expensive
as binding to the object that it denotes, since along the way
various non-trivial name space managers (such as a spreadsheet
application that can parse into ranges in its sheets) need to
be connected to by the parsing mechanism to succeed. As might
be expected, objects are not released by the parsing operation
itself, but are instead handed over to the passed-in binding context
(via IBindCtx::RegisterObjectBound). Thus, if the moniker
resulting from the parse is immediately bound using this same
binding context, redundant loading of objects is maximally avoided.
In many other cases, however, parsing a display name
may be quite inexpensive since a single name-space manager may
quickly return a moniker that will perform further expensive analysis
on any acceptable name during IMoniker::BindToObject or
other methods. An example of such an inexpensive parser is the
Win32 implementation of a File Moniker. A theoretical example
would be a naïve URL moniker which parsed from any valid
URL strings (i.e., "http:
", "file:
")
and only during binding took time to resolve the string against
the Internet, a potentially expensive operation.
The parsing process is an inductive one, in that
there is an initial step that gets the process going, followed
by the repeated application of an inductive step. At any point
after the beginning of the parse, a certain prefix of szDisplayName
has been parsed into a moniker, and a suffix of the display name
remains not understood. The inductive step asks the moniker-so-far
using IMoniker::ParseDisplayName to consume as much as
it would like of the remaining suffix and return the corresponding
moniker and the new suffix. The moniker is composed onto the end
of the existing moniker-so-far, and the process repeats.
Implementations of IMoniker::ParseDisplayName
vary in exactly where the knowledge of how to carry out the parsing
is kept. Some monikers by their nature are only used in particular
kinds of containers. It is likely that these monikers themselves
have the knowledge of the legal display name syntax within the
objects that they themselves denote, and so they can carry out
the processes completely within IMoniker::ParseDisplayName.
The common case, however, is that the moniker-so-far is generic
in the sense that is not specific to one kind of container, and
thus cannot know the legal syntax for elements within the container.
File monikers are an example of these, as are Item Monikers. These
monikers in general employ the following strategy to carry out
parsing. First, the moniker connects to the class of object
that it currently denotes, asking for IParseDisplayName
interface. If that succeeds, then it uses the obtained interface
pointer to attempt to carry out the parse. If the class refuses
to handle the parse, then the moniker binds to the object it
denotes, asking again for IParseDisplayName interface.
If this fails, then the parse is aborted.
The effect is that ultimately an object always gets
to be in control of the syntax of elements contained inside of
itself. It's just that objects of a certain nature can carry out
parsing more efficiently by having a moniker or their class do
the parsing on their behalf.
Notice that since MkParseDisplayNameEx knows
nothing of the legal syntax of display names (with the exception
of the initial parsing step; see below). It is of course beneficial
to the user that display names in different contexts not have
gratuitously different syntax. While there some rare situations
which call for special purpose syntax, it is recommended that,
unless there are compelling reasons to do otherwise, the syntax
for display names should be the same as or similar to the native
file system syntax; the aim is to build on user familiarity. Most
important about this are the characters allowed for the delimiters
used to separate the display name of one of the component monikers
from the next. Unless through some special circumstances they
have very good reason not to, all moniker implementations
should use inter-moniker delimiters from the character set:
\ / : ! [
Standardization in delimiters promotes usability.
But more importantly, notice that the parsing algorithm has the
characteristic that a given container consumes as much as it can
of the string being parsed before passing the remainder on to
the designated object inside themselves. If the delimiter expected
of the next-to-be-generated moniker in fact forms (part of) a
valid display name in the container, then the container's parse
will consume it!
Monikers and objects which have implementations on
more than one platform (such as File Monikers) should always parse
according to the syntax of the platform on which they are currently
running. When asked for their display name, monikers should also
show delimiters appropriate to the platform on which they are
currently running, even if they were originally created on a different
platform. In total, users will always deal with delimiters appropriate
for the host platform.
The initial step of the parsing process is
a bit tricky, in that it needs to somehow determine the initial
moniker-so-far. MkParseDisplayNameEx is omniscient with
respect to the syntax with which the display name of a moniker
may legally begin, and it uses this omniscience to choose the
initial moniker.
The initial moniker is determined by trying the following
strategies in order, using the first to succeed.
1. "ProgID:" Case: If a
prefix of szDisplayName conforms to the legal ProgID syntax,
is more than 1 character long, and is followed by a colon (':'),
the ProgID is converted to a CLSID with CLSIDFromProgID,
An instance of this class is asked for the IParseDisplayName
interface, and IParseDisplayName:ParseDisplayName is
called with the entire szDisplayName. This case distinguishes
MkParseDisplayNameEx from MkParseDisplayName.
2. ROT Case: All prefixes of szDisplayName
that consist solely of valid file name characters are consulted
as file monikers in the Running Object Table.
3. File-System Case: The file system is consulted
to check if a prefix of szDisplayName matches an existing
file. Said file name may be drive absolute, drive relative, working-directory
relative, or begin with an explicit network share name. This is
a common case.
4. "@ProgID" Case: If the initial
character of szDisplayName is '@', then the maximal string
immediately following the '@' which conforms to the legal ProgID
syntax is determined. This is converted to a CLSID with CLSIDFromProgID.
An instance of this class is asked in turn for IParseDisplayName
interface; the IParseDisplayName interface so found is
then given the whole string (starting with the '@') to continue
parsing.
See Also
IParseDisplayName
ReadUrlCacheEntryStream [Beta]
Provides a way to read the cached data from a stream
that has been opened using the RetrieveUrlCacheEntryStream
API.
BOOL ReadUrlCacheEntryStream
(
Parameters
hUrlCacheStream
[in] Handle that was returned by a call to the RetrieveUrlCacheEntryStream function.
dwLocation
[in] Offset to read from.
lpBuffer
[in] Pointer to a buffer where the data is read.
lpdwLen
[in] Pointer to a DWORD location where the length
of the above buffer passed in, on return it contains the actual
length of the data read.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
See Also
RegisterBindStatusCallback [Beta]
Registers an IBindStatusCallback
with an existing bind context.
HRESULT RegisterBindStatusCallback(
Parameters
pbc
[in] IBindCtx pointer to the bind context
with which the callback is to be registered.
pbsc
[in] Pointer to the IBindStatusCallback interface
to be registered.
grfBSCOption
Flags from the BSC_OPTION enumeration, specifying
which callback methods should be called.
dwReserved
Reserved for future extension.
Return Values
S_OK
Success.
E_OUTOFMEMORY
Insufficient memory to register the callback with
the bind context.
E_INVALIDARG
One or more arguments are invalid.
Remarks
RegisterBindStatusCallback registers
an object implementing IBindStatusCallback with an existing
bind context. This function is the only mechanism that clients
should use for registering an IBindStatusCallback interface
for a bind operation. Do not call IMoniker::RegisterObjectParams
rather than this function.
RegisterBindStatusCallback allows
the client to specify flags that determine which callback methods
the client is capable of receiving. If the client does not wish
to receive certain notification, it can choose to implement those
callback methods as empty function stubs (returning E_NOTIMPL),
and they will not be called.
This API allows multiple clients to each register
a callback for the same bind context. 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.
For this reason, a client should request to receive only those
callback methods that it plans on implementing.
See Also
RegisterFormatEnumerator [Beta]
Registers a format enumerator object onto the given
bind context.
HRESULT RegisterFormatEnumerator(
Parameters
pbc
[in] IBindCtx pointer to bind context with
which the format enumerator is to be registered.
pEFetc
[in] IEnumFORMATETC pointer the format enumerator
to be registered.
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
Registers a format enumerator object onto the given
bind context. This format enumerator is used to determine what
format types are prefered for the bind operation. Typically, the
pEFetc parameter would be the pointer obtained through
a call to CreateFormatEnumerator.
See Also
CreateFormatEnumerator
, RevokeFormatEnumerator
RegisterMediaTypes [Beta]
Registers media types strings.
HRESULT RegisterMediaTypes
(
Parameters
ctypes
[in] The number of media type strings in the rgszTypes
array. May not be zero.
rgszTypes
[in] Array of strings identifying the media types
to be registered. None may be NULL.
rgcfTypes
[in] Location to return the 32-bit values assigned
to corresponding media types in rgszTypes.
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
Media types are taken from the following:
See Also
TBD
RetrieveUrlCacheEntryFile [Beta]
Retrieves a cache entry from the cache in the form
of a file.
BOOL RetrieveUrlCacheEntryFile(
Parameters
lpszUrlName
[in] Source name of the cache entry. This must be
an unique name. The name string should not contain any escape
characters.
lpCacheEntryInfo
[in] Pointer to a cache entry info buffer (for the
CACHE_ENTRY_INFO
structure). If the buffer is not sufficient to accommodate
all the information associated with the URL, one or more of the
embedded pointers will be NULL.
lpdwCacheEntryInfoBufferSize
[in,out] Pointer to a DWORD location when the size
of the above buffer is passed in, on return this will contain
the size of the actual buffer used or required. The caller should
check the return value in this field. If the return size is less
than or equal to the size passed in, all the relevant data has
been returned.
dwReserved
Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
RetrieveUrlCacheEntryFile
retrieves a cache entry from the cache in the form of a file.
If an extension was provided while calling CommitUrlCacheEntry
then the file will have the specified extension. If the entry
is not available in cache it returns ERROR_FILE_NOT_FOUND, otherwise
it returns the name of the local file. The caller is given only
read permission to the local file, so the caller should not attempt
to write or delete the file. The file is locked for the caller
when it is retrieved, the caller should unlock the file after
it has been used up. Cache manager will automatically unlock the
locked files after certain interval.
While the file is locked cache manager will not remove
the file from cache. It important to note that this API may be
efficient or expensive depending on the internal implementation
of the cache. For instance, if the urldata is stored in a packed
file which contains data for other URLs, the cache will make a
copy of the data to a file in a temporary directory maintained
by the cache. The cache will eventually delete the copy. It is
recommended that this API be used only in situations where a filename
is needed in order to launch an application. RetrieveUrlCacheEntryStream
and associated stream APIs should be used in most cases.
See Also
RetrieveUrlCacheEntryStream [Beta]
Provides access to the cache data.
HANDLE RetrieveUrlCacheEntryStream(
Parameters
lpszUrlName
[in] Source name of the cache entry. This must be
an unique name. The name string should not contain any escape
characters.
lpCacheEntryInfo
[out] Pointer to a buffer to hold a CACHE_ENTRY_INFO
structure.
lpdwCacheEntryInfoBufferSize
[in,out] Pointer to a DWORD location when the size
of the above buffer is passed in, on return this will contain
the size of the actual buffer required.
fRandomRead
[in] Flag to indicate whether the stream is opened
for random access. Set the flag to TRUE to open the stream for
random access.
dwReserved
[in] Reserved for future use.
Return Values
Handle
If successful, returns a valid handle (to be used
in the other stream APIs).
INVALID_HANDLE_VALUE
Not successful;. and a call to GetLastError
returns the error code value. This returns ERROR_FILE_NOT_FOUND
if the cache entry specified by the source name is not found in
the cache storage.
Remarks
RetrieveCacheEntryStream
provides the most efficient and implementation independent way
of accessing the cache data. Cache clients that do not need url
data in the form of a file should use this API in order to access
the data for a particular URL.
See Also
RevokeBindStatusCallback [Beta]
Revokes an IBindStatusCallback
interface on a callback previously registered on a bind context.
HRESULT RevokeBindStatusCallback(
Parameters
pbc
[in] IBindCtx pointer to bind context from
which the callback interface is to be revoked.
pbsc
[in] Pointer to the IBindStatusCallback interface
to revoke.
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
RevokeBindStatusCallback
revokes an IBindStatusCallback callback previously registered
on a bind context. This call will not succeed if it is made during
a bind operation.
See Also
IBindStatusCallback
, RegisterBindStatusCallback
RevokeFormatEnumerator [Beta]
Removes a format enumerator from the given bind context.
HRESULT RevokeFormatEnumerator(
Parameters
pbc
[in] IBindCtx pointer to bind context from
which the format enumerator is to be revoked.
pbsc
[in] IEnumFORMATETC pointer to the format
enumerator to revoke.
Return Values
S_OK
Success - the format enumerator was removed..
E_INVALIDARG
One or more arguments are invalid.
Remarks
RevokeFormatEnumerator
removes a format enumerator from the bind context specified in
pbc. It must previously have been registered with a call
to RegisterFormatEnumerator.
See Also
SetUrlCacheConfigInfo [Beta]
Sets the specified cache configuration information.
BOOL SetUrlCacheConfigInfo
(
Parameters
lpCacheConfigInfo
[in] Pointer to a CACHE_CONFIG_INFO structure containing
the information to set in the registry.
dwFieldControl
[in] Bitmask that controls the fields to be returned
in the above buffer. Refer to the Remarks.
Return Values
S_OK
Success.
E_INVALIDARG
One or more arguments are invalid.
Remarks
The cache management APIs provide controls to administrator
to manage the files that are cached on the client storage. The
management APIs are to be used only by a control panel applet
to configure the cache. SetUrlCacheConfigInfo API sets
the specified cache configuration information. If any setting
is changed, all the top level windows get WM_SETTINGCHANGE message.
The dwFieldControl parameter is a bitmask that specifies
the fields to be retrieved. The value consists of one or more
of the following.
See Also
CACHE_CONFIG_INFO
structure, GetUrlCacheConfigInfo
SetUrlCacheEntryInfo [Beta]
Sets the specified fields of the cache entry info.
BOOL SetUrlCacheEntryInfo
(
Parameters
lpszUrlName
[in] Name of the cache entry. The name string should
not contain any escape character.
lpCacheEntryInfo
[in] Pointer to a CACHE_ENTRY_INFO
structure.
dwFieldControl
Bitmask that indicates the fields that are to be
set. Must be one or more of the following mask ORed together.
Return Values
ERROR_FILE_NOT_FOUND
The specified cache entry is not found in the cache.
See Also
CACHE_ENTRY_INFO
structure
UnlockUrlCacheEntryFile [Beta]
Unlocks the cache entry that was locked while the
file was retrieved for use from cache.
BOOL UnlockUrlCacheEntryFile
(
Parameters
lpszUrlName
[in] Source name of the cache entry that is being
unlocked. The name string should not contain any escape characters.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
UnlockUrlCacheEntryFile
unlocks the cache entry which was locked while the file was retrieved
for use from cache. The caller should not access the file after
it calls this API. The cache manager is now free to delete the
cache entry if it wants.
See Also
TBD
UnlockUrlCacheEntryStream [Beta]
Closes the stream that has been retrieved using the
RetrieveCacheUrlEntryStream function.
HRESULT UnlockCacheEntryStream
(
Parameters
hUrlCacheStream
[in] Handle that was returned by the RetrieveUrlCacheEntryStream
API.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
See Also
UrlCacheValidate [Beta]
Validates the cache consistency.
BOOL UrlCacheValidate
(
Parameters
bFixIt
[in] Fix the invalid entries if possible when this
flag is set to TRUE.
dwReserved
[in] Reserved for future use.
Return Values
TRUE
Success.
FALSE
Not successful;. and a call to GetLastError
returns the error code value.
Remarks
UrlCacheValidate validates
the cache consistency. Internet Services that use the URL cache
should call this api at appropriate time before using the cache
system. This API takes several seconds before it returns depending
upon the size of the cache.
LPCACHE_ CONFIG_INFO lpCacheConfigInfo
//Points to the CACHE_CONFIG_INFO structure
LPDWORD lpdwCacheConfigInfoBufferSize
//Points to the size of the buffer for the above
DWORD dwFieldControl
//Bitmask determining fields to be retrieved
);
CACHE_CONFIG_CLEANUP_INTERVAL_FC
0x00000002 CACHE_CONFIG_CLEANUP_FACTOR_FC 0x00000004
CACHE_CONFIG_CLEANUP_TIME_FC 0x00000008
CACHE_CONFIG_PERSISTENT_CACHE_FC 0x00000010
CACHE_CONFIG_FORCE_CLEANUP_FC 0x00000020
CACHE_CONFIG_DISK_CACHE_PATHS_FC 0x00000040
LPCSTR lpszUrlName
//Name of cache entry LPCACHE_ENTRY_INFO lpCacheEntryInfo
//Points to CACHE_ENTRY_INFO structure buffer
LPDWORD lpdwCacheEntryInfoBufferSize
//Size of the buffer in bytes );
IUnknown *punkOuter
//Controlling unknown for possible aggregation
REFIID riid //Interface ID to return on the new browse context
void **ppv //Receives the requested interface's pointer
);
coCreateInstance(CLSID_StdHlinkBrowseContext, punkOuter,
CLSCTX_SERVER, riid, ppv).
IDataObject* pdatobj
//Interface on target data from which to create the hyperlink
IHlinkSite* phlSite //Interface on hyperlink site
DWORD dwSiteData //Additional site data
IUnknown *punkOuter //Interface which controls aggregation
REFIID riid //Interface ID on new hyperlink object
Void ** ppv //Receives the requested interface's pointer
);
IMoniker * pmkTarget
//Interface on hyperlink target moniker
LPCWSTR szLocation //Named location of hyperlink reference within target
LPCWSTR szFriendlyName
//Display name of hyperlink IHlinkSite * phlSite
//Interface on hyperlink site DWORD dwSiteData //Additional site data
IUnknown * punkOuter
//Whether or not object is part of an aggregate
REFIID riid //Interface ID on new hyperlink object
Void * ppv //Receives the requested interface's pointer
);
LPCWSTR szTarget
//String helping to identify the hyperlink target
LPCWSTR szLocation //Location within the hyperlink target of new hyperlink object
LPCWSTR szFriendlyName
//Friendly name of the hyperlink IHlinkSite * phlSite
//Site for the new hyperlink object DWORD dwSiteData //Additional site data for the new hyperlink object
IUnknown * punkOuter
//Whether or not object is part of an aggregate
REFIID riid //Interface ID on new browse context object
Void * ppv //Location of the requested interface's pointer
);
DWORD dwReference
//Special reference flags LPWSTR ** pszReference
//Buffer to return special reference string
);
IHlink * phl
//The hyperlink to navigate to IHlinkFrame * phlFrame
//The hyperlink frame of the hyperlink container.
DWORD grfHLNF //Navigation flags
IBindCtx * pbc //Bind context object interface pointer
IBindStatusCallback * pbsc
//Bind status callback object interface pointer
IHlinkBrowseContext * phlbc
//Browse context object interface pointer
);
if (phlFrame)
phlFrame->Navigate(grfHLNF, pbc, pbsc, phl);
else if (phl)
phl->Navigate(grfHLNF, pbc, pbsc, phlbc);
LPCWSTR szTarget
//String helping to identify the hyperlink target
LPCWSTR szLocation //Location within the hyperlink target of new hyperlink
IHlinkSite * phlSite
//Site object interface for the new hyperlink object
DWORD dwSiteData //Additional site data for the new hyperlink object
IHlinkFrame * phlFrame
//Frame object interface for the new hyperlink object
DWORD grfHLNF //Navigation flags
IBindCtx * pbc //Bind context object
IBindStatusCallback * pbsc
//Bind status callback object IHlinkBrowseContext * phlbc
//Browse context object );
// create hyperlink site, IBindStatusCallback,
// gather bind context, and browse context
HlinkCreateFromString(szTarget, szLocation,
szFriendlyName, &hlSite, dwSiteData, NULL,
IID_IHlink, (void**)&phl);
HlinkNavigate(phl, phlFrame, grfHLNF, pbc, pbsc, phlbc);
phl->Release();
IHlinkFrame * phlFrame
//Frame object interface for the new hyperlink
IHlinkBrowseContext * phlbc
//Browse context object to use for this navigation
DWORD grfHLNF //Navigation flags
LPCWSTR szTarget //String helping to identify the hyperlink target
LPCWSTR szLocation //Location within the hyperlink target of new hyperlink
LPCWSTR szFriendlyName
//Friendly name of the hyperlink );
phlbc->OnNavigateHlink(grfHLNF, pmkTarget, szLocation, szFriendlyName);
if (phlframe)
phlframe->OnNavigate(grfHLNF);
IDataObject* pdatobj
//Data object to query );
DWORD dwReference
//Special reference flags LPCWSTR szReference //The special reference string
);
IMoniker * pmkTarget
//Moniker of the hyperlink target LPCWSTR szLocation //Optional string representing location within target
LPCWSTR szTargetFrameName
//Optional string naming the target frame
LPCWSTR szAdditionalParams
//Optional additional parameters IUnknown * punk //IUnknown interface of initiating document or object
DWORD grfHLNF //Navigation flags
IBindCtx * pbc //Bind context object
IBindStatusCallback * pbsc
//Bind status callback DWORD dwReserved //Reserved for future use
);
LPCWSTR szTarget
//String to be resolved into target's moniker
LPCWSTR szLocation //Optional string representing location within target
LPCWSTR szTargetFrameName
//Optional string naming the target frame
LPCWSTR szAdditionalParams
//Additional parameters IUnknown * pUnk //IUnknown interface of initiating document or object
DWORD grfHLNF //Navigation flags
IBindCtx * pbc //Bind context object
IBindStatusCallback * pbsc
//Bind status callback object DWORD dwReserved //Reserved for future use
);
IMoniker * pmk
//Points to the current memory handle for the specified byte array
);
IBindCtx* pbc
//The bind context
LPWSTR szDisplayName
//The display name to be parsed
ULONG * pcchEaten
//Number of characters of the display name successfully parsed
IMoniker ** ppmk //Location to return a moniker if successful
);
HANDLE hUrlCacheStream
//Handle returned by RetrieveCacheEntryStream
DWORD dwLocation //Offset to read from
LPVOID lpBuffer //
LPDWORD lpdwLen //
DWORD dwReserved
//Reserved );
IBindCtx * pbc
//Pointer to the bind context to be used
IBindStatusCallback * pbsc
//Pointer to callback interface to be registered
DWORD grfBSCOption //BSC_OPTION flags
DWORD dwReserved //Reserved
);
IBindCtx * pbc
//Points to the bind context
IEnumFORMATETC * pEFetc
//Points to the format enumerator
DWORD dwReserved //Reserved
);
UINT ctypes
//The number of media type strings in rgszTypes
LPTSTR * rgszTypes
//Array of media types to be registered
CLIPFORMAT * rgcfTypes
//Pointer to 32-bit values corresponding to rgszType array values
);
Value Meaning
CF_NULL 0 SZ_URLCONTEXT (L"URL Context")
CFSTR_MIME_FRACTALS (TEXT("application/fractals"))
CFSTR_MIME_RAWDATA (TEXT("application/octet"))
CFSTR_MIME_POSTSCRIPT (TEXT("application/postscript"))
CFSTR_MIME_AIIF (TEXT("audio/aiff"))
CFSTR_MIME_BASICAUDIO (TEXT("audio/basic"))
CFSTR_MIME_WAV (TEXT("audio/wav"))
CFSTR_MIME_X_AIIF (TEXT("audio/x-aiif"))
CFSTR_MIME_X_REALAUDIO (TEXT("audio/x-pn-realaudio"))
CFSTR_MIME_X_WAV (TEXT("audio/x-wav"))
CFSTR_MIME_BMP (TEXT("image/bmp"))
CFSTR_MIME_GIF (TEXT("image/gif"))
CFSTR_MIME_JPEG (TEXT("image/jpeg"))
CFSTR_MIME_TIFF (TEXT("image/tiff"))
CFSTR_MIME_XBM (TEXT("image/xbm"))
CFSTR_MIME_X_BITMAP (TEXT("image/x-bitmap"))
CFSTR_MIME_HTML (TEXT("text/html"))
CFSTR_MIME_TEXT (TEXT("text/plain"))
CFSTR_MIME_AVI (TEXT("video/avi"))
CFSTR_MIME_MPEG (TEXT("video/mpeg"))
CFSTR_MIME_QUICKTIME TEXT("video/quicktime"))
CFSTR_MIME_X_MSVIDEO (TEXT("video/x-msvideo"))
CFSTR_MIME_X_SGI_MOVIE (TEXT("video/x-sgi-movie"))
LPCSTR lpszUrlName
//Source name of the cache entry LPCACHE_ENTRY_INFO lpCacheEntryInfo
//Pointer to a cache entry info buffer
LPDWORD lpdwCacheEntryInfoBufferSize
//On return, contains the size of the actual buffer used
DWORD dwReserved
//Reserved );
LPCSTR lpszUrlName
//Source name of the cache entry LPCACHE_ENTRY_INFO lpEntryInfo
//Pointer to a CACHE_ENTRY_INFO structure on return
LPDWORD lpdwCacheEntryInfoBufferSize
//On return, contains the size of the actual buffer required
BOOL fRandomRead //Indicate whether the stream is opened for random access
DWORD dwReserved
//Reserved );
IBindCtx * pbc
//Points to the bind context from which the callback is to be revoked
IBindStatusCallback * pbsc
//Points to the callback interface to revoke
);
IBindCtx * pbc
//Points to the bind context
IEnumFORMATETC * pEFetc
//Points to the format enumerator to revoke
);
LPCACHE_CONFIG_INFO lpCacheInfo
//Points to the CacheConfigInfo structure
DWORD dwFieldControl
//Bitmask controlling fields to be set
);
CACHE_CONFIG_CLEANUP_INTERVAL_FC
0x00000002 CACHE_CONFIG_CLEANUP_FACTOR_FC 0x00000004
CACHE_CONFIG_CLEANUP_TIME_FC 0x00000008
CACHE_CONFIG_PERSISTENT_CACHE_FC 0x00000010
CACHE_CONFIG_FORCE_CLEANUP_FC 0x00000020
CACHE_CONFIG_DISK_CACHE_PATHS_FC 0x00000040
LPCSTR lpszUrlName
//Name of the cache entry
LPCACHE_ENTRY_INFO lpCacheEntryInfo
//Pointer to a CACHE_ENTRY_INFO structure.
DWORD dwFieldControl
//Fields to be set
);
Name Value
CACHE_ENTRY_ATTRIBUTE_FC 0x00000004
CACHE_ENTRY_HITRATE_FC 0x00000010
CACHE_ENTRY_MODTIME_FC 0x00000040
CACHE_ENTRY_EXPTIME_FC 0x00000080
CACHE_ENTRY_ACCTIME_FC 0x00000100
LPCSTR lpszUrlName
//Source name of the cache entry being unlocked
DWORD dwReserved
//Reserved );
HANDLE hUrlCacheStream
//Handle to cache entry stream
DWORD dwReserved
//Reserved );
BOOL bFixIt
//When TRUE, fix invalid entries
DWORD dwReserved
//Reserved );