Classe CComSafeArray

  • Artigo

Essa classe é um wrapper para a estrutura SAFEARRAY.

Sintaxe

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

Parâmetros

T
O tipo de dados a serem armazenados na matriz.

Membros

Construtores públicos

Nome Descrição
CComSafeArray::CComSafeArray O construtor .
CComSafeArray::~CComSafeArray O destruidor.

Métodos públicos

Nome Descrição
CComSafeArray::Add Adiciona um ou mais elementos, ou uma estrutura SAFEARRAY, a um CComSafeArray.
CComSafeArray::Attach Anexa uma estrutura SAFEARRAY a um objeto CComSafeArray.
CComSafeArray::CopyFrom Copia o conteúdo de uma estrutura SAFEARRAY no objeto CComSafeArray.
CComSafeArray::CopyTo Cria uma cópia do objeto CComSafeArray.
CComSafeArray::Create Cria um objeto CComSafeArray.
CComSafeArray::Destroy Destrói um objeto CComSafeArray.
CComSafeArray::Detach Desanexa um SAFEARRAY de um objeto CComSafeArray.
CComSafeArray::GetAt Recupera um único elemento de uma matriz unidimensional.
CComSafeArray::GetCount Retorna o número de elementos na matriz.
CComSafeArray::GetDimensions Retorna o número de dimensões na matriz.
CComSafeArray::GetLowerBound Retorna o limite inferior de uma determinada dimensão da matriz.
CComSafeArray::GetSafeArrayPtr Retorna o endereço do membro de dados m_psa.
CComSafeArray::GetType Retorna o tipo dos dados armazenados na matriz.
CComSafeArray::GetUpperBound Retorna o limite superior de qualquer dimensão da matriz.
CComSafeArray::IsSizable Testa se um objeto CComSafeArray pode ser redimensionado.
CComSafeArray::MultiDimGetAt Recupera um único elemento de uma matriz multidimensional.
CComSafeArray::MultiDimSetAt Define o valor de um elemento em uma matriz multidimensional.
CComSafeArray::Resize Redimensiona um objeto CComSafeArray.
CComSafeArray::SetAt Define o valor de um elemento em uma matriz unidimensional.

Operadores públicos

Nome Descrição
CComSafeArray::operator LPSAFEARRAY Converte um valor em um ponteiro SAFEARRAY.
CComSafeArray::operator[] Recupera um elemento da matriz.
CComSafeArray::operator = Operador de atribuição.

Membros de Dados Públicos

Nome Descrição
CComSafeArray::m_psa Esse membro de dados contém o endereço da estrutura SAFEARRAY.

Comentários

A CComSafeArray fornece um wrapper para a classe tipo de dados SAFEARRAY, simplificando a criação e o gerenciamento de matrizes uni e multidimensionais de quase qualquer dos tipos VARIANT com suporte.

A CComSafeArray simplifica a passagem de matrizes entre processos e, além disso, fornece segurança extra verificando valores de índice de matriz em relação aos limites superiores e inferiores.

O limite inferior de uma CComSafeArray pode começar em qualquer valor definido pelo usuário; no entanto, as matrizes acessadas por meio do C++ devem usar um limite inferior igual a 0. Outras linguagens, como o Visual Basic, podem usar outros valores de limite (por exemplo, -10 a 10).

Use CComSafeArray::Create para criar um objeto CComSafeArray e CComSafeArray::Destroy para excluí-lo.

Um CComSafeArray pode conter o seguinte subconjunto de tipos de dados VARIANT:

VARTYPE Descrição
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 ponteiro decimal
VT_VARIANT ponteiro variante
VT_CY tipo de dados Currency

Requisitos

Cabeçalhoatlsafe.h:

Exemplo

// 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

Adiciona um ou mais elementos, ou uma estrutura SAFEARRAY, a um CComSafeArray.

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

Parâmetros

psaSrc
Um ponteiro para um objeto SAFEARRAY.

ulCount
O número de objetos a serem adicionados à matriz.

pT
Um ponteiro para um ou mais objetos a serem adicionados à matriz.

t
Uma referência ao objeto a ser adicionado à matriz.

bCopy
Indica se uma cópia dos dados deve ser criada. O valor padrão é TRUE.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Os novos objetos são acrescentados ao final do objeto existente SAFEARRAY. Não há suporte para adicionar um objeto a um objeto multidimensional SAFEARRAY. Para adicionar uma matriz existente de objetos, ambas as matrizes devem conter elementos do mesmo tipo.

