CBindStatusCallback Class

 

The latest version of this topic can be found at CBindStatusCallback Class.

This class implements the IBindStatusCallback interface.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

template <class T,
    int nBindFlags = BINDF_ASYNCHRONOUS |   BINDF_ASYNCSTORAGE | BINDF_GETNEWESTVERSION | BINDF_NOWRITECACHE>  
class ATL_NO_VTABLE CBindStatusCallback : public CComObjectRootEx
 <T ::_ThreadModel::ThreadModelNoCS>,
    public IBindStatusCallbackImpl<T>

Parameters

T
Your class containing the function that will be called as the data is received.

nBindFlags
Specifies the bind flags that are returned by GetBindInfo. The default implementation sets the binding to be asynchronous, retrieves the newest version of the data/object, and does not store retrieved data in the disk cache.

Members

Public Constructors

Name	Description
CBindStatusCallback::CBindStatusCallback	The constructor.
CBindStatusCallback::~CBindStatusCallback	The destructor.

Public Methods

Name	Description
CBindStatusCallback::Download	Static method that starts the download process, creates a CBindStatusCallback object, and calls StartAsyncDownload.
CBindStatusCallback::GetBindInfo	Called by the asynchronous moniker to request information on the type of bind to be created.
CBindStatusCallback::GetPriority	Called by the asynchronous moniker to get the priority of the bind operation. The ATL implementation returns E_NOTIMPL.
CBindStatusCallback::OnDataAvailable	Called to provide data to your application as it becomes available. Reads the data, then calls the function passed to it to use the data.
CBindStatusCallback::OnLowResource	Called when resources are low. The ATL implementation returns S_OK.
CBindStatusCallback::OnObjectAvailable	Called by the asynchronous moniker to pass an object interface pointer to your application. The ATL implementation returns S_OK.
CBindStatusCallback::OnProgress	Called to indicate the progress of a data downloading process. The ATL implementation returns S_OK.
CBindStatusCallback::OnStartBinding	Called when binding is started.
CBindStatusCallback::OnStopBinding	Called when the asynchronous data transfer is stopped.
CBindStatusCallback::StartAsyncDownload	Initializes the bytes available and bytes read to zero, creates a push-type stream object from a URL, and calls OnDataAvailable every time data is available.

Public Data Members

Name	Description
CBindStatusCallback::m_dwAvailableToRead	Number of bytes available to read.
CBindStatusCallback::m_dwTotalRead	Total number of bytes read.
CBindStatusCallback::m_pFunc	Pointer to the function called when data is available.
CBindStatusCallback::m_pT	Pointer to the object requesting the asynchronous data transfer.
CBindStatusCallback::m_spBindCtx	Pointer to the IBindCtx interface for the current bind operation.
CBindStatusCallback::m_spBinding	Pointer to the IBinding interface for the current bind operation.
CBindStatusCallback::m_spMoniker	Pointer to the IMoniker interface for the URL to use.
CBindStatusCallback::m_spStream	Pointer to the IStream interface for the data transfer.

Remarks

The CBindStatusCallback class implements the IBindStatusCallback interface. IBindStatusCallback must be implemented by your application so it can receive notifications from an asynchronous data transfer. The asynchronous moniker provided by the system uses IBindStatusCallback methods to send and receive information about the asynchronous data transfer to and from your object.

Typically, the CBindStatusCallback object is associated with a specific bind operation. For example, in the ASYNC sample, when you set the URL property, it creates a CBindStatusCallback object in the call to Download:

   STDMETHOD(put_URL)(BSTR newVal)
   {
      HRESULT hResult = E_UNEXPECTED;

      ATLTRACE(_T("IATLAsync::put_URL\n"));
      m_bstrURL = newVal;

      if (::IsWindow(m_EditCtrl.m_hWnd))
      {
         ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0,  (LPARAM)_T(""));
         hResult = CBindStatusCallback<CATLAsync>::Download(this, &CATLAsync::OnData, 
            m_bstrURL, m_spClientSite, FALSE);
      }

      return hResult;
   }

The asynchronous moniker uses the callback function OnData to call your application when it has data. The asynchronous moniker is provided by the system.

Inheritance Hierarchy

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

Requirements

Header: atlctl.h

CBindStatusCallback::CBindStatusCallback

The constructor.

CBindStatusCallback();

Remarks

Creates an object to receive notifications concerning the asynchronous data transfer. Typically, one object is created for each bind operation.

The constructor also initializes m_pT and m_pFunc to NULL.

CBindStatusCallback::~CBindStatusCallback

The destructor.

~CBindStatusCallback();

Remarks

Frees all allocated resources.

CBindStatusCallback::Download

Creates a CBindStatusCallback object and calls StartAsyncDownload to start downloading data asynchronously from the specified URL.

static HRESULT Download(  
    T* pT,
    ATL_PDATAAVAILABLE pFunc,
    BSTR bstrURL,
    IUnknown* pUnkContainer = NULL,
    BOOL bRelative = FALSE);

