[TOC]

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

CreateAsyncBindCtx

[TOC]

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

CreateAsyncBindCtx

[TOC]

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.
FlagValue Definition
NORMAL_CACHE_ENTRY0x00000001 Normal cache entry, may be deleted to recover space for new entries.
STABLE_CACHE_ENTRY0x00000002 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_ENTRY0x00000004 These entries will never be removed automatically by the cache management system.
SPARSE_CACHE_ENTRY0x00010000 indicate this cache entry is incomplete.
OCX_CACHE_ENTRY0x00020000 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

CreateUrlCacheEntry

[TOC]

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

[TOC]

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

[TOC]

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

RetrieveUrlCacheEntryFile

[TOC]

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

[TOC]

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

[TOC]

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

[TOC]

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

[TOC]

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

[TOC]

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

[TOC]

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\\CLSID key.

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

[TOC]

GetUrlCacheConfigInfo [Beta]

Retrieves the current cache configuration information.

BOOL GetUrlCacheConfigInfo (
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
);

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.
CACHE_CONFIG_CLEANUP_INTERVAL_FC 0x00000002
CACHE_CONFIG_CLEANUP_FACTOR_FC0x00000004
CACHE_CONFIG_CLEANUP_TIME_FC0x00000008
CACHE_CONFIG_PERSISTENT_CACHE_FC0x00000010
CACHE_CONFIG_FORCE_CLEANUP_FC0x00000020
CACHE_CONFIG_DISK_CACHE_PATHS_FC0x00000040

See Also

CACHE_CONFIG_INFO structure

[TOC]

GetUrlCacheEntryInfo [Beta]

Retrieves the information of the specified cache entry.

BOOL GetUrlCacheEntryInfo (
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
);

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

[TOC]

HlinkCreateBrowseContext [Beta]

Creates an empty, default instance of the system browse context object.

HRESULT HlinkCreateBrowseContext(
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
);

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

coCreateInstance(CLSID_StdHlinkBrowseContext, punkOuter,
CLSCTX_SERVER, riid, ppv).

See Also

IHlinkBrowseContext , IHlinkFrame::GetBrowseContext , IHlinkTarget::GetBrowseContext

[TOC]

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(
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
);

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

[TOC]

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(
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
);

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

[TOC]

HlinkCreateFromString [Beta]

Creates a new hyperlink object from strings representing the hyperlink target, the location within the target, and a friendly name.

HlinkCreateFromString(
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
);

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

[TOC]

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(
DWORD dwReference //Special reference flags
LPWSTR ** pszReference //Buffer to return special reference string
);

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

[TOC]

HlinkNavigate [Beta]

This helper API can be used to navigate a hyperlink given a hyperlink object and an optional hyperlink frame object.

HlinkNavigate(
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
);

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:

if (phlFrame)
phlFrame->Navigate(grfHLNF, pbc, pbsc, phl);
else if (phl)
phl->Navigate(grfHLNF, pbc, pbsc, phlbc);

See Also

IHlinkBrowseContext , IHlink::Navigate , IHlinkFrame::Navigate , IHlinkTarget::Navigate

[TOC]

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(
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
);

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:

// 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();

See Also

HLNF , HlinkNavigate , HlinkCreateFromString , HlinkSimpleNavigateToString

[TOC]

HlinkOnNavigate [Beta]

Notifies a hyperlink browse context and hyperlink frame, if it exists, that a hyperlink target has been navigated to.

HlinkOnNavigate(
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
);

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:

phlbc->OnNavigateHlink(grfHLNF, pmkTarget, szLocation, szFriendlyName);
if (phlframe)
phlframe->OnNavigate(grfHLNF);

See Also

IHlinkBrowseContext::OnNavigateHlink , IHlinkFrame::OnNavigate , IHlinkSite::OnNavigationComplete

[TOC]

HlinkQueryCreateFromData [Beta]

Determines if a new hyperlink can be created from an IDataObject.

HRESULT HlinkQueryCreateFromData(
IDataObject* pdatobj //Data object to query
);

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

HlinkCreateFromData

[TOC]

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(
DWORD dwReference //Special reference flags
LPCWSTR szReference//The special reference string
);

Parameters

dwReference

[in] A value taken from the HLSR enumeration.

szReference

[in] The special reference string.

See Also

HlinkGetSpecialReference , HLSR

[TOC]

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(
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
);

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

[TOC]

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(
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
);

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

[TOC]

IsAsyncMoniker [Beta]

Tests if a moniker supports asynchronous binding.

HRESULT IsAsyncMoniker(
IMoniker * pmk //Points to the current memory handle for the specified byte array
);

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

[TOC]

MkParseDisplayNameEx [Beta]

Given a string, this function returns a moniker of the object that the string denotes.

HRESULT MkParseDisplayNameEx(
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
);

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

[TOC]

ReadUrlCacheEntryStream [Beta]

Provides a way to read the cached data from a stream that has been opened using the RetrieveUrlCacheEntryStream API.

