CAsyncMonikerFile 类

提供功能以在 ActiveX 控件（原为 OLE 控件）中使用异步名字对象。

语法

class CAsyncMonikerFile : public CMonikerFile

成员

公共构造函数

名称	描述
CAsyncMonikerFile::CAsyncMonikerFile	构造 CAsyncMonikerFile 对象。

公共方法

名称	描述
CAsyncMonikerFile::Close	关闭并释放所有资源。
CAsyncMonikerFile::GetBinding	检索指向异步传输绑定的指针。
CAsyncMonikerFile::GetFormatEtc	检索流中的数据格式。
CAsyncMonikerFile::Open	异步打开文件。

受保护方法

名称	描述
CAsyncMonikerFile::CreateBindStatusCallback	创建实现 IBindStatusCallback 的 COM 对象。
CAsyncMonikerFile::GetBindInfo	由 OLE 系统库调用，请求有关要创建的绑定类型的信息。
CAsyncMonikerFile::GetPriority	由 OLE 系统库调用以获取绑定的优先级。
CAsyncMonikerFile::OnDataAvailable	当数据在异步绑定操作期间对客户端可用时，调用该函数以提供数据。
CAsyncMonikerFile::OnLowResource	当资源不足时调用。
CAsyncMonikerFile::OnProgress	调用以指示数据下载进程的进度。
CAsyncMonikerFile::OnStartBinding	当绑定启动时调用。
CAsyncMonikerFile::OnStopBinding	停止异步传输时调用。

备注

派生自 CMonikerFile，而后者又派生自 COleStreamFile，它使用 CAsyncMonikerFileIMoniker 接口异步访问任何数据流，包括从 URL 异步加载文件。 这些文件可以是 ActiveX 控件的数据路径属性。

异步名字对象主要用于 Internet 支持的应用程序和 ActiveX 控件中，以在文件传输期间提供具有响应能力的用户界面。 一个典型例子是使用 CDataPathProperty 为 ActiveX 控件提供异步属性。 CDataPathProperty 对象会重复获取回调，以在长时间的属性交换过程中指示新数据的可用性。

有关如何在 Internet 应用程序中使用异步名字对象和 ActiveX 控件的详细信息，请参阅以下文章：

• Internet 第一步：异步名字对象

• Internet 第一步：ActiveX 控件

继承层次结构

CObject

CFile

COleStreamFile

CMonikerFile

CAsyncMonikerFile

要求

标头：afxole.h

CAsyncMonikerFile::CAsyncMonikerFile

构造 CAsyncMonikerFile 对象。

CAsyncMonikerFile();

注解

它不创建 IBindHost 接口。 仅当 IBindHost 在 Open 成员函数中提供时才使用。

有关 IBindHost 接口的说明，请参阅 Windows SDK。

CAsyncMonikerFile::Close

调用此函数以关闭并释放所有资源。

virtual void Close();

备注

可以在未打开或已经关闭的文件上调用。

CAsyncMonikerFile::CreateBindStatusCallback

创建实现 IBindStatusCallback 的 COM 对象。

virtual IUnknown* CreateBindStatusCallback(IUnknown* pUnkControlling);

参数

pUnkControlling
指向控制未知（外部 IUnknown）或 NULL（如果未使用聚合）的指针。

返回值

如果 pUnkControlling 不是 NULL，则该函数返回在新 COM 对象上支持 IBindStatusCallback 的指向内部 IUnknown 的指针。 如果 pUnkControlling 是 NULL，则该函数返回在新 COM 对象上支持 IBindStatusCallback 的指向 IUnknown 的指针。

备注

CAsyncMonikerFile 需要实现 IBindStatusCallback 的 COM 对象。 MFC 实现此类对象，并且它是可聚合的。 可以重写 CreateBindStatusCallback 以返回自己的 COM 对象。 COM 对象可以通过调用 CreateBindStatusCallback 以及控制 COM 对象的未知情况来聚合 MFC 的实现。 使用 CCmdTarget COM 支持实现的 COM 对象可以使用 CCmdTarget::GetControllingUnknown 检索控制未知。

另外，COM 对象可以通过调用 CreateBindStatusCallback( NULL ) 来委托 MFC 的实现。

CAsyncMonikerFile::Open 调用 CreateBindStatusCallback。

有关异步名字对象和异步绑定的详细信息，请参阅 IBindStatusCallback 接口以及异步绑定和存储如何工作。 有关聚合的讨论，请参阅聚合。 这三个主题都在 Windows SDK 中。

CAsyncMonikerFile::GetBindInfo

从异步名字对象的客户端调用，以告知异步名字对象它希望绑定的方式。

virtual DWORD GetBindInfo() const;

返回值

检索 IBindStatusCallBack 的设置。 有关 IBindStatusCallback 接口的说明，请参阅 Windows SDK。

