CBindStatusCallback 類別

發行項
08/03/2024

這個類別會實作 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：:D ownload	啟動下載程式的靜態方法、建立 `CBindStatusCallback` 物件，並呼叫 `StartAsyncDownload`。
CBindStatusCallback：：GetBindInfo	由異步Moniker呼叫，要求要建立之系結類型的相關信息。
CBindStatusCallback：：GetPriority	由異步Moniker呼叫以取得系結作業的優先順序。 ATL 實作會傳 `E_NOTIMPL`回。
CBindStatusCallback：：OnDataAvailable	呼叫以在應用程式可供使用時將數據提供給您的應用程式。讀取數據，然後呼叫傳遞給它的函式以使用數據。
CBindStatusCallback：：OnLowResource	資源不足時呼叫。 ATL 實作會傳回S_OK。
CBindStatusCallback：：OnObjectAvailable	由異步 Moniker 呼叫，以將物件介面指標傳遞至您的應用程式。 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 應用程式必須實作，才能從異步數據傳輸接收通知。系統提供的異步 Moniker 會使用 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;
}

異步 Moniker 會使用回呼函 OnData 式在具有數據時呼叫您的應用程式。異步Moniker是由系統提供。

繼承階層架構

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

需求

標頭： atlctl.h

CBindStatusCallback：：CBindStatusCallback

建構函式。

CBindStatusCallback();

備註

建立物件，以接收有關異步數據傳輸的通知。一般而言，會為每個系結作業建立一個物件。

建構函式也會將m_pT和 m_pFunc初始化為NULL。

CBindStatusCallback：：~CBindStatusCallback

解構函式。

~CBindStatusCallback();

備註

釋放所有已配置的資源。

CBindStatusCallback：:D ownload

建立 CBindStatusCallback 物件，並呼叫 StartAsyncDownload 以異步方式從指定的 URL 下載數據。

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

參數

鉑
[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 是相對還是絕對的旗標。根據預設，FALSE 表示 URL 是絕對的。

傳回值

其中一個標準 HRESULT 值。

備註

每次有數據可用時，都會透過 OnDataAvailable傳送至物件。 OnDataAvailable讀取數據並呼叫 pFunc 所指向的函式（例如，儲存數據或列印到畫面）。

CBindStatusCallback：：GetBindInfo

呼叫以告訴Moniker如何系結。

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

參數

pgrfBSCF
[out]BINDF 列舉值的指標，指出系結作業的發生方式。根據預設，使用下列列舉值進行設定：

BINDF_ASYNCHRONOUS異步下載。

OnDataAvailable BINDF_ASYNCSTORAGE在數據尚無法使用時傳回E_PENDING，而不是在數據可用之前封鎖。

BINDF_GETNEWESTVERSION系結作業應該擷取最新版的數據。

BINDF_NOWRITECACHE系結作業不應將擷取的數據儲存在磁碟快取中。

pbindinfo
[in， out]結構的 BINDINFO 指標，提供物件想要如何系結的詳細資訊。

傳回值

其中一個標準 HRESULT 值。

備註

默認實作會將系結設定為異步，並使用數據推送模型。在數據推送模型中，Moniker 會驅動異步系結作業，並在每當有新的數據可用時持續通知用戶端。

CBindStatusCallback：：GetPriority

由異步Moniker呼叫以取得系結作業的優先順序。

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 介面的指標，提供系結內容的存取權（儲存特定Moniker系結作業相關信息的物件）。

CComPtr<IBindCtx> m_spBindCtx;

備註

在中 StartAsyncDownload初始化。

CBindStatusCallback：：m_spBinding

目前系結作業介面的指標 IBinding 。

CComPtr<IBinding> m_spBinding;

備註

在中 OnStartBinding 初始化，並在中 OnStopBinding釋放。

CBindStatusCallback：：m_spMoniker

IMoniker 介面的指標，供 URL 使用。

CComPtr<IMoniker> m_spMoniker;

備註

在中 StartAsyncDownload初始化。

CBindStatusCallback：：m_spStream

目前系結作業之 IStream 介面的指標。

CComPtr<IStream> m_spStream;

備註

OnDataAvailable當BCSF旗標BCSF_FIRSTDATANOTIFICATION並在BCSF旗標BCSF_LASTDATANOTIFICATION時釋放時，從 STGMEDIUM 結構初始化。

CBindStatusCallback：：OnDataAvailable

系統提供的異步 Moniker 會呼叫 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

由異步 Moniker 呼叫，以將物件介面指標傳遞至您的應用程式。

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

參數

riid
所要求介面的介面標識碼。未使用的。

朋克
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設定為 IBinding pBinding 中的指標。

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

參數

dwReserved
保留供未來使用。

pBinding
[in]目前系結作業之 IBinding 介面的位址。這不可以是 NULL。客戶端應該在此指標上呼叫 AddRef，以保留系結對象的參考。

CBindStatusCallback：：OnStopBinding

釋放 IBinding 數據成員中的指標m_spBinding。

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

參數

hresult
從系結作業傳回的狀態代碼。

szError
字串值的位址。未使用的。

備註

由系統提供的異步 Moniker 呼叫，以指出系結作業的結尾。

CBindStatusCallback：：StartAsyncDownload

開始以異步方式從指定的 URL 下載數據。

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

參數

鉑
[in]要求異步數據傳輸之物件的指標。物件 CBindStatusCallback 會在這個物件的類別上範本化。

pFunc
[in]接收所讀取數據的函式指標。函式是物件類別的成員，類型 T為。如需語法和範例，請參閱<備註>。

bstrURL
[in]要從中取得數據的 URL。可以是任何有效的 URL 或檔名。不可以是 NULL。例如：

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

pUnkContainer
[in] IUnknown 容器的。根據預設，NULL。

bRelative
[in]指出 URL 是相對還是絕對的旗標。根據預設，FALSE 表示 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：:D ownload

參數

傳回值

備註

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

參數

傳回值

備註

範例

另請參閱

意見反應

其他資源