ReleaseBindInfo
Functions

ReleaseBindInfo


ReleaseBindInfo(
    BINDINFO *pbindinfo
);

Release the resources used by the specified BINDINFO structure.

pbindinfo
Address of the specified BINDINFO structure.

RevokeBindStatusCallback

HRESULT RevokeBindStatusCallback(
    [in] IBindCtx *pbc,
    [in] IBindStatusCallback *pbsc
);

Revokes a bind status callback interface previously registered on a bind context.

pbc
Address of the IBindCtx interface for the bind context from which the callback interface is to be revoked.
pbsc
Address of the IBindStatusCallback interface to revoke.

This function will not succeed if it is made during a bind operation.

Note that it is not necessary to make this call for every use of a bind context. It is possible, although not recommended, to reuse the same bind context and the same callback for several bind operations. Upon calling the IUnknown::Release method, all registered objects on that bind context are revoked, including the callback interfaces. Therefore, releasing a bind context implicitly releases all registered callbacks. However, if you choose to reuse a bind context, you can use RevokeBindStatusCallback to remove a registered callback so it is not reused.

See also IBindStatusCallback, RegisterBindStatusCallback

RevokeFormatEnumerator

HRESULT RevokeFormatEnumerator(
    [in] LPBC pbc,
    [in] IEnumFORMATETC *pEFetc
);

Removes a format enumerator from the given bind context.

pbc
Address of the IBindCtx interface for the bind context from which the enumerator is to be revoked.
pEFetc
Address of the IEnumFORMATETC interface for the enumerator to revoke.

This function removes a format enumerator from the bind context specified in pbc. It must previously have been registered with a call to RegisterFormatEnumerator.

Note that it is not necessary to make this call for every use of a bind context. It is possible (although not recommended) to reuse the same bind context and the same format enumerator for several bind operations. Upon calling IUnknown::Release, all registered objects on that bind context are revoked, including the format enumerator interfaces. Therefore, releasing a bind context implicitly releases all registered format enumerators. However, if you choose to reuse a bind context, you can use RevokeFormatEnumerator to remove a registered format enumerator so it is not reused.

See also RegisterFormatEnumerator

URLDownloadToCacheFile

HRESULT URLDownloadToCacheFile(
    LPUNKNOWN lpUnkcaller,
    LPCSTR szURL,
    LPTSTR szFileName,
    DWORD dwBufLength,
    DWORD dwReserved,
    IBindStatusCallback *pBSC
);

Downloads data into the Internet cache and returns the file name of the cache location for retrieving the bits. The client can choose to be notified of progress through a notification callback.

lpUnkcaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
URL to be downloaded. Cannot be NULL.
szFileName
Name of the downloaded file. Cannot be NULL.
dwBufLength
DWORD value that contains the size of the szFileName buffer or a flag. If a flag is set to dwBufLength, the buffer is assumed to be of size MAX_PATH. The flag can be one of the following values:
URLOSTRM_USECACHEDCOPY_ONLY Only download the resource from the cache.
URLOSTRM_USECACHEDCOPY Download the resource from the cache if it is available; otherwise, download it from the Internet.
URLOSTRM_GETNEWESTVERSION Download the resource from the Internet, if it is newer, and store it in the cache.
dwReserved
Reserved. Must be set to zero.
pBSC
Address of the caller's IBindStatusCallback interface. URLDownloadToCacheFile calls this interface's IBindStatusCallback::OnProgress method on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call. Can be NULL.

This function always returns a file name if the download operation succeeds. If the given URL is a "file:" URL, URLDownloadToCacheFile directly returns the file name for the "file:" URL rather than making a copy to the cache. If the given URL is an Internet URL ("http:", "ftp:"), URLDownloadToCacheFile downloads this file and returns the local file name of the cached copy. Using this function ensures that a file name is returned without unnecessary copying of data.

URLDownloadToFile