备注

默认实现将绑定设置为异步，以使用存储介质（流） ，并使用数据推送模型。 如果要更改绑定的行为，请重写此函数。

执行此操作的一个原因是使用数据拉取模型而不是数据推送模型进行绑定。 在数据拉取模型中，客户端驱动绑定操作，名字对象仅在读取时向客户端提供数据。 在数据推送模型中，名字对象驱动异步绑定操作，并在有新数据可用时持续通知客户端。

CAsyncMonikerFile::GetBinding

调用此函数以检索指向异步传输绑定的指针。

IBinding* GetBinding() const;

返回值

指向异步传输开始时提供的 IBinding 接口的指针。 如果出于任何原因无法异步传输，则返回 NULL。

备注

这允许通过 IBinding 接口控制数据传输过程（例如，使用 IBinding::AbortIBinding::Pause 和 IBinding::Resume）。

有关 IBinding 接口的说明，请参阅 Windows SDK。

CAsyncMonikerFile::GetFormatEtc

调用此函数以检索流中的数据格式。

FORMATETC* GetFormatEtc() const;

返回值

针对当前打开的流指向 Windows 结构 FORMATETC 的指针。 如果名字对象未绑定、不是异步，或者异步操作尚未开始，则返回 NULL。

CAsyncMonikerFile::GetPriority

从异步名字对象客户端调用，因为绑定进程开始接收为绑定操作的线程提供的优先级。

virtual LONG GetPriority() const;

返回值

将发生的异步传输优先级。 标准线程优先级标记之一：THREAD_PRIORITY_ABOVE_NORMAL、 THREAD_PRIORITY_BELOW_NORMAL、 THREAD_PRIORITY_HIGHEST、 THREAD_PRIORITY_IDLE、 THREAD_PRIORITY_LOWEST、 THREAD_PRIORITY_NORMAL 和 THREAD_PRIORITY_TIME_CRITICAL。 有关这些值的说明，请参阅 Windows 函数 SetThreadPriority。

备注

不应直接调用 GetPriority。 由默认实现返回 THREAD_PRIORITY_NORMAL。

CAsyncMonikerFile::OnDataAvailable

异步绑定操作期间，异步名字对象调用 OnDataAvailable 以在数据可用时向客户端提供数据。

virtual void OnDataAvailable(DWORD dwSize, DWORD bscfFlag);

参数

dwSize
自绑定开始以来可用的累计数据量（以字节为单位）。 可以是零，表示数据量与操作无关，或者没有具体的数量。

bscfFlag
一个 BSCF 枚举值。 可以是如下一个或多个值：

• BSCF_FIRSTDATANOTIFICATION 为给定绑定操作标识对 OnDataAvailable 的第一次调用。

• BSCF_INTERMEDIATEDATANOTIFICATION 为绑定操作标识对 OnDataAvailable 的中间调用。

• BSCF_FIRSTDATANOTIFICATION 为给定绑定操作标识对 OnDataAvailable 的最后调用。

备注

此函数的默认实现不执行任何操作。 有关示例实现，请参见下面的“示例”部分。

示例

void CMyMoniker::OnDataAvailable(DWORD dwSize, DWORD bscfFlag)
{
   if ((bscfFlag & BSCF_FIRSTDATANOTIFICATION) != 0)
   {
      m_dwReadBefore = 0;
      m_strText.Empty();
   }

   DWORD dwArriving = dwSize - m_dwReadBefore;

   if (dwArriving > 0)
   {
      int nLen = m_strText.GetLength();
      ASSERT((DWORD)nLen == m_dwReadBefore);
      LPTSTR psz = m_strText.GetBuffer(nLen + dwArriving);
      Read(psz + nLen, dwArriving);
      m_strText.ReleaseBuffer(nLen + dwArriving);
      m_dwReadBefore = dwSize;
   }
}

CAsyncMonikerFile::OnLowResource

资源不足时由名字对象调用。

virtual void OnLowResource();

备注

默认实现调用 GetBinding( )-> Abort( )。

CAsyncMonikerFile::OnProgress

由名字对象重复调用，以指示此绑定操作的当前进度，通常在较长的操作期间以合理的间隔进行调用。

virtual void OnProgress(
    ULONG ulProgress,
    ULONG ulProgressMax,
    ULONG ulStatusCode,
    LPCTSTR szStatusText);

参数

ulProgress
相对于 ulProgressMax 中所指示的预期最大值，指示绑定操作的当前进度。

ulProgressMax
指示在此操作调用 OnProgress 期间 ulProgress 的预期最大值。

ulStatusCode
提供有关绑定操作进度的其他信息。 从 BINDSTATUS 枚举获取有效值。 请参见可能的值的注解。

