CComEnumImpl クラス
このクラスは、列挙される項目が配列に格納される COM 列挙子インターフェイスの実装を提供します。
構文
template <class Base,
const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base
パラメーター
Base
COM 列挙子インターフェイス。 例については、IEnumString に関する記事を参照してください。
piid
列挙子インターフェイスのインターフェイス ID へのポインター。
T
列挙子インターフェイスによって公開される項目の型。
コピー
同種のコピー ポリシー クラス。
メンバー
パブリック コンストラクター
| 名前 | 説明 |
|---|---|
| CComEnumImpl::CComEnumImpl | コンストラクター。 |
| CComEnumImpl::~CComEnumImpl | デストラクター。 |
パブリック メソッド
| 名前 | 説明 |
|---|---|
| CComEnumImpl::Clone | Clone 列挙インターフェイス メソッドの実装。 |
| CComEnumImpl::Init | 列挙子を初期化します。 |
| CComEnumImpl::Next | Next の実装。 |
| CComEnumImpl::Reset | Reset の実装。 |
| CComEnumImpl::Skip | Skip の実装。 |
パブリック データ メンバー
| 名前 | 説明 |
|---|---|
| CComEnumImpl::m_begin | 配列内の最初の項目へのポインター。 |
| CComEnumImpl::m_dwFlags | Init を介して渡されるコピー フラグ。 |
| CComEnumImpl::m_end | 配列内の最後の項目の次の位置へのポインター。 |
| CComEnumImpl::m_iter | 配列内の現在の項目へのポインター。 |
| CComEnumImpl::m_spUnk | 列挙されるコレクションを提供するオブジェクトの IUnknown ポインター。 |
解説
メソッドの実装例については、「IEnumString」を参照してください。 CComEnumImpl では、列挙される項目が配列に格納される COM 列挙子インターフェイスの実装が提供されます。 このクラスは、C++ 標準ライブラリ コンテナーに基づく列挙子インターフェイスの実装を提供する IEnumOnSTLImpl クラスに似ています。
Note
CComEnumImpl と IEnumOnSTLImpl の違いの詳細については、「CComEnumImpl::Init」を参照してください。
通常、このインターフェイスの実装から派生させて、独自の列挙子クラスを作成する必要は ''ありません''。 配列に基づいて ATL 提供の列挙子を使用する場合は、CComEnum のインスタンスを作成する方が一般的です。
しかし、カスタム列挙子 (列挙子インターフェイスに加えてインターフェイスを公開するものなど) を指定する必要がある場合は、このクラスから派生させることができます。 このような状況では、独自の実装を指定するために、CComEnumImpl::Clone メソッドをオーバーライドする必要がある可能性があります。
詳細については、「ATL コレクションと列挙子」を参照してください。
継承階層
Base
CComEnumImpl
要件
ヘッダー: atlcom.h
CComEnumImpl::CComEnumImpl
コンストラクター。
CComEnumImpl();
CComEnumImpl::~CComEnumImpl
デストラクター。
~CComEnumImpl();
CComEnumImpl::Init
列挙子インターフェイスへのポインターをクライアントに渡す前に、このメソッドを呼び出す必要があります。
HRESULT Init(
T* begin,
T* end,
IUnknown* pUnk,
CComEnumFlags flags = AtlFlagNoCopy);
パラメーター
begin
列挙する項目を含む配列の最初の要素へのポインター。
end
列挙する項目を含む配列の最後の要素の次の位置へのポインター。
pUnk
[入力] 列挙子の有効期間中に存続する必要があるオブジェクトの IUnknown ポインター。 そのようなオブジェクトが存在しない場合は、NULL を渡します。
flags
列挙子で配列の所有権を取得するか、配列のコピーを作成する必要があるかどうかを指定するフラグ。 使用できる値を以下に示します。
戻り値
標準の HRESULT 値。
解説
このメソッドは 1 回だけ呼び出します。列挙子を初期化し、使用してから、スローします。
別のオブジェクトに保持されている配列内の項目へのポインターを渡す (および列挙子にデータのコピーを求めない) 場合、pUnk パラメーターを使い、列挙子で必要である限り、オブジェクトとそれが保持する配列を確実に使用できるようにすることができます。 列挙子では単にオブジェクトに対する COM 参照を保持して、それを維持します。 COM 参照は、列挙子が破棄されると自動的に解放されます。
flags パラメーターを使用すると、列挙子で渡された配列要素を処理する方法を指定できます。flags では、次に示す CComEnumFlags 列挙型のいずれかの値を取ることができます。
enum CComEnumFlags
{
AtlFlagNoCopy = 0,
AtlFlagTakeOwnership = 2, // BitOwn
AtlFlagCopy = 3 // BitOwn | BitCopy
};
AtlFlagNoCopy は、配列の有効期間が列挙子によって制御されないことを意味します。 この場合、配列は静的になるか、pUnk によって識別されるオブジェクトで、必要でなくなったときに配列を解放する必要があります。
AtlFlagTakeOwnership は、配列の破棄が列挙子によって制御されることを意味します。 この場合、配列は new を使用して動的に割り当てられている必要があります。 列挙子により、そのデストラクター内の配列が削除されます。 通常、pUnk に NULL を渡しますが、何らかの理由で列挙子の破棄の通知を受ける必要がある場合は、引き続き有効なポインターを渡すことができます。
AtlFlagCopy は、Init に渡された配列をコピーして、新しい配列を作成することを意味します。 新しい配列の有効期間は、列挙子によって制御されます。 列挙子により、そのデストラクター内の配列が削除されます。 通常、pUnk に NULL を渡しますが、何らかの理由で列挙子の破棄の通知を受ける必要がある場合は、引き続き有効なポインターを渡すことができます。
Note
このメソッドのプロトタイプでは、配列要素を T 型として指定します。ここで、T はクラスのテンプレート パラメーターとして定義されたものです。 これは、COM インターフェイス メソッド CComEnumImpl::Next を使用して公開される型と同じです。 これは、IEnumOnSTLImpl とは異なり、このクラスで異なるストレージと公開されるデータ型がサポートされないことを意味します。 配列内の要素のデータ型は、COM インターフェイスによって公開されるデータ型と同じである必要があります。
CComEnumImpl::Clone
このメソッドでは、CComEnum 型のオブジェクトを作成し、現在のオブジェクトで使用されているのと同じ配列と列挙子で初期化し、新しく作成されたオブジェクトのインターフェイスを返すことで、Clone メソッドの実装を提供します。
STDMETHOD(Clone)(Base** ppEnum);
パラメーター
ppEnum
[出力] 現在の列挙子から複製され、新しく作成されたオブジェクトの列挙子インターフェイス。
戻り値
標準の HRESULT 値。
解説
複製された列挙子では、元の列挙子によって使用されるデータの独自のコピー (または所有権の取得) が行われることがないことに注意してください。 必要に応じて、複製された列挙子では (COM 参照を使用して) 元の列挙子を維持し、データが必要な限り、確実に使用できるようにします。
CComEnumImpl::m_spUnk
このスマート ポインターでは、CComEnumImpl::Init に渡されるオブジェクトへの参照が維持されます。これにより、列挙子の有効期間中は確実に存続することになります。
CComPtr<IUnknown> m_spUnk;
CComEnumImpl::m_begin
列挙する項目を含む配列の最後の要素の次の位置へのポインター。
T* m_begin;
CComEnumImpl::m_end
列挙する項目を含む配列の最初の要素へのポインター。
T* m_end;
CComEnumImpl::m_iter
列挙する項目を含む配列の現在の要素へのポインター。
T* m_iter;
CComEnumImpl::m_dwFlags
CComEnumImpl::Init に渡されるフラグ。
DWORD m_dwFlags;
CComEnumImpl::Next
このメソッドでは、Next メソッドの実装を提供します。
STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);
パラメーター
celt
[入力] 要求された要素の数。
rgelt
[出力] 要素が格納される配列。
pceltFetched
[出力] rgelt で実際に返される要素の数。 celt より少ない数の要素がリストに残っている場合、これは celt より小さくなることがあります。
戻り値
標準の HRESULT 値。
CComEnumImpl::Reset
このメソッドでは、Reset メソッドの実装を提供します。
STDMETHOD(Reset)(void);
戻り値
標準の HRESULT 値。
CComEnumImpl::Skip
このメソッドでは、Skip メソッドの実装を提供します。
STDMETHOD(Skip)(ULONG celt);
パラメーター
celt
[in] スキップする要素数。
戻り値
標準の HRESULT 値。
解説
celt が 0 の場合は E_INVALIDARG を返し、celt より小さい数の要素が返された場合は S_FALSE を返します。それ以外の場合は、S_OK を返します。