O sinalizador bCopy é levado em conta quando elementos do tipo BSTR ou VARIANT são adicionados a uma matriz. O valor padrão TRUE garante que uma nova cópia seja feita dos dados quando o elemento é adicionado à matriz.

CComSafeArray::Attach

Anexa uma estrutura SAFEARRAY a um objeto CComSafeArray.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parâmetros

psaSrc
Um ponteiro para a estrutura SAFEARRAY.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Anexa uma estrutura SAFEARRAY a um CComSafeArray objeto, disponibilizando os métodos existentes CComSafeArray.

CComSafeArray::CComSafeArray

O construtor .

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);

Parâmetros

bound
Uma estrutura SAFEARRAYBOUND.

ulCount
O número de elementos na matriz.

lLBound
O valor de limite inferior; ou seja, o índice do primeiro elemento na matriz.

pBound
Um ponteiro para uma estrutura SAFEARRAYBOUND.

uDims
A contagem de dimensões na matriz.

saSrc
Uma referência a uma estrutura SAFEARRAY ou um objeto CComSafeArray. Em ambos os casos, o construtor usa essa referência para fazer uma cópia da matriz, de modo que a matriz não seja referenciada após a construção.

psaSrc
Um ponteiro para uma estrutura SAFEARRAY. O construtor usa esse endereço para fazer uma cópia da matriz, portanto, a matriz nunca é referenciada após a construção.

Comentários

Cria um objeto CComSafeArray.

CComSafeArray::~CComSafeArray

O destruidor.

~CComSafeArray() throw()

Comentários

Libera todos os recursos alocados.

CComSafeArray::CopyFrom

Copia o conteúdo de uma estrutura SAFEARRAY no objeto CComSafeArray.

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parâmetros

ppArray
Ponteiro para a SAFEARRAY a ser copiada.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Esse método copia o conteúdo de um SAFEARRAY no objeto CComSafeArray atual. O conteúdo existente da matriz é substituído.

CComSafeArray::CopyTo

Cria uma cópia do objeto CComSafeArray.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parâmetros

ppArray
Um ponteiro para um local no qual criar o novo SAFEARRAY.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Esse método copia o conteúdo de um objeto CComSafeArray em uma estrutura SAFEARRAY.

CComSafeArray::Create

Cria um CComSafeArray.

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

Parâmetros

pBound
Um ponteiro para um objeto SAFEARRAYBOUND.

uDims
O número de dimensões na matriz.

ulCount
O número de elementos na matriz.

lLBound
O valor de limite inferior; ou seja, o índice do primeiro elemento na matriz.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Um objeto CComSafeArray pode ser criado com base em uma estrutura existente SAFEARRAYBOUND e no número de dimensões ou especificando o número de elementos na matriz e no limite inferior. Se a matriz for acessada no C++, o limite inferior deverá ser 0. Outras linguagens podem permitir outros valores para o limite inferior (por exemplo, o Visual Basic dá suporte a matrizes com elementos com um intervalo como -10 a 10).

CComSafeArray::Destroy

Destrói um objeto CComSafeArray.

HRESULT Destroy();

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Destrói um objeto existente CComSafeArray e todos os dados que ele contém.

CComSafeArray::Detach

Desanexa um SAFEARRAY de um objeto CComSafeArray.

LPSAFEARRAY Detach();

Retornar valor

Um ponteiro para um objeto SAFEARRAY.

Comentários

Esse método desanexa o objeto SAFEARRAY do objeto CComSafeArray.

CComSafeArray::GetAt

Recupera um único elemento de uma matriz unidimensional.

T& GetAt(LONG lIndex) const;

Parâmetros

lIndex
O número de índice do valor na matriz a ser retornada.

Retornar valor

Retorna uma referência ao elemento exigido da matriz.

CComSafeArray::GetCount

Retorna o número de elementos na matriz.

