Classe CComEnumImpl

Questa classe fornisce l'implementazione per un'interfaccia dell'enumeratore COM in cui gli elementi enumerati vengono archiviati in una matrice.

Sintassi

template <class Base,
    const IID* piid, class T, class Copy>
class ATL_NO_VTABLE CComEnumImpl : public Base

Parametri

Base
Interfaccia dell'enumeratore COM. Per un esempio, vedere IEnumString .

piid
Puntatore all'ID interfaccia dell'interfaccia dell'enumeratore.

T
Tipo di elemento esposto dall'interfaccia dell'enumeratore.

Copia
Classe di criteri di copia omogenea.

Membri

Costruttori pubblici

Nome	Descrizione
CComEnumImpl::CComEnumImpl	Costruttore.
CComEnumImpl::~CComEnumImpl	Distruttore.

Metodi pubblici

Nome	Descrizione
CComEnumImpl::Clone	Implementazione del metodo di interfaccia di enumerazione Clone .
CComEnumImpl::Init	Inizializza l'enumeratore.
CComEnumImpl::Next	Implementazione di Next.
CComEnumImpl::Reset	Implementazione di Reset.
CComEnumImpl::Skip	Implementazione di Skip.

Membri dati pubblici

Nome	Descrizione
CComEnumImpl::m_begin	Puntatore al primo elemento della matrice.
CComEnumImpl::m_dwFlags	Flag di copia passati tramite Init.
CComEnumImpl::m_end	Puntatore alla posizione immediatamente successiva all'ultimo elemento della matrice.
CComEnumImpl::m_iter	Puntatore all'elemento corrente nella matrice.
CComEnumImpl::m_spUnk	Puntatore IUnknown dell'oggetto che fornisce l'insieme da enumerare.

Osservazioni:

Per un esempio di implementazioni del metodo, vedere IEnumString . CComEnumImpl fornisce l'implementazione per un'interfaccia dell'enumeratore COM in cui gli elementi enumerati vengono archiviati in una matrice. Questa classe è analoga alla IEnumOnSTLImpl classe , che fornisce un'implementazione di un'interfaccia enumeratore basata su un contenitore della libreria standard C++.

Nota

Per informazioni dettagliate sulle altre differenze tra CComEnumImpl e , vedere CComEnumImpl::InitIEnumOnSTLImpl.

In genere, non sarà necessario creare una classe enumeratore personalizzata derivando da questa implementazione dell'interfaccia. Se si vuole usare un enumeratore fornito da ATL basato su una matrice, è più comune creare un'istanza di CComEnum.

Tuttavia, se è necessario fornire un enumeratore personalizzato (ad esempio, uno che espone interfacce oltre all'interfaccia dell'enumeratore), è possibile derivare da questa classe. In questa situazione, è probabile che sia necessario eseguire l'override del metodo CComEnumImpl::Clone per fornire la propria implementazione.

Per altre informazioni, vedere Raccolte e enumeratori ATL.

Gerarchia di ereditarietà

Base

CComEnumImpl

Requisiti

Intestazione: atlcom.h

CComEnumImpl::CComEnumImpl

Costruttore.

CComEnumImpl();

CComEnumImpl::~CComEnumImpl

Distruttore.

~CComEnumImpl();

CComEnumImpl::Init

È necessario chiamare questo metodo prima di passare un puntatore all'interfaccia dell'enumeratore a tutti i client.

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

Parametri

begin
Puntatore al primo elemento della matrice contenente gli elementi da enumerare.

end
Puntatore alla posizione immediatamente successiva all'ultimo elemento della matrice contenente gli elementi da enumerare.

Punk
[in] Puntatore IUnknown di un oggetto che deve essere mantenuto attivo durante la durata dell'enumeratore. Passare NULL se non esiste alcun oggetto di questo tipo.

flags
Flag che specificano se l'enumeratore deve assumere la proprietà della matrice o crearne una copia. I valori possibili sono descritti di seguito.

Valore restituito

Valore HRESULT standard.

Osservazioni:

Chiamare questo metodo una sola volta: inizializzare l'enumeratore, usarlo e quindi eliminarlo.

