CBindStatusCallback 类

项目
10/17/2023

此类实现 IBindStatusCallback 接口。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

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>

参数

T
包含收到数据时要调用的函数的类。

nBindFlags
指定 GetBindInfo 返回的绑定标志。默认实现将绑定设置为异步，检索数据/对象的最新版本，并且不将检索到的数据存储在磁盘缓存中。

成员

公共构造函数

名称	描述
CBindStatusCallback::CBindStatusCallback	构造函数。
CBindStatusCallback::~CBindStatusCallback	析构函数。

公共方法

名称	描述
CBindStatusCallback::Download	用于启动下载进程、创建 `CBindStatusCallback` 对象和调用 `StartAsyncDownload` 的静态方法。
CBindStatusCallback::GetBindInfo	由异步名字对象调用，以请求有关要创建的绑定类型的信息。
CBindStatusCallback::GetPriority	由异步名字对象调用，以获取绑定操作的优先级。 ATL 实现返回 `E_NOTIMPL`。
CBindStatusCallback::OnDataAvailable	调用以在数据可用时向应用程序提供数据。读取数据，然后调用传递给它的函数来使用数据。
CBindStatusCallback::OnLowResource	当资源不足时调用。 ATL 实现返回 S_OK。
CBindStatusCallback::OnObjectAvailable	由异步名字对象调用，以将对象接口指针传递给应用程序。 ATL 实现返回 S_OK。
CBindStatusCallback::OnProgress	调用以指示数据下载进程的进度。 ATL 实现返回 S_OK。
CBindStatusCallback::OnStartBinding	启动绑定时调用。
CBindStatusCallback::OnStopBinding	停止异步数据传输时调用。
CBindStatusCallback::StartAsyncDownload	将可用字节数和已读取的字节数初始化为零，从 URL 创建推送类型的流对象，并在数据可用时调用 `OnDataAvailable`。

公共数据成员

“属性”	描述
CBindStatusCallback::m_dwAvailableToRead	可读取的字节数。
CBindStatusCallback::m_dwTotalRead	已读取的字节总数。
CBindStatusCallback::m_pFunc	指向数据可用时调用的函数的指针。
CBindStatusCallback::m_pT	指向请求异步数据传输的对象的指针。
CBindStatusCallback::m_spBindCtx	指向当前绑定操作的 IBindCtx 接口的指针。
CBindStatusCallback::m_spBinding	指向当前绑定操作的 `IBinding` 接口的指针。
CBindStatusCallback::m_spMoniker	指向要使用的 URL 的 IMoniker 接口的指针。
CBindStatusCallback::m_spStream	指向用于数据传输的 IStream 接口的指针。

注解

CBindStatusCallback 类实现 IBindStatusCallback 接口。 IBindStatusCallback 必须由应用程序实现，以便它可以接收来自异步数据传输的通知。系统提供的异步名字对象使用 IBindStatusCallback 方法来发送和接收有关与对象相互进行的异步数据传输的信息。

通常，CBindStatusCallback 对象与特定的绑定操作相关联。例如，在 ASYNC 示例中，当你设置 URL 属性时，它会在 Download 调用中创建一个 CBindStatusCallback 对象：

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;
}

获得数据后，异步名字对象将使用回调函数 OnData 来调用你的应用程序。异步名字对象由系统提供。

继承层次结构

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

要求

标头：atlctl.h

CBindStatusCallback::CBindStatusCallback

构造函数。

CBindStatusCallback();

备注

创建一个对象以接收有关异步数据传输的通知。通常为每个绑定操作创建一个对象。

构造函数还会将 m_pT 和 m_pFunc 初始化为 NULL。

CBindStatusCallback::~CBindStatusCallback

析构函数。

~CBindStatusCallback();

注解

释放所有已分配的资源。

CBindStatusCallback::Download

创建一个 CBindStatusCallback 对象并调用 StartAsyncDownload 以开始从指定的 URL 异步下载数据。

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

参数

pT
[in] 指向请求异步数据传输的对象的指针。 CBindStatusCallback 对象在此对象的类中模板化。

pFunc
[in] 指向接收读取的数据的函数的指针。该函数是对象的 T 类型类的成员。有关语法和示例，请参阅 StartAsyncDownload。

bstrURL
[in] 要从中获取数据的 URL。可以是任何有效 URL 或文件名。不能为 NULL。例如：

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

pUnkContainer
[in] 容器的 IUnknown。默认情况下为 NULL。

