Класс CComEnumImpl
Этот класс предоставляет реализацию для интерфейса перечислителя COM, где перечисляемые элементы хранятся в массиве.
Синтаксис
template <class Base,
const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base
Параметры
Основание
Интерфейс перечислителя COM. См . пример IEnumString .
piid
Указатель на идентификатор интерфейса интерфейса перечислителя.
T
Тип элемента, предоставляемый интерфейсом перечислителя.
Копировать
Однородный класс политики копирования.
Участники
Открытые конструкторы
| Имя | Описание |
|---|---|
| CComEnumImpl::CComEnumImpl | Конструктор. |
| CComEnumImpl::~CComEnumImpl | Деструктор |
Открытые методы
| Имя | Описание |
|---|---|
| CComEnumImpl::Clone | Реализация метода интерфейса перечисления Clone . |
| CComEnumImpl::Init | Инициализирует перечислитель. |
| CComEnumImpl::Next | Реализация Next. |
| CComEnumImpl::Reset | Реализация сброса. |
| CComEnumImpl::Skip | Реализация Skip. |
Открытые члены данных
| Имя | Описание |
|---|---|
| CComEnumImpl::m_begin | Указатель на первый элемент в массиве. |
| CComEnumImpl::m_dwFlags | Копирование флагов, передаваемых через Init. |
| CComEnumImpl::m_end | Указатель на расположение непосредственно за последним элементом в массиве. |
| CComEnumImpl::m_iter | Указатель на текущий элемент в массиве. |
| CComEnumImpl::m_spUnk | Указатель IUnknown объекта, предоставляющего перечисляемую коллекцию. |
Замечания
Пример реализации методов см . в IEnumString . CComEnumImpl предоставляет реализацию для интерфейса перечислителя COM, где перечисляемые элементы хранятся в массиве. Этот класс аналогичен IEnumOnSTLImpl классу, который предоставляет реализацию интерфейса перечислителя на основе контейнера стандартной библиотеки C++.
Примечание.
Дополнительные сведения о дальнейших различиях между 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
Указатель на расположение только за последним элементом массива, содержащим элементы, которые необходимо перечислить.
панк
[in] Указатель IUnknown объекта, который должен храниться в живых во время существования перечислителя. Передайте значение NULL, если такой объект не существует.
flags
Флаги, указывающие, должен ли перечислитель взять на себя владение массивом или сделать его копию. Возможные значения описаны ниже.
Возвращаемое значение
Стандартное значение HRESULT.
Замечания
Вызовите этот метод только один раз— инициализируйте перечислитель, используйте его, а затем выбросить его.
Если вы передаете указатели на элементы в массиве, удерживаемом в другом объекте (и не запрашиваете перечислитель копировать данные), можно использовать параметр pUnk , чтобы убедиться, что объект и массив, который он содержит, доступны до тех пор, пока перечислитель им нужен. Перечислитель просто содержит com-ссылку на объект, чтобы сохранить его в живых. Ссылка COM автоматически освобождается при уничтожении перечислителя.
Параметр флагов позволяет указать, как перечислитель должен обрабатывать элементы массива, передаваемые в него. Флаги могут принимать одно из значений из перечисления, показанного CComEnumFlags ниже:
enum CComEnumFlags
{
AtlFlagNoCopy = 0,
AtlFlagTakeOwnership = 2, // BitOwn
AtlFlagCopy = 3 // BitOwn | BitCopy
};
AtlFlagNoCopy означает, что время существования массива не контролируется перечислителем. В этом случае массив будет статическим или объект, идентифицированный pUnk , будет отвечать за освобождение массива, если он больше не нужен.
AtlFlagTakeOwnership означает, что уничтожение массива должно контролироваться перечислителем. В этом случае массив должен быть динамически выделен с помощью new. Перечислитель удаляет массив в деструкторе. Как правило, вы передаете значение NULL для pUnk, хотя вы по-прежнему можете передать допустимый указатель, если вам нужно уведомить об уничтожении перечислителя по какой-то причине.
AtlFlagCopy означает, что создается новый массив путем копирования переданного массива Init. Время существования нового массива должно контролироваться перечислителем. Перечислитель удаляет массив в деструкторе. Как правило, вы передаете значение NULL для pUnk, хотя вы по-прежнему можете передать допустимый указатель, если вам нужно уведомить об уничтожении перечислителя по какой-то причине.
Примечание.
Прототип этого метода указывает элементы массива как тип T, где T был определен как параметр шаблона для класса. Это тот же тип, который предоставляется с помощью метода COM-интерфейса CComEnumImpl::Next. Это означает, что, в отличие от IEnumOnSTLImpl, этот класс не поддерживает различные типы данных и хранилища. Тип данных элементов в массиве должен совпадать с типом данных, предоставляемым с помощью com-интерфейса.
CComEnumImpl::Clone
Этот метод обеспечивает реализацию метода Clone путем создания объекта типа CComEnum, инициализации его с тем же массивом и итератором, используемым текущим объектом, и возвращая интерфейс в только что созданном объекте.
STDMETHOD(Clone)(Base** ppEnum);
Параметры
ppEnum
[out] Интерфейс перечислителя для только что созданного объекта, клонированного из текущего перечислителя.
Возвращаемое значение
Стандартное значение 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);
Параметры
кельт
[in] Количество запрошенных элементов.
rgelt
[out] Массив, заполненный элементами.
pceltFetched
[out] Количество элементов, возвращаемых в rgelt. Это может быть меньше сельта , если в списке осталось меньше элементов celt .
Возвращаемое значение
Стандартное значение HRESULT.
CComEnumImpl::Reset
Этот метод предоставляет реализацию метода Reset .
STDMETHOD(Reset)(void);
Возвращаемое значение
Стандартное значение HRESULT.
CComEnumImpl::Skip
Этот метод предоставляет реализацию метода Skip .
STDMETHOD(Skip)(ULONG celt);
Параметры
кельт
[in] Количество пропущенных элементов.
Возвращаемое значение
Стандартное значение HRESULT.
Замечания
Возвращает E_INVALIDARG если celt равно нулю, возвращает S_FALSE, если возвращаются меньше элементов celt , возвращает S_OK в противном случае.