Se si passano puntatori a elementi in una matrice contenuta in un altro oggetto (e non si chiede all'enumeratore di copiare i dati), è possibile usare il parametro pUnk per assicurarsi che l'oggetto e la matrice che contiene siano disponibili per tutto il tempo necessario all'enumeratore. L'enumeratore contiene semplicemente un riferimento COM sull'oggetto per mantenerlo attivo. Il riferimento COM viene rilasciato automaticamente quando l'enumeratore viene eliminato definitivamente.

Il parametro flags consente di specificare il modo in cui l'enumeratore deve trattare gli elementi della matrice passati. I flag possono accettare uno dei valori dell'enumerazione CComEnumFlags illustrata di seguito:

enum CComEnumFlags
   {
   AtlFlagNoCopy = 0,
   AtlFlagTakeOwnership = 2, // BitOwn
   AtlFlagCopy = 3           // BitOwn | BitCopy
   };

AtlFlagNoCopy significa che la durata della matrice non è controllata dall'enumeratore. In questo caso, la matrice sarà statica o l'oggetto identificato da pUnk sarà responsabile della liberazione della matrice quando non è più necessario.

AtlFlagTakeOwnership significa che la distruzione della matrice deve essere controllata dall'enumeratore. In questo caso, la matrice deve essere stata allocata dinamicamente usando new. L'enumeratore eliminerà la matrice nel distruttore. In genere, si passa NULL per pUnk, anche se è comunque possibile passare un puntatore valido se è necessario ricevere una notifica della distruzione dell'enumeratore per qualche motivo.

AtlFlagCopy significa che una nuova matrice deve essere creata copiando la matrice passata a Init. La durata della nuova matrice deve essere controllata dall'enumeratore. L'enumeratore eliminerà la matrice nel distruttore. In genere, si passa NULL per pUnk, anche se è comunque possibile passare un puntatore valido se è necessario ricevere una notifica della distruzione dell'enumeratore per qualche motivo.

Nota

Il prototipo di questo metodo specifica gli elementi della matrice come di tipo T, dove T è stato definito come parametro di modello per la classe . Si tratta dello stesso tipo esposto tramite il metodo di interfaccia COM CComEnumImpl::Next. L'implicazione di questo è che, a differenza di IEnumOnSTLImpl, questa classe non supporta diversi tipi di archiviazione ed esposti. Il tipo di dati degli elementi nella matrice deve essere uguale al tipo di dati esposto tramite l'interfaccia COM.

CComEnumImpl::Clone

Questo metodo fornisce l'implementazione del metodo Clone creando un oggetto di tipo CComEnum, inizializzandolo con la stessa matrice e iteratore usato dall'oggetto corrente e restituendo l'interfaccia sull'oggetto appena creato.

STDMETHOD(Clone)(Base** ppEnum);

Parametri

ppEnum
[out] Interfaccia dell'enumeratore in un oggetto appena creato clonato dall'enumeratore corrente.

Valore restituito

Valore HRESULT standard.

Osservazioni:

Si noti che gli enumeratori clonati non effettuano mai la propria copia (o prendono la proprietà) dei dati usati dall'enumeratore originale. Se necessario, gli enumeratori clonati manterranno attivo l'enumeratore originale (usando un riferimento COM) per assicurarsi che i dati siano disponibili per tutto il tempo necessario.

CComEnumImpl::m_spUnk

Questo puntatore intelligente mantiene un riferimento sull'oggetto passato a CComEnumImpl::Init, assicurandosi che rimanga attivo durante la durata dell'enumeratore.

CComPtr<IUnknown> m_spUnk;

CComEnumImpl::m_begin

Puntatore alla posizione immediatamente successiva all'ultimo elemento della matrice contenente gli elementi da enumerare.

T* m_begin;

CComEnumImpl::m_end

Puntatore al primo elemento della matrice contenente gli elementi da enumerare.

T* m_end;

CComEnumImpl::m_iter

Puntatore all'elemento corrente della matrice contenente gli elementi da enumerare.

T* m_iter;

CComEnumImpl::m_dwFlags

Flag passati a CComEnumImpl::Init.

DWORD m_dwFlags;

CComEnumImpl::Next

Questo metodo fornisce l'implementazione del metodo Next .

STDMETHOD(Next)(ULONG celt, T* rgelt, ULONG* pceltFetched);

Parametri

celta
[in] Numero di elementi richiesti.

rgelt
[out] Matrice da riempire con gli elementi.

pceltFetched
[out] Numero di elementi effettivamente restituiti in rgelt. Può essere minore di celt se nell'elenco rimangono meno di elementi celt .

Valore restituito

Valore HRESULT standard.

CComEnumImpl::Reset

Questo metodo fornisce l'implementazione del metodo Reset .

STDMETHOD(Reset)(void);

Valore restituito

Valore HRESULT standard.

CComEnumImpl::Skip

Questo metodo fornisce l'implementazione del metodo Skip .

STDMETHOD(Skip)(ULONG celt);

Parametri

celta
[in] Numero di elementi da ignorare.

Valore restituito

Valore HRESULT standard.

Osservazioni:

Restituisce E_INVALIDARG se celt è zero, restituisce S_FALSE se vengono restituiti elementi meno di celt , restituisce S_OK in caso contrario.

Vedi anche

Classe IEnumOnSTLImpl
Classe CComEnum
Cenni preliminari sulla classe