bRelative
[in] 指示 URL 是相对还是绝对 URL 的标志。默认为 FALSE，即 URL 是绝对 URL。

返回值

标准 HRESULT 值之一。

备注

每当数据可用时，它都会通过 OnDataAvailable 发送到对象。 OnDataAvailable 读取数据，并调用 pFunc 指向的函数（例如，存储数据或将其输出到屏幕）。

CBindStatusCallback::GetBindInfo

调用以告知名字对象如何进行绑定。

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

参数

pgrfBSCF
[out] 指向 BINDF 枚举值的指针，这些值指示如何执行绑定操作。默认使用以下枚举值进行设置：

BINDF_ASYNCHRONOUS：异步下载。

BINDF_ASYNCSTORAGE：OnDataAvailable 在数据尚不可用时返回 E_PENDING，而不是阻塞到数据可用为止。

BINDF_GETNEWESTVERSION：绑定操作应检索最新版本的数据。

BINDF_NOWRITECACHE：绑定操作不应将检索到的数据存储在磁盘缓存中。

pbindinfo
[in, out] 指向 BINDINFO 结构的指针，该结构提供有关对象希望如何进行绑定的详细信息。

返回值

标准 HRESULT 值之一。

备注

默认实现将绑定设置为异步并使用数据推送模型。在数据推送模型中，名字对象驱动异步绑定操作，并在有新数据可用时持续通知客户端。

CBindStatusCallback::GetPriority

由异步名字对象调用，以获取绑定操作的优先级。

STDMETHOD(GetPriority)(LONG* pnPriority);

参数

pnPriority
[out] LONG 变量的地址，该变量在成功时接收优先级。

返回值

返回 E_NOTIMPL。

CBindStatusCallback::m_dwAvailableToRead

可用于存储可读取的字节数。

DWORD m_dwAvailableToRead;

注解

在 StartAsyncDownload 中初始化为零。

CBindStatusCallback::m_dwTotalRead

在异步数据传输中读取的累积总字节数。

DWORD m_dwTotalRead;

备注

每次调用 OnDataAvailable 时按实际读取的字节数递增。在 StartAsyncDownload 中初始化为零。

CBindStatusCallback::m_pFunc

m_pFunc 指向的函数由 OnDataAvailable 在读取可用数据后调用（例如，存储数据或将其输出到屏幕）。

ATL_PDATAAVAILABLE m_pFunc;

注解

m_pFunc 指向的函数是对象类的成员，其语法如下：

void Function_Name(
   CBindStatusCallback<T>* pbsc,
   BYTE* pBytes,
   DWORD dwSize
   );

CBindStatusCallback::m_pT

指向请求异步数据传输的对象的指针。

T* m_pT;

注解

CBindStatusCallback 对象在此对象的类中模板化。

CBindStatusCallback::m_spBindCtx

指向 IBindCtx 接口的指针，该接口提供对绑定上下文（存储有关特定名字对象绑定操作的信息的对象）的访问。

CComPtr<IBindCtx> m_spBindCtx;

注解

在 StartAsyncDownload 中初始化。

CBindStatusCallback::m_spBinding

指向当前绑定操作的 IBinding 接口的指针。

CComPtr<IBinding> m_spBinding;

备注

在 OnStartBinding 中初始化，在 OnStopBinding 中释放。

CBindStatusCallback::m_spMoniker

指向要使用的 URL 的 IMoniker 接口的指针。

CComPtr<IMoniker> m_spMoniker;

备注

在 StartAsyncDownload 中初始化。

CBindStatusCallback::m_spStream

指向当前绑定操作的 IStream 接口的指针。

CComPtr<IStream> m_spStream;

注解

当 BCSF 标志为 BCSF_FIRSTDATANOTIFICATION 时从 STGMEDIUM 结构在 OnDataAvailable 中初始化，当 BCSF 标志为 BCSF_LASTDATANOTIFICATION 时释放。

CBindStatusCallback::OnDataAvailable

系统提供的异步名字对象调用 OnDataAvailable 以在数据可用时向对象提供数据。

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

参数

grfBSCF
[in] 一个 BSCF 枚举值。以下一项或多项：BSCF_FIRSTDATANOTIFICATION、BSCF_INTERMEDIARYDATANOTIFICATION 或 BSCF_LASTDATANOTIFICATION。

dwSize
[in] 自绑定开始以来可用的累计数据量（以字节为单位）。可为零，表示不相关的数据量，或者没有具体的可用数据量。

