CComEnumImpl::Init

[アーティクル]
08/09/2011

このメソッドは、列挙子インターフェイスへのポインターをクライアントに返す前に呼び出す必要があります。

HRESULT Init(
   T* begin,
   T* end,
   IUnknown* pUnk,
   CComEnumFlags flags = AtlFlagNoCopy 
);

パラメーター

begin
列挙されるアイテムを格納する配列内の最初の要素へのポインターです。
end
列挙されるアイテムを格納する配列内の最後にある要素の次の位置を指すポインターです。
pUnk
[入力] 列挙子の有効期間中、有効にしておく必要があるオブジェクトの IUnknown ポインター。有効にしておくオブジェクトがない場合は NULL を渡します。
flags
列挙子が配列の所有権を持つかどうか、または配列のコピーを作成するかどうかを指定するフラグ。指定できる値については下記で説明します。

戻り値

標準の HRESULT 値。

解説

このメソッドは、列挙子を初期化し、使用し、破棄するまでの間に一度だけ呼び出してください。

別のオブジェクトが保持している配列内のアイテムへのポインターを渡す場合 (さらに列挙子がデータをコピーしないように指定する場合)、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 を渡しますが、なんらかの理由で列挙子の破棄を通知する必要がある場合は、有効なポインターを渡すこともできます。

注意

このメソッドのプロトタイプは、配列の要素を T 型として指定します。T は、クラスに渡すテンプレートパラメーターとして定義されている型です。この型は、COM インターフェイスメソッド CComEnumImpl::Next によって公開される型と同じです。つまり、このクラスは IEnumOnSTLImpl とは異なり、別のストレージや、公開されているデータ型をサポートしません。配列内の要素のデータ型は、COM インターフェイスで公開されているデータ型と同じであることが必要とされます。