URLOpenStream

Creates a push-type stream object from a URL. The data is downloaded from the Internet as fast as possible. Every time data is available, it is "pushed" at the client through a notification callback.

HRESULT URLOpenStream(
  LPUNKNOWN pCaller,  // Caller's controlling IUnknown 
  PCWSTR szURL,       // URL to be converted to stream
  DWORD dwResv,       // Reserved for future use
  LPBINDSTATUSCALLBACK lpfnCB
                      // Caller's IBindStatusCallback 
);
 

Parameters

pCaller

[in] Pointer to the caller's controlling IUnknown. If the caller is not an ActiveX component, this value may be set to NULL.

szURL

[in] Pointer to the URL to be converted to a stream object. Cannot be NULL.

dwResv

[in] Reserved for future use; must be zero.

lpfnCB

[in] Pointer to caller's IBindStatusCallback interface.

Return Values

This function returns the same values as IBindHost::MonikerBindToStorage.

Remarks

If pCaller is non-NULL, the caller is a COM object that is contained in another component, such as an ActiveX Control in the context of an HTML page.In this case, the function attempts the download in the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.

URLOpenStream calls IBindStatusCallback::OnDataAvailable every time data arrives from the Internet. OnDataAvailable can return E_ABORT to abort the download. When the callback is invoked and the pstm member of the STGMEDIUM structure is not NULL, the caller can read from the stream the amount of data specified in the dwSize argument passed with the OnDataAvailable call. If the caller does not read the full amount or does not call ISequentialStream::Read at all, OnDataAvailable is still called the next time data arrives, as long the grfBSCF flags do not indicate BINDF_LASTDATANOTIFICATION. In that case, no more data is downloaded. Any data that is not read at any given time is still available the next time OnDataAvailable is called.

The logic in the following code fragment is a typical implementation of OnDataAvailable as it is used by the URLOpenStream function:

HRESULT MyBindStatusCallback::OnDataAvailable(DWORD grfBSCF, DWORD dwSize, ..., STGMEDIUM * pstgmed)
{
    if(dwSize < sizeof(BITMAPINFOHEADER))
        return(NOERROR);  // not enough has been read yet, just return
    if(!g_bGotInfoHeader) // did we get info before?
    {
       // No, go ahead, read now...
        DWORD dwRead;
        HRESULT hr = pstgmed->pstm->Read( &bmih, sizeof(bmih), &dwRead);
        if( SUCCEEDED(hr) )
        {
            // now we got it... we can return
            g_bGotInfoHeader = TRUE;
            return(hr);
        }
    }
}
 

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in urlmon.h.

See Also

IBindStatusCallback, IBindStatusCallback::OnDataAvailable, IStream, ISequentialStream, ISequentialStream::Read