Parameters

pT
[in] A pointer to the object requesting the asynchronous data transfer. The CBindStatusCallback object is templatized on this object's class.

pFunc
[in] A pointer to the function that receives the data that is read. The function is a member of your object's class of type T. See StartAsyncDownload for syntax and an example.

bstrURL
[in] The URL to obtain data from. Can be any valid URL or file name. Cannot be NULL. For example:

CComBSTR mybstr =_T("https://somesite/data.htm")

pUnkContainer
[in] The IUnknown of the container. NULL by default.

bRelative
[in] A flag indicating whether the URL is relative or absolute. FALSE by default, meaning the URL is absolute.

Return Value

One of the standard HRESULT values.

Remarks

Every time data is available it is sent to the object through OnDataAvailable. OnDataAvailable reads the data and calls the function pointed to by pFunc (for example, to store the data or print it to the screen).

CBindStatusCallback::GetBindInfo

Called to tell the moniker how to bind.

STDMETHOD(GetBindInfo)(
    DWORD* pgrfBSCF,
    BINDINFO* pbindinfo);

Parameters

pgrfBSCF
[out] A pointer to BINDF enumeration values indicating how the bind operation should occur. By default, set with the following enumeration values:

BINDF_ASYNCHRONOUS Asynchronous download.

BINDF_ASYNCSTORAGE OnDataAvailable returns E_PENDING when data is not yet available rather than blocking until data is available.

BINDF_GETNEWESTVERSION The bind operation should retrieve the newest version of the data.

BINDF_NOWRITECACHE The bind operation should not store retrieved data in the disk cache.

pbindinfo
[in, out] A pointer to the BINDINFO structure giving more information about how the object wants binding to occur.

Return Value

One of the standard HRESULT values.

Remarks

The default implementation sets the binding to be asynchronous and to use the data-push model. In the data-push model, the moniker drives the asynchronous bind operation and continuously notifies the client whenever new data is available.

CBindStatusCallback::GetPriority

Called by the asynchronous moniker to get the priority of the bind operation.

STDMETHOD(GetPriority)(LONG* pnPriority);

Parameters

pnPriority
[out] Address of the LONG variable that, on success, receives the priority.

Return Value

Returns E_NOTIMPL.

CBindStatusCallback::m_dwAvailableToRead

Can be used to store the number of bytes available to be read.

DWORD m_dwAvailableToRead;

Remarks

Initialized to zero in StartAsyncDownload.

CBindStatusCallback::m_dwTotalRead

The cumulative total of bytes read in the asynchronous data transfer.

DWORD m_dwTotalRead;

Remarks

Incremented every time OnDataAvailable is called by the number of bytes actually read. Initialized to zero in StartAsyncDownload.

CBindStatusCallback::m_pFunc

The function pointed to by m_pFunc is called by OnDataAvailable after it reads the available data (for example, to store the data or print it to the screen).

ATL_PDATAAVAILABLE m_pFunc;

Remarks

The function pointed to by m_pFunc is a member of your object's class and has the following syntax:

void Function_Name(

CBindStatusCallback<T>* pbsc,

BYTE* pBytes,

DWORD dwSize

);

CBindStatusCallback::m_pT

A pointer to the object requesting the asynchronous data transfer.

T* m_pT;

Remarks

The CBindStatusCallback object is templatized on this object's class.

CBindStatusCallback::m_spBindCtx

A pointer to an IBindCtx interface that provides access to the bind context (an object that stores information about a particular moniker binding operation).

CComPtr<IBindCtx> m_spBindCtx;

Remarks

Initialized in StartAsyncDownload.

CBindStatusCallback::m_spBinding

A pointer to the IBinding interface of the current bind operation.

CComPtr<IBinding> m_spBinding;

Remarks

Initialized in OnStartBinding and released in OnStopBinding.

CBindStatusCallback::m_spMoniker

A pointer to the IMoniker interface for the URL to use.

CComPtr<IMoniker> m_spMoniker;

Remarks

Initialized in StartAsyncDownload.

CBindStatusCallback::m_spStream

A pointer to the IStream interface of the current bind operation.

CComPtr<IStream> m_spStream;

Remarks

Initialized in OnDataAvailable from the STGMEDIUM structure when the BCSF flag is BCSF_FIRSTDATANOTIFICATION and released when the BCSF flag is BCSF_LASTDATANOTIFICATION.

CBindStatusCallback::OnDataAvailable

The system-supplied asynchronous moniker calls OnDataAvailable to provide data to the object as it becomes available.

STDMETHOD(  
    OnDataAvailable)(DWORD grfBSCF,
    DWORD dwSize,
    FORMATETC* /* pformatetc */,
    STGMEDIUM* pstgmed);

Parameters

