CBindStatusCallback クラス

[アーティクル]
10/12/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	使用可能なバイト数と読み取られたバイト数を 0 に初期化し、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();

解説

非同期データ転送に関する通知を受信するオブジェクトを作成します。通常、バインド操作ごとに 1 つのオブジェクトが作成されます。

また、コンストラクターによって 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
[入力] 非同期データ転送を要求するオブジェクトへのポインター。 CBindStatusCallback オブジェクトは、このオブジェクトのクラスでテンプレート化されます。

pFunc
[入力] 読み取られるデータを受け取る関数へのポインター。関数は、T 型のオブジェクトのクラスのメンバーです。構文と例については、「StartAsyncDownload」を参照してください。

bstrURL
[入力] データの取得元の URL。任意の有効な URL またはファイル名にすることができます。 Nll は指定できません。次に例を示します。

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

pUnkContainer
[入力] コンテナーの IUnknown。既定では NULL になります。

bRelative
[入力] URL が相対か絶対かを示すフラグ。既定では FALSE になります。つまり、URL は絶対です。

戻り値

標準 HRESULT 値のいずれか。

解説

データが使用可能になるたびに、OnDataAvailable を使用してオブジェクトに送信されます。 OnDataAvailable ではデータを読み取り、pFunc によって指し示される関数を呼び出します (たとえば、データを格納したり、画面に出力したりする場合)。

CBindStatusCallback::GetBindInfo

モニカーにバインドする方法を指示するために呼び出されます。

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

パラメーター

pgrfBSCF
[出力] バインド操作の実行方法を示す BINDF 列挙値へのポインター。既定では、次の列挙値で設定されます。

BINDF_ASYNCHRONOUS 非同期ダウンロード。

BINDF_ASYNCSTORAGE OnDataAvailable では、データが使用可能になるまでブロックするのではなく、データがまだ使用できない場合に E_PENDING を返します。

BINDF_GETNEWESTVERSION バインド操作で、最新バージョンのデータを取得する必要があります。

BINDF_NOWRITECACHE バインド操作では、取得されたデータをディスクキャッシュに格納することはできません。

pbindinfo
[入力、出力] オブジェクトがどのようにバインディングを必要とするかについての詳細情報を提供する BINDINFO 構造体へのポインター。

戻り値

標準 HRESULT 値のいずれか。

解説

既定の実装では、バインディングを非同期にし、データプッシュモデルを使用するように設定します。データプッシュモデルでは、モニカーによって非同期バインド操作が開始され、新しいデータが利用可能になると常にクライアントに継続的に通知されます。

CBindStatusCallback::GetPriority

バインド操作の優先順位を取得するために非同期モニカーによって呼び出されます。

STDMETHOD(GetPriority)(LONG* pnPriority);

パラメーター

pnPriority
[出力] 成功した場合は優先順位を受け取る LONG 変数のアドレス。

戻り値

E_NOTIMPL を返します。

CBindStatusCallback::m_dwAvailableToRead

読み取り可能なバイト数を格納するために使用できます。

DWORD m_dwAvailableToRead;

解説

StartAsyncDownload で 0 に初期化されます。

CBindStatusCallback::m_dwTotalRead

非同期データ転送で読み取られたバイトの累積合計。

DWORD m_dwTotalRead;

解説

OnDataAvailable が呼び出されるたびに、実際に読み取られたバイト数だけインクリメントされます。 StartAsyncDownload で 0 に初期化されます。

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
[入力] BSCF 列挙値。 BSCF_FIRSTDATANOTIFICATION、BSCF_INTERMEDIARYDATANOTIFICATION、または BSCF_LASTDATANOTIFICATION のうちの 1 つまたは複数。

dwSize
[入力] バインディングの開始以降に使用できるデータの累積量 (バイト単位)。 0 にすることができます。これは、データの量が関連していないこと、または特定の量が使用できなくなったことを示します。

pformatetc
[入力] 使用可能なデータの形式を格納している FORMATETC 構造体へのポインター。形式がない場合は、CF_NULL にすることができます。

pstgmed
[入力] 使用できるようになった実際のデータを保持する 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

pBinding の IBinding ポインターにデータメンバー m_spBinding を設定します。

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

パラメーター

dwReserved
将来利用するために予約されています。

pBinding
[入力] 現在のバインド操作の 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);

パラメーター

pFunc
[入力] 読み取られるデータを受け取る関数へのポインター。関数は、T 型のオブジェクトのクラスのメンバーです。構文と例については、「解説」を参照してください。

bstrURL
[入力] データの取得元の URL。任意の有効な URL またはファイル名にすることができます。 Nll は指定できません。次に例を示します。

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

pUnkContainer
[入力] コンテナーの IUnknown。既定では NULL になります。

bRelative
[入力] URL が相対か絶対かを示すフラグ。既定では FALSE になります。つまり、URL は絶対です。

戻り値

標準 HRESULT 値のいずれか。

解説

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

パラメーター

戻り値

解説

例

関連項目

フィードバック

フィードバック

その他のリソース

パブリックコンストラクター

パブリックメソッド

パブリックデータメンバー