BOOL ReadUrlCacheEntryStream (
HANDLE hUrlCacheStream //Handle returned by RetrieveCacheEntryStream
DWORD dwLocation//Offset to read from
LPVOID lpBuffer//
LPDWORD lpdwLen//
DWORD dwReserved //Reserved
);

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

RetrieveUrlCacheEntryStream

[TOC]

RegisterBindStatusCallback [Beta]

Registers an IBindStatusCallback with an existing bind context.

HRESULT RegisterBindStatusCallback(
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
);

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

IBindStatusCallback

[TOC]

RegisterFormatEnumerator [Beta]

Registers a format enumerator object onto the given bind context.

HRESULT RegisterFormatEnumerator(
IBindCtx * pbc //Points to the bind context
IEnumFORMATETC * pEFetc //Points to the format enumerator
DWORD dwReserved//Reserved
);

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

[TOC]

RegisterMediaTypes [Beta]

Registers media types strings.

HRESULT RegisterMediaTypes (
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
);

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:
ValueMeaning
CF_NULL0
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_QUICKTIMETEXT("video/quicktime"))
CFSTR_MIME_X_MSVIDEO(TEXT("video/x-msvideo"))
CFSTR_MIME_X_SGI_MOVIE(TEXT("video/x-sgi-movie"))

See Also

TBD

[TOC]

RetrieveUrlCacheEntryFile [Beta]

Retrieves a cache entry from the cache in the form of a file.

BOOL RetrieveUrlCacheEntryFile(
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
);

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

CommitUrlCacheEntry

[TOC]

RetrieveUrlCacheEntryStream [Beta]

Provides access to the cache data.

HANDLE RetrieveUrlCacheEntryStream(
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
);

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

ReadUrlCacheEntryStream

[TOC]

RevokeBindStatusCallback [Beta]

Revokes an IBindStatusCallback interface on a callback previously registered on a bind context.

HRESULT RevokeBindStatusCallback(
IBindCtx * pbc //Points to the bind context from which the callback is to be revoked
IBindStatusCallback * pbsc //Points to the callback interface to revoke
);

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

[TOC]

RevokeFormatEnumerator [Beta]

Removes a format enumerator from the given bind context.

HRESULT RevokeFormatEnumerator(
IBindCtx * pbc //Points to the bind context
IEnumFORMATETC * pEFetc //Points to the format enumerator to revoke
);

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

RegisterFormatEnumerator

[TOC]

SetUrlCacheConfigInfo [Beta]

Sets the specified cache configuration information.

BOOL SetUrlCacheConfigInfo (
LPCACHE_CONFIG_INFO lpCacheInfo //Points to the CacheConfigInfo structure
DWORD dwFieldControl //Bitmask controlling fields to be set
);

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.
CACHE_CONFIG_CLEANUP_INTERVAL_FC 0x00000002
CACHE_CONFIG_CLEANUP_FACTOR_FC0x00000004
CACHE_CONFIG_CLEANUP_TIME_FC0x00000008
CACHE_CONFIG_PERSISTENT_CACHE_FC0x00000010
CACHE_CONFIG_FORCE_CLEANUP_FC0x00000020
CACHE_CONFIG_DISK_CACHE_PATHS_FC0x00000040

See Also

CACHE_CONFIG_INFO structure, GetUrlCacheConfigInfo

[TOC]

SetUrlCacheEntryInfo [Beta]

Sets the specified fields of the cache entry info.

BOOL SetUrlCacheEntryInfo (
LPCSTR lpszUrlName //Name of the cache entry
LPCACHE_ENTRY_INFO lpCacheEntryInfo //Pointer to a CACHE_ENTRY_INFO structure.
DWORD dwFieldControl //Fields to be set
);

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.
NameValue
CACHE_ENTRY_ATTRIBUTE_FC0x00000004
CACHE_ENTRY_HITRATE_FC0x00000010
CACHE_ENTRY_MODTIME_FC0x00000040
CACHE_ENTRY_EXPTIME_FC0x00000080
CACHE_ENTRY_ACCTIME_FC0x00000100

Return Values

ERROR_FILE_NOT_FOUND

The specified cache entry is not found in the cache.

See Also

CACHE_ENTRY_INFO structure

[TOC]

UnlockUrlCacheEntryFile [Beta]

Unlocks the cache entry that was locked while the file was retrieved for use from cache.

BOOL UnlockUrlCacheEntryFile (
LPCSTR lpszUrlName //Source name of the cache entry being unlocked
DWORD dwReserved //Reserved
);

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

[TOC]

UnlockUrlCacheEntryStream [Beta]

Closes the stream that has been retrieved using the RetrieveCacheUrlEntryStream function.

HRESULT UnlockCacheEntryStream (
HANDLE hUrlCacheStream //Handle to cache entry stream
DWORD dwReserved //Reserved
);

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

RetrieveUrlCacheEntryStream

[TOC]

UrlCacheValidate [Beta]

Validates the cache consistency.

BOOL UrlCacheValidate (
BOOL bFixIt //When TRUE, fix invalid entries
DWORD dwReserved //Reserved
);

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.