template< class T >
class CBindStatusCallback :
public CComObjectRootEx<T::_ThreadModel::ThreadModelNoCS>,
public IBindStatusCallbackImpl<T>
Parameters
T Your class, derived from IBindStatusCallbackImpl.
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 strURL) { ... m_bstrURL = strURL; CBindStatusCallback<CATLAsync>::Download(this, OnData, m_bstrURL, m_spClientSite, FALSE); return S_OK; }
The asynchronous moniker uses the callback function OnData to call your application when it has data. The asynchronous moniker is provided by the system.
See the ActiveX SDK for a description of IBindStatusCallback.
#include <atlctl.h>
IBindStatusCallback Methods | |
GetBindInfo | Called by the asynchronous moniker to request information on the type of bind to be created. |
GetPriority | Called by the asynchronous moniker to get the priority of the bind operation. The ATL implementation returns E_NOTIMPL. |
OnLowResource | Called when resources are low. The ATL implementation returns S_OK. |
OnObjectAvailable | Called by the asynchronous moniker to pass an object interface pointer to your application. The ATL implementation returns S_OK. |
OnProgress | Called to indicate the progress of a data downloading process. The ATL implementation returns S_OK. |
OnStartBinding | Called when binding is started. |
OnStopBinding | Called when the asynchronous data transfer is stopped. |
Class Methods | |
CBindStatusCallback | Constructor. |
Download | Starts the download process, creates a CBindStatusCallback object, and calls StartAsyncDownload. |
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. |
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. |
Data Members | |
m_dwAvailableToRead | Number of bytes available to read. |
m_dwTotalRead | Total number of bytes read. |
m_pFunc | Pointer to the function called when data is available. |
m_pT | Pointer to the object requesting the asynchronous data transfer. |
m_spBindCtx | Pointer to the IBindCtx interface for the current bind operation. |
m_spBinding | Pointer to the IBinding interface for the current bind operation. |
m_spMoniker | Pointer to the IMoniker interface for the URL to use. |
m_spStream | Pointer to the IStream interface for the data transfer. |
CBindStatusCallback( );
Remarks
The constructor. 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 Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload
HRESULT Download( T* pT, ATL_PDATAAVAILABLE pFunc, BSTR bstrURL, IUnknown* pUnkContainer = NULL, BOOL bRelative = FALSE );
Return Value
One of the standard HRESULT values.
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 StartAyncDownload for syntax and an example.
bstrURL [in] The URL to obtain data from. Can be any valid URL or filename. Cannot be NULL. For example:
CComBSTR mybstr =_T("http://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.
Remarks
Creates a CBindStatusCallback object and calls StartAsyncDownload to start downloading data asynchronously from the specified URL. 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 Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload
HRESULT GetBindInfo( DWORD* pgrfBSCF, BINDINFO* pbindinfo );
Return Value
One of the standard HRESULT values.
Parameters
pgrfBSCF [out] A pointer to BINDF enumeration values indicating how the bind operation should occur. By default, set with the following enumeration values:
pbindinfo [in, out] A pointer to the BINDINFO structure giving more information about how the object wants binding to occur.
Remarks
Called to tell the moniker how to bind. 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.
See IBindStatusCallback::GetBindInfo in the ActiveX SDK.
CBindStatusCallback Overview | Class Members
HRESULT GetPriority( LONG* pnPriority );
See IBindStatusCallback::GetPriority in the ActiveX SDK.
Remarks
Returns E_NOTIMPL.
CBindStatusCallback Overview | Class Members
HRESULT OnDataAvailable( DWORD grfBSCF, DWORD dwSize, FORMATETC* pformatetc, STGMEDIUM* pstgmed );
Return Value
One of the standard HRESULT values.
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.
Remarks
The system-supplied asynchronous moniker calls OnDataAvailable to provide data to the object as it becomes available.
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 Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload
HRESULT OnLowResource( DWORD dwReserved );
See IBindStatusCallback::OnLowResource in the ActiveX SDK.
Remarks
Returns S_OK.
CBindStatusCallback Overview | Class Members
HRESULT OnObjectAvailable( REFID riid, IUnknown* punk );
See IBindStatusCallback::OnObjectAvailable in the ActiveX SDK.
Remarks
Returns S_OK.
CBindStatusCallback Overview | Class Members
HRESULT OnProgress( ULONG ulProgress, ULONG ulProgressMax, ULONG ulStatusCode, LPCWSTRONG szStatusText );
See IBindStatusCallback::OnProgress in the ActiveX SDK.
Remarks
Returns S_OK.
CBindStatusCallback Overview | Class Members
HRESULT OnStartBinding( DWORD dwReserved, IBinding* pBinding );
See IBindStatusCallback::OnStartBinding in the ActiveX SDK.
Remarks
Sets the data member m_spBinding to the IBinding pointer in pBinding.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::OnStopBinding
HRESULT OnStopBinding( HRESULT hresult, LPCWSTR szError );
See IBindStatusCallback::OnStopBinding in the ActiveX SDK.
Remarks
Releases the IBinding pointer in the data member m_spBinding. Called by the system-supplied asynchronous moniker to indicate the end of the bind operation.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::OnStartBinding
HRESULT StartAsyncDownload( T* pT, ATL_PDATAAVAILABLE pFunc, BSTR bstrURL, BOOL bRelative = FALSE );
Return Value
One of the standard HRESULT values.
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 filename. Cannot be NULL. For example:
CComBSTR mybstr =_T("http://somesite/data.htm")
bRelative [in] A flag indicating whether the URL is relative or absolute. FALSE by default, meaning the URL is absolute.
Remarks
Starts downloading data asynchronously from the specified URL. Everytime 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:
void OnData(CBindStatusCallback<CATLAsync>* pbsc, BYTE* pBytes, DWORD dwSize) { m_bstrText.Append= (LPCSTR)pBytes; if (::IsWindow(m_EditCtrl.m_hWnd)) { USES_CONVERSION; ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0, (LPARAM)OLE2CT((BSTR)m_bstrText)); } }
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::OnDataAvailable
DWORD m_dwAvailableToRead;
Remarks
Can be used to store the number of bytes available to be read. Initialized to zero in StartAsyncDownload.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload
DWORD m_dwTotalRead;
Remarks
The cumulative total of bytes read in the asychronous data transfer. Incremented everytime OnDataAvailable is called by the number of bytes actually read. Initialized to zero in StartAsyncDownload.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload, CBindStatusCallback::OnDataAvailable
ATL_PDATAAVAILABLE m_pFunc;
Remarks
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).
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 Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload, CBindStatusCallback::OnDataAvailable
T* m_pT;
Remarks
A pointer to the object requesting the asynchronous data transfer. The CBindStatusCallback object is templatized on this object's class.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload
CComPtr<IBindCtx> m_spBindCtx;
Remarks
A pointer to an IBindCtx interface that provides access to the bind context (an object that stores information about a particular moniker binding operation). Initialized in StartAsyncDownload.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload, CComPtr
CComPtr<IBinding> m_spBinding;
Remarks
A pointer to the IBinding interface of the current bind operation. Initialized in OnStartBinding and released in OnStopBinding.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::OnStartBinding, CBindStatusCallback::OnStopBinding, CComPtr
CComPtr<IMoniker> m_spMoniker;
Remarks
A pointer to the IMoniker interface for the URL to use. Initialized in StartAsyncDownload.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::StartAsyncDownload, CComPtr
CComPtr<IStream> m_spStream;
Remarks
A pointer to the IStream interface of the current bind operation. Initialized in OnDataAvailable from the STGMEDIUM structure when the BCSF flag is BCSF_FIRSTDATANOTIFICATION and released when the BCSF flag is BCSF_LASTDATANOTIFICATION.
CBindStatusCallback Overview | Class Members
See Also CBindStatusCallback::OnDataAvailable, CComPtr