ULONG GetCount(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão da matriz.

Retornar valor

Retorna o número de elementos na matriz.

Comentários

Quando usado com uma matriz multidimensional, esse método retornará o número de elementos somente em uma dimensão específica.

CComSafeArray::GetDimensions

Retorna o número de dimensões na matriz.

UINT GetDimensions() const;

Retornar valor

Retorna o número de dimensões na matriz.

CComSafeArray::GetLowerBound

Retorna o limite inferior de uma determinada dimensão da matriz.

LONG GetLowerBound(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão da matriz da qual obter o limite inferior. Se omitido, o padrão será 0.

Retornar valor

Retorna o limite inferior.

Comentários

Se o limite inferior for 0, indicará uma matriz no estilo C cujo primeiro elemento é o elemento número 0. No caso de um erro, por exemplo, um argumento de dimensão inválido, esse método chamará AtlThrow com uma HRESULT descrevendo o erro.

CComSafeArray::GetSafeArrayPtr

Retorna o endereço do membro de dados m_psa.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Retornar valor

Retorna um ponteiro para o membro de dados CComSafeArray::m_psa.

CComSafeArray::GetType

Retorna o tipo dos dados armazenados na matriz.

VARTYPE GetType() const;

Retornar valor

Retorna o tipo de dados armazenados na matriz, que pode ser qualquer um dos seguintes tipos:

VARTYPE Descrição
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 ponteiro decimal
VT_VARIANT ponteiro variante
VT_CY tipo de dados Currency

CComSafeArray::GetUpperBound

Retorna o limite superior de qualquer dimensão da matriz.

LONG GetUpperBound(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão da matriz da qual obter o limite superior. Se omitido, o padrão será 0.

Retornar valor

Retorna o limite superior. Esse valor é inclusivo, o índice máximo válido para essa dimensão.

Comentários

No caso de um erro, por exemplo, um argumento de dimensão inválido, esse método chamará AtlThrow com uma HRESULT descrevendo o erro.

CComSafeArray::IsSizable

Testa se um objeto CComSafeArray pode ser redimensionado.

bool IsSizable() const;

Retornar valor

Retornará TRUE se CComSafeArray puder ser redimensionado, FALSE se não puder.

CComSafeArray::m_psa

Contém o endereço da estrutura da SAFEARRAY acessada.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Recupera um único elemento de uma matriz multidimensional.

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

Parâmetros

alIndex
Ponteiro para um vetor de índices para cada dimensão na matriz. A dimensão mais à esquerda (mais significativa) é alIndex[0].

t
Uma referência aos dados retornados.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

CComSafeArray::MultiDimSetAt

Define o valor de um elemento em uma matriz multidimensional.

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

Parâmetros

alIndex
Ponteiro para um vetor de índices para cada dimensão na matriz. A dimensão mais à direita (menos significativa) é alIndex[0].

T
Especifica o valor do novo elemento.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Esta é uma versão multidimensional da CComSafeArray::SetAt.

CComSafeArray::operator []

Recupera um elemento da matriz.

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

Parâmetros

lIndex, nIndex
O número de índice do elemento necessário na matriz.

Retornar valor

Retorna o elemento da matriz apropriado.

Comentários

Executa uma função semelhante a CComSafeArray::GetAt, no entanto, esse operador só funciona com matrizes unidimensionais.

CComSafeArray::operator =

Operador de atribuição.

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

Parâmetros

saSrc
Uma referência a um objeto CComSafeArray.

psaSrc
Um ponteiro para um objeto SAFEARRAY.

Retornar valor

Retorna o tipo dos dados armazenados na matriz.

CComSafeArray::operator LPSAFEARRAY

Converte um valor em um ponteiro SAFEARRAY.

operator LPSAFEARRAY() const;

Retornar valor

Converte um valor em um ponteiro SAFEARRAY.

CComSafeArray::Resize

Redimensiona um objeto CComSafeArray.

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

Parâmetros

pBound
Um ponteiro para uma estrutura SAFEARRAYBOUND que contém informações sobre o número de elementos e o limite inferior de uma matriz.

ulCount
O número solicitado de objetos na matriz redimensionada.

lLBound
O limite inferior.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

Esse método só redimensiona a dimensão mais à direita. Ele não redimensionará matrizes que retornam IsResizable como FALSE.

CComSafeArray::SetAt

Define o valor de um elemento em uma matriz unidimensional.

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

Parâmetros

lIndex
O número de índice do elemento da matriz a ser definido.

t
O novo valor do elemento especificado.

bCopy
Indica se uma cópia dos dados deve ser criada. O valor padrão é TRUE.

Retornar valor

Retorna S_OK se houver êxito ou um erro HRESULT se houver falha.

Comentários

O sinalizador bCopy é levado em conta quando elementos do tipo BSTR ou VARIANT são adicionados a uma matriz. O valor padrão TRUE garante que uma nova cópia seja feita dos dados quando o elemento é adicionado à matriz.

Confira também

Tipo de dados SAFEARRAY
CComSafeArray::Create
CComSafeArray::Destroy
Visão geral da classe