szStatusText
有关当前进度的信息，具体取决于 ulStatusCode 的值。 请参见可能的值的注解。

注解

ulStatusCode 的可能值（以及每个值的 szStatusText）为：

值	说明
BINDSTATUS_FINDINGRESOURCE	绑定操作正在查找保存绑定到的对象或存储的资源。 szStatusText 提供要搜索资源的显示名称（例如“www.microsoft.com”）。
BINDSTATUS_CONNECTING	绑定操作正在连接到保存绑定到的对象或存储的资源。 szStatusText 提供连接到的资源的显示名称（例如 IP 地址）。
BINDSTATUS_SENDINGREQUEST	绑定操作正在请求绑定到的对象或存储。 szStatusText 提供对象的显示名称（例如文件名）。
BINDSTATUS_REDIRECTING	绑定操作已重定向到其他数据位置。 szStatusText 提供新数据位置的显示名称。
BINDSTATUS_USINGCACHEDCOPY	绑定操作正在从缓存副本检索请求的对象或存储。 szStatusText 为 NULL.
BINDSTATUS_BEGINDOWNLOADDATA	绑定操作已开始接收绑定到的对象或存储。 szStatusText 提供数据位置的显示名称。
BINDSTATUS_DOWNLOADINGDATA	绑定操作继续接收绑定到的对象或存储。 szStatusText 提供数据位置的显示名称。
BINDSTATUS_ENDDOWNLOADDATA	绑定操作已完成接收绑定到的对象或存储。 szStatusText 提供数据位置的显示名称。
BINDSTATUS_CLASSIDAVAILABLE	即将创建要绑定到的对象实例。 szStatusText 以字符串格式提供新对象的 CLSID，使客户端有机会根据需要取消绑定操作。

CAsyncMonikerFile::OnStartBinding

在派生类中重写此函数，以在绑定启动时执行操作。

virtual void OnStartBinding();

注解

此函数由名字对象回调。 默认实现不执行任何操作。

CAsyncMonikerFile::OnStopBinding

绑定操作结束时由名字对象调用。

virtual void OnStopBinding(HRESULT hresult, LPCTSTR szError);

参数

hresult
作为错误或警告值的 HRESULT。

szErrort
描述错误的字符串。

注解

重写此函数以在传输停止时执行操作。 默认情况下，函数释放 IBinding。

有关 IBinding 接口的说明，请参阅 Windows SDK。

CAsyncMonikerFile::Open

调用此成员函数以异步打开文件。

virtual BOOL Open(
    LPCTSTR lpszURL,
    CFileException* pError = NULL);

virtual BOOL Open(
    IMoniker* pMoniker,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszURL,
    IBindHost* pBindHost,
    CFileException* pError = NULL);

virtual BOOL Open(
    IMoniker* pMoniker,
    IBindHost* pBindHost,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszURL,
    IServiceProvider* pServiceProvider,
    CFileException* pError = NULL);

virtual BOOL Open(
    IMoniker* pMoniker,
    IServiceProvider* pServiceProvider,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszURL,
    IUnknown* pUnknown,
    CFileException* pError = NULL);

virtual BOOL Open(
    IMoniker* pMoniker,
    IUnknown* pUnknown,
    CFileException* pError = NULL);

参数

lpszURL
指向要异步打开文件的指针。 该文件可以是任何有效的 URL 或文件名。

pError
指向文件异常的指针。 发生错误时，会将其设置为原因。

pMoniker
指向异步名字对象接口 IMoniker 的指针，一个精确的名字对象，它是文档自身名字对象的组合，可以使用 IOleClientSite::GetMoniker(OLEWHICHMK_CONTAINER) 以及从路径名称创建的名字对象检索。 控件可以使用此名字对象进行绑定，但这不是控件应保存的名称对象。

pBindHost
指向 IBindHost 接口的指针，该接口将用于从可能相对的路径名称创建名字对象。 如果绑定主机无效或不提供名字对象，则默认调用 Open(lpszFileName,pError)。 有关 IBindHost 接口的说明，请参阅 Windows SDK。

pServiceProvider
指向 IServiceProvider 接口的指针。 如果服务提供商无效或无法提供 IBindHost 服务，则默认调用 Open(lpszFileName,pError)。

pUnknown
指向 IUnknown 接口的指针。 如果找到 IServiceProvider，函数将查询 IBindHost。 如果服务提供商无效或无法提供 IBindHost 服务，则默认调用 Open(lpszFileName,pError)。

返回值

如果成功打开文件，则为非零；否则为 0。

备注

此调用会启动绑定过程。

可以为 lpszURL 参数使用 URL 或文件名。 例如：

CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("http://www.microsoft.com"));

- 或 -

CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("file:c:\\mydata.dat"));

另请参阅

CMonikerFile 类
层次结构图
CMonikerFile 类
CDataPathProperty 类