HRESULT URLDownloadToFile(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    LPCSTR szFileName,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Downloads bits from the Internet and saves them to a file. The client can choose to be notified of progress through a notification callback.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the calling application is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be downloaded. Cannot be NULL.
szFileName
String containing the name of the file to create for bits that come from the download.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface. URLDownloadToFile calls this interface's IBindStatusCallback::OnProgress method on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call. Can be NULL.

UrlMkGetSessionOption

WINOLEAPI UrlMkGetSessionOption(
    [in] DWORD dwOption,
    [in] LPVOID pBuffer,
    [in] DWORD dwBufferLength,
    [out] DWORD *pdwBufferLength,
    [in] DWORD dwReserved
);

Sets options for the current Internet session.

dwOption
Unsigned long integer value containing the session options to be retrieved. Currently, URL monikers support only the URLMON_OPTION_USERAGENT value, which retrieves the current user agent string.
pBuffer
Address of the buffer containing the new session settings.
dwBufferLength
Double-word value containing the size of pBuffer.
pdwBufferLength
Address of a double-word value containing the size of the data stored in buffer or the size required to store the data if the buffer size was insufficient.
dwReserved
Reserved for future use. Must be set to zero.

UrlMkSetSessionOption

HRESULT UrlMkSetSessionOption(
    [in] DWORD dwOption,
    [in] LPVOID pBuffer,
    [in] DWORD dwBufferLength,
    [in] DWORD dwReserved
);

Sets options for the current Internet session.

dwOption
Session option to be set. Can be one of the following values:
INTERNET_OPTION_PROXY Sets the proxy settings. pBuffer must contain a INTERNET_PROXY_INFO structure. INTERNET_OPTION_PROXY and INTERNET_PROXY_INFO are defined in the wininet.h file. For more information, see the Microsoft Win32 Internet Function Reference.
INTERNET_OPTION_REFRESH Sets the value that determines if the proxy information can be reread from the registry. The value TRUE indicates that the proxy information can be reread from the registry. For more information on this value, see the Microsoft Win32 Internet Function Reference.
pBuffer
Buffer containing the new session settings.
dwBufferLength
Size of pBuffer.
dwReserved
Reserved for future use. Must be set to zero.

This function maps directly to the Windows® Internet function InternetSetOption, although UrlMkSetSessionOption allows only global options to be set.

To use this function, the client code must include the Wininet.h header file, which declares values for the dwOption parameter and structures for the pBuffer parameter.

URLOpenBlockingStream

HRESULT URLOpenBlockingStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    LPSTREAM *ppStream,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a blocking type stream object from a URL and downloads the data from the Internet. When the data is downloaded, the client application or control can read it using the IStream::Read method.

pCaller
Address of the controlling IUnknown interface. If the client application or control is not a COM object or ActiveX control, the parameter can be set to NULL.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
ppStream
Address of the IStream interface on the stream object created by this function. The caller can read from the stream as soon as it has this pointer.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface. Can be set to NULL.

This function is synchronous and will only return after all of the data has been downloaded from the Internet.

URLOpenBlockingStream calls the IBindStatusCallback::OnProgress method (if provided) on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call.

URLOpenPullStream

HRESULT URLOpenPullStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a pull type stream object from a URL.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface, on which URLOpenPullStream calls IBindStatusCallback::OnDataAvailable when data arrives from the Internet. IBindStatusCallback::OnDataAvailable can return E_ABORT to abort the download.

The pull model is slightly more cumbersome than the push model, but it allows the client to control the amount of Internet access for the download.

The data is downloaded from the Internet on demand. If not enough data is available locally to satisfy the requests, the IStream::Read call will not block until enough data has arrived. Instead, IStream::Read immediately returns E_PENDING, and URLOpenPullStream requests the next packet of data from the Internet server.

URLOpenStream

HRESULT URLOpenStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a push type stream object from a URL.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface, on which URLOpenStream calls IBindStatusCallback::OnDataAvailable when data arrives from the Internet. IBindStatusCallback::OnDataAvailable can return E_ABORT to abort the download.

The data is downloaded from the Internet as fast as possible. When data is available, it is pushed at the client through a notification callback.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.