pformatetc
[in] 指向包含可用数据格式的 FORMATETC 结构的指针。如果没有格式，则可为 CF_NULL。

pstgmed
[in] 指向包含现在可用的实际数据的 STGMEDIUM 结构的指针。

返回值

标准 HRESULT 值之一。

备注

OnDataAvailable 读取数据，然后调用对象类的方法（例如，存储数据或将其输出到屏幕）。有关详细信息，请参阅 CBindStatusCallback::StartAsyncDownload。

CBindStatusCallback::OnLowResource

当资源不足时调用。

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

参数

dwReserved
保留。

返回值

返回 S_OK。

CBindStatusCallback::OnObjectAvailable

由异步名字对象调用，以将对象接口指针传递给应用程序。

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

参数

riid
所请求接口的接口标识符。未使用。

punk
IUnknown 接口的地址。未使用。

返回值

返回 S_OK。

CBindStatusCallback::OnProgress

调用以指示数据下载进程的进度。

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

参数

ulProgress
无符号长整型。未使用。

ulProgressMax
未使用的无符号长整型。

ulStatusCode
无符号长整型。未使用。

szStatusText
字符串值的地址。未使用。

返回值

返回 S_OK。

CBindStatusCallback::OnStartBinding

将数据成员 m_spBinding 设置为 pBinding 中的 IBinding 指针。

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

参数

dwReserved
保留供将来使用。

pBinding
[in] 当前绑定操作的 IBinding 接口的地址。不能为 NULL。客户端应在此指针上调用 AddRef 以保留对绑定对象的引用。

CBindStatusCallback::OnStopBinding

释放数据成员 m_spBinding 中的 IBinding 指针。

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

参数

hresult
从绑定操作返回的状态代码。

szError
字符串值的地址。未使用。

备注

由系统提供的异步名字对象调用，以指示绑定操作结束。

CBindStatusCallback::StartAsyncDownload

开始从指定的 URL 异步下载数据。

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

参数

pT
[in] 指向请求异步数据传输的对象的指针。 CBindStatusCallback 对象在此对象的类中模板化。

pFunc
[in] 指向接收读取的数据的函数的指针。该函数是对象的 T 类型类的成员。有关语法和示例，请参阅“注解”。

bstrURL
[in] 要从中获取数据的 URL。可以是任何有效 URL 或文件名。不能为 NULL。例如：

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

pUnkContainer
[in] 容器的 IUnknown。默认情况下为 NULL。

bRelative
[in] 指示 URL 是相对还是绝对 URL 的标志。默认为 FALSE，即 URL 是绝对 URL。

返回值

标准 HRESULT 值之一。

备注

每当数据可用时，它都会通过 OnDataAvailable 发送到对象。 OnDataAvailable 读取数据，并调用 pFunc 指向的函数（例如，存储数据或将其输出到屏幕）。

pFunc 指向的函数是对象类的成员，其语法如下：

void Function_Name(
    CBindStatusCallback<T>* pbsc,
    BYTE* pBytes,
    DWORD dwSize);

在以下示例（摘自 ASYNC 示例）中，函数 OnData 将收到的数据写入文本框中。

示例

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!!!"));
      }
   }
}

另请参阅

类概述

通过

CBindStatusCallback 类

语法

参数

成员

公共构造函数

公共方法

公共数据成员

注解

继承层次结构

要求

CBindStatusCallback::CBindStatusCallback

备注

CBindStatusCallback::~CBindStatusCallback

注解

CBindStatusCallback::Download

参数

返回值

备注

CBindStatusCallback::GetBindInfo

参数

返回值

备注

CBindStatusCallback::GetPriority

参数

返回值

CBindStatusCallback::m_dwAvailableToRead

注解

CBindStatusCallback::m_dwTotalRead

备注

CBindStatusCallback::m_pFunc

注解

CBindStatusCallback::m_pT

注解

CBindStatusCallback::m_spBindCtx

注解

CBindStatusCallback::m_spBinding

备注

CBindStatusCallback::m_spMoniker

备注

CBindStatusCallback::m_spStream

注解

CBindStatusCallback::OnDataAvailable

参数

返回值

备注

CBindStatusCallback::OnLowResource

参数

返回值

CBindStatusCallback::OnObjectAvailable

参数

返回值

CBindStatusCallback::OnProgress

参数

返回值

CBindStatusCallback::OnStartBinding

参数

CBindStatusCallback::OnStopBinding

参数

备注

CBindStatusCallback::StartAsyncDownload

参数

返回值

备注

示例

另请参阅

反馈

其他资源