CAsyncMonikerFile 類別

提供可在 ActiveX 控制項 (先前稱為 OLE 控制項) 中使用非同步 Moniker 的功能。

語法

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	當非同步傳輸停止時呼叫。

備註

衍生自衍生自 COleStreamFile 的 CMonikerFile ，會使用 IMoniker 介面以非同步方式存取任何資料流程， CAsyncMonikerFile 包括從 URL 非同步載入檔案。 檔案可以是 ActiveX 控制項的 datapath 屬性。

非同步 Moniker 主要用於啟用網際網路的應用程式和 ActiveX 控制項中，以在檔案傳輸期間提供回應式使用者介面。 其中的主要範例是使用 CDataPathProperty 來提供 ActiveX 控制項的非同步屬性。 物件 CDataPathProperty 會重複取得回呼，以指出在冗長的屬性交換過程中新資料的可用性。

如需如何在網際網路應用程式中使用非同步 Moniker 和 ActiveX 控制項的詳細資訊，請參閱下列文章：

• 網際網路第一個步驟：非同步 Monikers

• 網際網路第一個步驟：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，函式會在支援 IBindStatusCallback 的新 COM 物件上傳回內部 IUnknown 的指標。 如果 pUnkControlling 為 Null，函式會在支援 IBindStatusCallback 的新 COM 物件上傳回 的指標 IUnknown 。

備註

CAsyncMonikerFile 需要實作 的 IBindStatusCallback COM 物件。 MFC 會實作這類物件，而且可匯總。 您可以覆寫 CreateBindStatusCallback 以傳回自己的 COM 物件。 COM 物件可以藉由使用 COM 物件的控制未知呼叫 CreateBindStatusCallback 來匯總 MFC 的實作。 使用 COM 支援實作的 CCmdTarget COM 物件可以使用 擷取未知 CCmdTarget::GetControllingUnknown 的控制。

或者，COM 物件可以藉由呼叫 CreateBindStatusCallback( NULL ) 委派給 MFC 的實作。

CAsyncMonikerFile：：Open 會呼叫 CreateBindStatusCallback 。

如需非同步 Moniker 和非同步系結的詳細資訊，請參閱 IBindStatusCallback 介面和 非同步系結和儲存體運作 方式。 如需匯總的討論，請參閱 匯總 。 這三個主題都在 Windows SDK 中。

CAsyncMonikerFile：：GetBindInfo

從非同步 Moniker 的用戶端呼叫，以告訴非同步 Moniker 它想要系結的方式。

virtual DWORD GetBindInfo() const;

傳回值

擷取 的 IBindStatusCallBack 設定。 如需介面的描述 IBindStatusCallback ，請參閱 Windows SDK。

備註

預設實作會將系結設定為非同步、使用儲存媒體（資料流程），以及使用資料推送模型。 如果您想要變更系結的行為，請覆寫此函式。

這樣做的其中一個原因是使用資料提取模型來系結，而不是資料推送模型。 在資料提取模型中，用戶端會驅動系結作業，而 Moniker 只會在讀取時將資料提供給用戶端。 在資料推送模型中，Moniker 會驅動非同步系結作業，並在每當有新資料可用時持續通知用戶端。

CAsyncMonikerFile：：GetBinding

呼叫此函式以擷取非同步傳輸系結的指標。

IBinding* GetBinding() const;

傳回值

非同步傳輸開始時所提供介面的 IBinding 指標。 如果基於任何原因，無法以非同步方式進行傳輸，則傳回 Null。

備註

這可讓您透過 IBinding 介面控制資料傳輸程式，例如，使用 IBinding::Abort 、 IBinding::Pause 和 IBinding::Resume 。

如需介面的描述 IBinding ，請參閱 Windows SDK。

CAsyncMonikerFile：：GetFormatEtc

呼叫此函式以擷取資料流程中的資料格式。

FORMATETC* GetFormatEtc() const;

傳回值

目前開啟資料流程之 Windows 結構 FORMATETC 的指標。 如果 Moniker 尚未系結、不是非同步，或非同步作業尚未開始，則傳回 Null。

CAsyncMonikerFile：：GetPriority

從非同步 Moniker 的用戶端呼叫，因為系結進程開始接收系結作業之執行緒的優先順序。

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

非同步 Moniker 會呼叫 OnDataAvailable ，以在非同步系結作業期間提供資料給用戶端。

virtual void OnDataAvailable(DWORD dwSize, DWORD bscfFlag);

參數

dwSize
自系結開始以來可用的資料累計數量（以位元組為單位）。 可以是零，表示資料量與作業無關，或沒有可用的特定數量。

bscfFlag
BSCF 列舉值。 可以是下列其中一或多個值：

• BSCF_FIRSTDATANOTIFICATION 識別指定系結作業的第一次呼叫 OnDataAvailable 。

• BSCF_INTERMEDIATEDATANOTIFICATION 識別系結作業的中繼呼叫 OnDataAvailable 。

• BSCF_LASTDATANOTIFICATION識別系結作業的最後一個呼叫 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

資源不足時，Moniker 呼叫。

virtual void OnLowResource();

備註

預設實作會呼叫 GetBinding( )-> Abort( ) 。

CAsyncMonikerFile：：OnProgress

Moniker 重複呼叫以指出此系結作業的目前進度，通常是在長時間作業期間以合理的間隔。

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

參數

ulProgress
指出系結作業的目前進度，相對於 ulProgressMax 中所 指示的預期最大值。

ulProgressMax
表示針對此作業呼叫 OnProgress 期間，ulProgress 的預期最大值 。

ulStatusCode
提供有關系結作業進度的其他資訊。 有效值取自 BINDSTATUS 列舉。 如需可能的值，請參閱。

szStatusText
目前進度的相關資訊，視 ulStatusCode 的值 而定。 如需可能的值，請參閱。

備註

ulStatusCode 的可能值為 ：每個 值的 szStatusText ：

值	Description
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();

備註

Moniker 會呼叫此函式。 預設實作不做任何動作。

CAsyncMonikerFile：：OnStopBinding

系結作業結尾的 Moniker 呼叫。

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
非同步 Moniker 介面 IMoniker 的指標、精確的 Moniker，這是檔本身 Moniker 的組合，您可以使用 擷取 IOleClientSite::GetMoniker(OLEWHICHMK_CONTAINER) ，以及從路徑名稱建立的 Moniker。 控制項可以使用這個 Moniker 系結，但這不是控制項應該儲存的 Moniker。

pBindHost
介面的 IBindHost 指標，將用來從潛在的相對路徑名稱建立 Moniker。 如果系結主機無效或未提供 Moniker，則呼叫預設為 Open(lpszFileName,pError) 。 如需介面的描述 IBindHost ，請參閱 Windows SDK。

pServiceProvider
介面的 IServiceProvider 指標。 如果服務提供者無效或無法提供服務， IBindHost 則呼叫預設為 Open(lpszFileName,pError) 。

pUnknown
介面的 IUnknown 指標。 如果 IServiceProvider 找到 ，則函式會查詢 IBindHost 。 如果服務提供者無效或無法提供服務， IBindHost 則呼叫預設為 Open(lpszFileName,pError) 。

傳回值

如果已成功開啟檔案，則為非零;否則為 0。

備註

此呼叫會起始系結程式。

您可以使用 URL 或 lpszURL 參數的 檔案名。 例如：

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 類別