grfBSCF
[in] A BSCF enumeration value. One or more of the following: BSCF_FIRSTDATANOTIFICATION, BSCF_INTERMEDIARYDATANOTIFICATION, or BSCF_LASTDATANOTIFICATION.

dwSize
[in] The cumulative amount (in bytes) of data available since the beginning of the binding. Can be zero, indicating that the amount of data is not relevant or that no specific amount became available.

pformatetc
[in] Pointer to the FORMATETC structure that contains the format of the available data. If there is no format, can be CF_NULL.

pstgmed
[in] Pointer to the STGMEDIUM structure that holds the actual data now available.

Return Value

One of the standard HRESULT values.

Remarks

OnDataAvailable reads the data, then calls a method of your object's class (for example, to store the data or print it to the screen). See CBindStatusCallback::StartAsyncDownload for details.

CBindStatusCallback::OnLowResource

Called when resources are low.

STDMETHOD(OnLowResource)(DWORD /* dwReserved */);

Parameters

dwReserved
Reserved.

Return Value

Returns S_OK.

CBindStatusCallback::OnObjectAvailable

Called by the asynchronous moniker to pass an object interface pointer to your application.

STDMETHOD(OnObjectAvailable)(REFID /* riid */, IUnknown* /* punk */);

Parameters

riid
Interface identifier of the requested interface. Unused.

punk
Address of the IUnknown interface. Unused.

Return Value

Returns S_OK.

CBindStatusCallback::OnProgress

Called to indicate the progress of a data downloading process.

STDMETHOD(OnProgress)(
    ULONG /* ulProgress */,
    ULONG /* ulProgressMax */,
    ULONG /* ulStatusCode */,
    LPCWSTRONG /* szStatusText */);

Parameters

ulProgress
Unsigned long integer. Unused.

ulProgressMax
Unsigned long integer Unused.

ulStatusCode
Unsigned long integer. Unused.

szStatusText
Address of a string value. Unused.

Return Value

Returns S_OK.

CBindStatusCallback::OnStartBinding

Sets the data member m_spBinding to the IBinding pointer in pBinding.

STDMETHOD(OnStartBinding)(DWORD /* dwReserved */, IBinding* pBinding);

Parameters

dwReserved
Reserved for future use.

pBinding
[in] Address of the IBinding interface of the current bind operation. This cannot be NULL. The client should call AddRef on this pointer to keep a reference to the binding object.

CBindStatusCallback::OnStopBinding

Releases the IBinding pointer in the data member m_spBinding.

STDMETHOD(OnStopBinding)(HRESULT hresult, LPCWSTR /* szError */);

Parameters

hresult
Status code returned from the bind operation.

szStatusText
Address of a string value Unused.

Remarks

Called by the system-supplied asynchronous moniker to indicate the end of the bind operation.

CBindStatusCallback::StartAsyncDownload

Starts downloading data asynchronously from the specified URL.

HRESULT StartAsyncDownload(  
    T* pT,
    ATL_PDATAAVAILABLE pFunc,
    BSTR bstrURL,
    IUnknown* pUnkContainer = NULL,
    BOOL bRelative = FALSE);

Parameters

pT
[in] A pointer to the object requesting the asynchronous data transfer. The CBindStatusCallback object is templatized on this object's class.

pFunc
[in] A pointer to the function that receives the data being read. The function is a member of your object's class of type T. See Remarks for syntax and an example.

bstrURL
[in] The URL to obtain data from. Can be any valid URL or file name. Cannot be NULL. For example:

CComBSTR mybstr =_T("https://somesite/data.htm")

pUnkContainer
[in] The IUnknown of the container. NULL by default.

bRelative
[in] A flag indicating whether the URL is relative or absolute. FALSE by default, meaning the URL is absolute.

Return Value

One of the standard HRESULT values.

Remarks

Every time data is available it is sent to the object through OnDataAvailable. OnDataAvailable reads the data and calls the function pointed to by pFunc (for example, to store the data or print it to the screen).

The function pointed to by pFunc is a member of your object's class and has the following syntax:

void Function_Name(

CBindStatusCallback<T>* pbsc ,

BYTE* pBytes ,

DWORD dwSize

);

In the following example (taken from the ASYNC sample), the function OnData writes the received data into a text box.

Example

   void OnData(CBindStatusCallback<CATLAsync>* , BYTE* pBytes, DWORD /*cBytes*/)
   {
      ATLTRACE(_T("OnData called\n"));

      m_bstrText.Append((LPCSTR)pBytes);
      if (::IsWindow(m_EditCtrl.m_hWnd))
      {
         USES_CONVERSION;
         _ATLTRY {
            ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0, 
               (LPARAM)(LPCTSTR)COLE2CT((BSTR)m_bstrText));
         }
         _ATLCATCH( e ) {
            e; // unused
            // COLE2CT threw an exception!
            ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0, 
               (LPARAM)_T("Could not allocate enough memory!!!"));
         }
      }
   }

See Also

Class Overview