Condividi tramite

Classe CComSafeArray

  • Articolo

Questa classe è un wrapper per la SAFEARRAY struttura.

Sintassi

template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray

Parametri

T
Tipo di dati da memorizzare nella matrice.

Membri

Costruttori pubblici

Nome Descrizione
CComSafeArray::CComSafeArray Costruttore.
CComSafeArray::~CComSafeArray Distruttore.

Metodi pubblici

Nome Descrizione
CComSafeArray::Add Aggiunge uno o più elementi, o una SAFEARRAY struttura, a un oggetto CComSafeArray.
CComSafeArray::Attach Associa una SAFEARRAY struttura a un CComSafeArray oggetto .
CComSafeArray::CopyFrom Copia il contenuto di una SAFEARRAY struttura nell'oggetto CComSafeArray .
CComSafeArray::CopyTo Crea una copia dell'oggetto CComSafeArray.
CComSafeArray::Create Crea un oggetto CComSafeArray.
CComSafeArray::Destroy Elimina un oggetto CComSafeArray .
CComSafeArray::Detach Scollega un oggetto SAFEARRAY da un CComSafeArray oggetto .
CComSafeArray::GetAt Recupera un singolo elemento da una matrice unidimensionale.
CComSafeArray::GetCount Restituisce il numero di elementi nella matrice.
CComSafeArray::GetDimensions Restituisce il numero di dimensioni nella matrice.
CComSafeArray::GetLowerBound Restituisce il limite inferiore di una determinata dimensione della matrice.
CComSafeArray::GetSafeArrayPtr Restituisce l'indirizzo del membro dati m_psa .
CComSafeArray::GetType Restituisce il tipo di dati memorizzati nella matrice.
CComSafeArray::GetUpperBound Restituisce il limite superiore di una determinata dimensione della matrice.
CComSafeArray::IsSizable Verifica se è possibile ridimensionare un oggetto CComSafeArray .
CComSafeArray::MultiDimGetAt Recupera un singolo elemento da una matrice multidimensionale.
CComSafeArray::MultiDimSetAt Imposta il valore di un elemento in una matrice multidimensionale.
CComSafeArray::Resize Ridimensiona un oggetto CComSafeArray .
CComSafeArray::SetAt Imposta il valore di un elemento in una matrice unidimensionale.

Operatori pubblici

Nome Descrizione
CComSafeArray::operator LPSAFEARRAY Esegue il cast di un valore a un SAFEARRAY puntatore.
CComSafeArray::operator[] Recupera un elemento da una matrice.
CComSafeArray::operator = Operatore di assegnazione.

Membri dati pubblici

Nome Descrizione
CComSafeArray::m_psa Questo membro dati contiene l'indirizzo della SAFEARRAY struttura.

Osservazioni:

CComSafeArray fornisce un wrapper per la SAFEARRAY classe del tipo di dati, semplificando la creazione e la gestione di matrici singole e multidimensionali di quasi tutti i tipi supportati VARIANT .

CComSafeArray semplifica il passaggio delle matrici tra processi e fornisce anche protezione aggiuntiva poiché controlla i valori degli indici della matrice rispetto ai limiti superiore e inferiore.

Il limite inferiore di una classe CComSafeArray può iniziare con qualsiasi valore definito dall'utente; tuttavia, le matrici a cui si accede con C++ usano un limite inferiore pari a 0. Altri linguaggi, quali Visual Basic, possono usare altri valori di delimitazione (ad esempio da -10 a 10).

Usare CComSafeArray::Create per creare un CComSafeArray oggetto e CComSafeArray::Destroy per eliminarlo.

Un CComSafeArray oggetto può contenere il sottoinsieme di tipi di VARIANT dati seguente:

VARTYPE Descrizione
VT_I1 char
VT_I2 short
VT_I4 int
VT_I4 long
VT_I8 longlong
VT_UI1 byte
VT_UI2 ushort
VT_UI4 uint
VT_UI4 ulong
VT_UI8 ulonglong
VT_R4 float
VT_R8 double
VT_DECIMAL Puntatore decimale
VT_VARIANT Puntatore Variant
VT_CY Currency (tipo di dati)

Requisiti

Intestazione:atlsafe.h

Esempio

// Create a multidimensional array, 
// then write and read elements

// Define an array of character pointers
CComSafeArray<char> *pSar;

char cElement;
char cTable[2][3] = {'A','B','C','D','E','F'};

