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

Metodi pubblici

Membri dati pubblici

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++.

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.

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