CAsyncMonikerFile 類別

發行項
08/04/2024

提供可在 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控件的詳細資訊，請參閱下列文章：

繼承階層架構

CAsyncMonikerFile

需求

標頭： afxole.h

CAsyncMonikerFile：：CAsyncMonikerFile

建構 CAsyncMonikerFile 物件。

CAsyncMonikerFile();

備註

它不會建立 IBindHost 介面。 IBindHost 只有在您在成員函式中 Open 提供它時才使用。

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

CAsyncMonikerFile：：Close

呼叫此函式以關閉並釋放所有資源。

virtual void Close();

備註

可以在未開啟或已關閉的檔案上呼叫。

CAsyncMonikerFile：：CreateBindStatusCallback

建立實作的 IBindStatusCallbackCOM 物件。

virtual IUnknown* CreateBindStatusCallback(IUnknown* pUnkControlling);

參數

pUnkControlling
如果未使用匯總，則為控制未知（外部 IUnknown）或 NULL 的指標。

傳回值

如果 pUnkControlling 不是 NULL，函式會在支援 IBindStatusCallback的新 COM 物件上傳回內部IUnknown的指標。如果 pUnkControlling 為 NULL，函式會在支援 IBindStatusCallback的新 COM 物件上傳回的指標IUnknown。

備註

CAsyncMonikerFile 需要實作的 IBindStatusCallbackCOM 物件。 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 類別

共用方式為