// Declare the variable used to store the
// array indexes
LONG aIndex[2];

// Define the array bound structure
CComSafeArrayBound bound[2];
bound[0].SetCount(2);
bound[0].SetLowerBound(0);
bound[1].SetCount(3);
bound[1].SetLowerBound(0);   

// Create a new 2 dimensional array
// each dimension size is 3
pSar = new CComSafeArray<char>(bound,2); 

// Use MultiDimSetAt to store characters in the array
for (int x = 0; x < 2; x++)
{
   for (int y = 0; y < 3; y++)
   {
      aIndex[0] = x;
      aIndex[1] = y;
      HRESULT hr = pSar->MultiDimSetAt(aIndex,cTable[x][y]);
      ATLASSERT(hr == S_OK);
   }
}
// Use MultiDimGetAt to retrieve characters in the array
for (int x = 0; x < 2; x++)
{
   for (int y = 0; y < 3; y++)
   {
      aIndex[0]=x;
      aIndex[1]=y;
      HRESULT hr = pSar->MultiDimGetAt(aIndex,cElement);
      ATLASSERT(hr == S_OK);
      ATLASSERT(cElement == cTable[x][y]);
   }   
}

CComSafeArray::Add

Aggiunge uno o più elementi, o una SAFEARRAY struttura, a un oggetto CComSafeArray.

HRESULT Add(const SAFEARRAY* psaSrc);
HRESULT Add(ULONG ulCount, const T* pT, BOOL bCopy = TRUE);
HRESULT Add(const T& t, BOOL bCopy = TRUE);

Parametri

psaSrc
Puntatore a un oggetto SAFEARRAY.

ulCount
Numero di oggetti da aggiungere alla matrice.

pT
Puntatore a uno o più oggetti da aggiungere alla matrice.

t
Riferimento all'oggetto da aggiungere alla matrice.

bCopy
Indica se deve essere creata una copia dei dati. Il valore predefinito è TRUE.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

I nuovi oggetti vengono accodati alla fine dell'oggetto esistente SAFEARRAY . L'aggiunta di un oggetto a un oggetto multidimensionale SAFEARRAY non è supportata. Quando si aggiunge una matrice di oggetti esistente, entrambe le matrici devono contenere elementi dello stesso tipo.

Il bCopy flag viene preso in considerazione quando gli elementi di tipo BSTR o VARIANT vengono aggiunti a una matrice. Il valore predefinito di TRUE garantisce che venga creata una nuova copia dei dati quando l'elemento viene aggiunto alla matrice.

CComSafeArray::Attach

Associa una SAFEARRAY struttura a un CComSafeArray oggetto .

HRESULT Attach(const SAFEARRAY* psaSrc);

Parametri

psaSrc
Puntatore alla SAFEARRAY struttura.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Associa una SAFEARRAY struttura a un CComSafeArray oggetto, rendendo disponibili i metodi esistenti CComSafeArray .

CComSafeArray::CComSafeArray

Costruttore.

CComSafeArray();
CComSafeArray(const SAFEARRAYBOUND& bound);
CComSafeArray(ULONG  ulCount, LONG lLBound = 0);
CComSafeArray(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
CComSafeArray(const CComSafeArray& saSrc);
CComSafeArray(const SAFEARRAY& saSrc);
CComSafeArray(const SAFEARRAY* psaSrc);

Parametri

bound
Struttura SAFEARRAYBOUND.

ulCount
Numero di elementi nella matrice.

lLBound
Valore limite inferiore; ovvero l'indice del primo elemento nella matrice.

pBound
Puntatore a una SAFEARRAYBOUND struttura.

uDims
Conteggio delle dimensioni nella matrice.

saSrc
Riferimento a una struttura o CComSafeArray a un SAFEARRAY oggetto . In entrambi i casi, il costruttore usa questo riferimento per creare una copia della matrice, quindi la matrice non viene fatto riferimento dopo la costruzione.

psaSrc
Puntatore a una SAFEARRAY struttura. Il costruttore usa questo indirizzo per creare una copia della matrice, quindi la matrice non viene mai fatto riferimento dopo la costruzione.

Osservazioni:

Crea un oggetto CComSafeArray.

CComSafeArray::~CComSafeArray

Distruttore.

~CComSafeArray() throw()

Osservazioni:

Libera tutte le risorse allocate.

CComSafeArray::CopyFrom

Copia il contenuto di una SAFEARRAY struttura nell'oggetto CComSafeArray .

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parametri

ppArray
Puntatore all'oggetto SAFEARRAY da copiare.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Questo metodo copia il contenuto di un SAFEARRAY oggetto nell'oggetto corrente CComSafeArray . Il contenuto esistente della matrice viene sostituito.

CComSafeArray::CopyTo

Crea una copia dell'oggetto CComSafeArray.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parametri

ppArray
Puntatore a una posizione in cui creare il nuovo SAFEARRAYoggetto .

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Questo metodo copia il contenuto di un CComSafeArray oggetto in una SAFEARRAY struttura.

CComSafeArray::Create

Crea un oggetto CComSafeArray.

HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0);

Parametri

pBound
Puntatore a un oggetto SAFEARRAYBOUND.

uDims
Numero di dimensioni nella matrice.

ulCount
Numero di elementi nella matrice.

lLBound
Valore limite inferiore; ovvero l'indice del primo elemento nella matrice.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Un CComSafeArray oggetto può essere creato da una struttura esistente SAFEARRAYBOUND e dal numero di dimensioni oppure specificando il numero di elementi nella matrice e il limite inferiore. Se è necessario accedere alla matrice da C++, il limite inferiore deve essere 0. Altri linguaggi possono consentire altri valori per il limite inferiore, ad esempio Visual Basic supporta matrici con elementi con un intervallo compreso tra -10 e 10.

CComSafeArray::Destroy

Elimina un oggetto CComSafeArray .

HRESULT Destroy();

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Elimina definitivamente un oggetto esistente CComSafeArray e tutti i dati contenuti.

CComSafeArray::Detach

Scollega un oggetto SAFEARRAY da un CComSafeArray oggetto .

LPSAFEARRAY Detach();

Valore restituito

Restituisce un puntatore a un SAFEARRAY oggetto .

Osservazioni:

Questo metodo scollega l'oggetto SAFEARRAY dall'oggetto CComSafeArray .

CComSafeArray::GetAt

Recupera un singolo elemento da una matrice unidimensionale.

T& GetAt(LONG lIndex) const;

Parametri

lIndex
Numero di indice del valore nella matrice da restituire.

Valore restituito

Restituisce un riferimento all'elemento della matrice richiesto.

CComSafeArray::GetCount

Restituisce il numero di elementi nella matrice.

ULONG GetCount(UINT uDim = 0) const;

Parametri

uDim
Dimensione della matrice.

Valore restituito

Restituisce il numero di elementi nella matrice.

Osservazioni:

Se utilizzato con una matrice multidimensionale, questo metodo restituirà solo il numero di elementi in una dimensione specifica.

CComSafeArray::GetDimensions

Restituisce il numero di dimensioni nella matrice.

UINT GetDimensions() const;

Valore restituito

Restituisce il numero di dimensioni nella matrice.

CComSafeArray::GetLowerBound

Restituisce il limite inferiore di una determinata dimensione della matrice.

LONG GetLowerBound(UINT uDim = 0) const;

Parametri

uDim
Dimensione della matrice per la quale ottenere il limite inferiore. Se omesso, il valore predefinito è 0.

Valore restituito

Restituisce il limite inferiore.

Osservazioni:

Se il limite inferiore è 0, indica una matrice simile a C il cui primo elemento è il numero di elemento 0. In caso di errore, ad esempio, un argomento di dimensione non valido, questo metodo chiama AtlThrow con un oggetto HRESULT che descrive l'errore.

CComSafeArray::GetSafeArrayPtr

Restituisce l'indirizzo del membro dati m_psa .

LPSAFEARRAY* GetSafeArrayPtr() throw();

Valore restituito

Restituisce un puntatore al CComSafeArray::m_psa membro dati.

CComSafeArray::GetType

Restituisce il tipo di dati memorizzati nella matrice.

VARTYPE GetType() const;

Valore restituito

Restituisce il tipo di dati archiviati nella matrice, che può essere uno dei tipi seguenti:

VARTYPE Descrizione
VT_I1 char
VT_I2 short
VT_I4 int
VT_I4 long
VT_I8 longlong
VT_UI1 byte
VT_UI2 ushort
VT_UI4 uint
VT_UI4 ulong
VT_UI8 ulonglong
VT_R4 float
VT_R8 double
VT_DECIMAL Puntatore decimale
VT_VARIANT Puntatore Variant
VT_CY Currency (tipo di dati)

CComSafeArray::GetUpperBound

Restituisce il limite superiore di una determinata dimensione della matrice.

LONG GetUpperBound(UINT uDim = 0) const;

Parametri

uDim
Dimensione della matrice per la quale ottenere il limite superiore. Se omesso, il valore predefinito è 0.

Valore restituito

Restituisce il limite superiore. Questo valore è inclusivo, ovvero l'indice massimo valido per questa dimensione.

Osservazioni:

In caso di errore, ad esempio, un argomento di dimensione non valido, questo metodo chiama AtlThrow con un oggetto HRESULT che descrive l'errore.

CComSafeArray::IsSizable

Verifica se è possibile ridimensionare un oggetto CComSafeArray .

bool IsSizable() const;

Valore restituito

Restituisce TRUE se l'oggetto CComSafeArray può essere ridimensionato, FALSE se non è possibile.

CComSafeArray::m_psa

Contiene l'indirizzo della SAFEARRAY struttura a cui si accede.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Recupera un singolo elemento da una matrice multidimensionale.

HRESULT MultiDimGetAt(const LONG* alIndex, T& t);

Parametri

alIndex
Puntatore a un vettore di indici per ogni dimensione nella matrice. La dimensione più a sinistra (più significativa) è alIndex[0].

t
Riferimento ai dati restituiti.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

CComSafeArray::MultiDimSetAt

Imposta il valore di un elemento in una matrice multidimensionale.

HRESULT MultiDimSetAt(const LONG* alIndex, const T& t);

Parametri

alIndex
Puntatore a un vettore di indici per ogni dimensione nella matrice. La dimensione più a destra (meno significativa) è alIndex[0].

T
Specifica il valore del nuovo elemento.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Si tratta di una versione multidimensionale di CComSafeArray::SetAt.

CComSafeArray::operator []

Recupera un elemento da una matrice.

T& operator[](long lindex) const;
T& operator[]int nindex) const;

Parametri

lIndex, nIndex
Numero di indice dell'elemento obbligatorio nella matrice.

Valore restituito

Restituisce l'elemento di matrice appropriato.

Osservazioni:

Esegue una funzione simile a CComSafeArray::GetAt, ma questo operatore funziona solo con matrici unidimensionali.

CComSafeArray::operator =

Operatore di assegnazione.

ATL::CComSafeArray<T>& operator=(const ATL::CComSafeArray& saSrc);
ATL::CComSafeArray<T>& operator=(const SAFEARRAY* psaSrc);

Parametri

saSrc
Riferimento a un oggetto CComSafeArray.

psaSrc
Puntatore a un oggetto SAFEARRAY.

Valore restituito

Restituisce il tipo di dati memorizzati nella matrice.

CComSafeArray::operator LPSAFEARRAY

Esegue il cast di un valore a un SAFEARRAY puntatore.

operator LPSAFEARRAY() const;

Valore restituito

Esegue il cast di un valore a un SAFEARRAY puntatore.

CComSafeArray::Resize

Ridimensiona un oggetto CComSafeArray .

HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);

Parametri

pBound
Puntatore a una SAFEARRAYBOUND struttura che contiene informazioni sul numero di elementi e sul limite inferiore di una matrice.

ulCount
Numero richiesto di oggetti nella matrice ridimensionata.

lLBound
Limite inferiore.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Questo metodo ridimensiona solo la dimensione più a destra. Non ridimensiona le matrici che restituiscono IsResizable come FALSE.

CComSafeArray::SetAt

Imposta il valore di un elemento in una matrice unidimensionale.

HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE);

Parametri

lIndex
Numero di indice dell'elemento della matrice da impostare.

t
Nuovo valore dell'elemento specificato.

bCopy
Indica se deve essere creata una copia dei dati. Il valore predefinito è TRUE.

Valore restituito

Restituisce S_OK l'esito positivo o un errore in caso di errore HRESULT .

Osservazioni:

Il bCopy flag viene preso in considerazione quando gli elementi di tipo BSTR o VARIANT vengono aggiunti a una matrice. Il valore predefinito di TRUE garantisce che venga creata una nuova copia dei dati quando l'elemento viene aggiunto alla matrice.

Vedi anche

SAFEARRAY Tipo di dati
CComSafeArray::Create
CComSafeArray::Destroy
Cenni preliminari sulla classe