CComSafeArray Classe

Esta classe é um envelope para a SAFEARRAY estrutura.

Sintaxe

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

Parâmetros

T
O tipo de dados a armazenar no array.

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Membros de Dados Públicos

Observações

CComSafeArray fornece um wrapper para a SAFEARRAY classe de tipo de dados , tornando simples a criação e gestão de arrays unidimensionais e multidimensionais de quase qualquer um dos tipos suportados VARIANT .

CComSafeArray Simplifica a passagem de arrays entre processos e, adicionalmente, proporciona segurança adicional ao verificar os valores do índice de array em relação aos limites superior e inferior.

O limite inferior de a CComSafeArray pode começar em qualquer valor definido pelo utilizador; no entanto, os arrays acedidos através de C++ devem usar um limite inferior de 0. Outras linguagens, como o Visual Basic, podem usar outros valores de delimitação (por exemplo, de -10 a 10).

Use CComSafeArray::Create para criar um CComSafeArray objeto e CComSafeArray::Destroy para o apagar.

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

Requerimentos

Cabeçalho:atlsafe.h

Example

// 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 SAFEARRAY estrutura, 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 SAFEARRAY objeto.

ulCount
O número de objetos a adicionar ao array.

pT
Um apontador para um ou mais objetos a serem adicionados ao array.

t
Uma referência ao objeto a ser adicionado ao array.

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

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Os novos objetos são adicionados ao final do objeto existente SAFEARRAY . Adicionar um objeto a um objeto multidimensional SAFEARRAY não é suportado. Ao adicionar um array existente de objectos, ambos os arrays devem conter elementos do mesmo tipo.

O bCopy flag é tido em conta quando elementos do tipo BSTR ou VARIANT são adicionados a um array. O valor padrão de TRUE garante que é feita uma nova cópia dos dados quando o elemento é adicionado ao array.

CComSafeArray::Attach

Anexa uma SAFEARRAY estrutura a um CComSafeArray objeto.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parâmetros

psaSrc
Um apontador para a SAFEARRAY estrutura.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Anexa uma SAFEARRAY estrutura a um CComSafeArray objeto, tornando os métodos existentes CComSafeArray disponíveis.

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 SAFEARRAYBOUND estrutura.

ulCount
O número de elementos na matriz.

lLBound
O valor do limite inferior; isto é, o índice do primeiro elemento do array.

pBound
Um ponteiro para uma SAFEARRAYBOUND estrutura.

uDims
A contagem das dimensões na matriz.

saSrc
Uma referência a uma SAFEARRAY estrutura ou CComSafeArray objeto. Em qualquer dos casos, o construtor usa esta referência para fazer uma cópia do array, pelo que o array não é referenciado após a construção.

psaSrc
Um ponteiro para uma SAFEARRAY estrutura. O construtor usa este endereço para fazer uma cópia do array, pelo que o array nunca é referenciado após a construção.

Observações

Cria um objeto CComSafeArray.

CComSafeArray::~CComSafeArray

O destruidor.

~CComSafeArray() throw()

Observações

Liberta todos os recursos alocados.

CComSafeArray::CopyFrom

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

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parâmetros

ppArray
Apontar para o SAFEARRAY para copiar.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Este método copia o conteúdo de a SAFEARRAY para o objeto atual CComSafeArray . O conteúdo existente do array é substituído.

CComSafeArray::CopyTo

Cria uma cópia do CComSafeArray objeto.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parâmetros

ppArray
Um ponteiro para um local onde criar o novo SAFEARRAY.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Este método copia o conteúdo de um CComSafeArray objeto numa SAFEARRAY estrutura.

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 SAFEARRAYBOUND objeto.

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

ulCount
O número de elementos na matriz.

lLBound
O valor do limite inferior; isto é, o índice do primeiro elemento do array.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Um CComSafeArray objeto pode ser criado a partir de uma estrutura existente SAFEARRAYBOUND e do número de dimensões, ou especificando o número de elementos no array e o limite inferior. Se o array for acedido a partir de C++, o limite inferior deve ser 0. Outras linguagens podem permitir outros valores para o limite inferior (por exemplo, o Visual Basic suporta arrays com elementos com um intervalo como -10 a 10).

CComSafeArray::Destroy

Destrói um CComSafeArray objeto.

HRESULT Destroy();

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

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

CComSafeArray::Detach

Desliga a SAFEARRAY de um CComSafeArray objeto.

LPSAFEARRAY Detach();

Valor de retorno

Devolve um ponteiro para um SAFEARRAY objeto.

Observações

Este método separa o SAFEARRAY objeto do objeto CComSafeArray .

CComSafeArray::GetAt

Recupera um único elemento de um array unidimensional.

T& GetAt(LONG lIndex) const;

Parâmetros

lIndex
O número de índice do valor no array a devolver.

Valor de retorno

Devolve uma referência ao elemento do array requerido.

CComSafeArray::GetCount

Devolve o número de elementos no array.

ULONG GetCount(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão do array.

Valor de retorno

Devolve o número de elementos no array.

Observações

Quando usado com um array multidimensional, este método devolve apenas o número de elementos numa dimensão específica.

CComSafeArray::GetDimensions

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

UINT GetDimensions() const;

Valor de retorno

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

CComSafeArray::GetLowerBound

Devolve o limite inferior para uma dada dimensão do array.

LONG GetLowerBound(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão do array para a qual se obtém o limite inferior. Se for omitido, o padrão é 0.

Valor de retorno

Devolve o limite inferior.

Observações

Se o limite inferior for 0, isto indica um array semelhante a C cujo primeiro elemento é o elemento número 0. No caso de um erro, por exemplo, um argumento de dimensão inválido, este método chama AtlThrow com um HRESULT descrevendo o erro.

CComSafeArray::GetSafeArrayPtr

Devolve o endereço do m_psa membro de dados.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Valor de retorno

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

CComSafeArray::GetType

Devolve o tipo de dados armazenados no array.

VARTYPE GetType() const;

Valor de retorno

Devolve o tipo de dados armazenados no array, que pode ser qualquer um dos seguintes tipos:

CComSafeArray::GetUpperBound

Devolve o limite superior para qualquer dimensão do array.

LONG GetUpperBound(UINT uDim = 0) const;

Parâmetros

uDim
A dimensão do array para a qual se obtém o limite superior. Se for omitido, o padrão é 0.

Valor de retorno

Devolve o limite superior. Este valor é inclusivo, o índice máximo válido para esta dimensão.

Observações

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

CComSafeArray::IsSizable

Testa se um CComSafeArray objeto pode ser redimensionado.

bool IsSizable() const;

Valor de retorno

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

CComSafeArray::m_psa

Detém o endereço da SAFEARRAY estrutura acedida.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Recupera um único elemento de um array multidimensional.

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

Parâmetros

alIndex
Apontar para um vetor de índices para cada dimensão no array. A dimensão mais à esquerda (mais significativa) é alIndex[0].

t
Uma referência aos dados devolvidos.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

CComSafeArray::MultiDimSetAt

Define o valor de um elemento num array multidimensional.

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

Parâmetros

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

T
Especifica o valor do novo elemento.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

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

CComSafeArray::operator []

Recupera um elemento do array.

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

Parâmetros

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

Valor de retorno

Devolve o elemento do array apropriado.

Observações

Desempenha uma função semelhante a CComSafeArray::GetAt, no entanto, este operador só funciona com arrays 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 SAFEARRAY objeto.

Valor de retorno

Devolve o tipo de dados armazenados no array.

CComSafeArray::operator LPSAFEARRAY

Atribui um valor a um SAFEARRAY apontador.

operator LPSAFEARRAY() const;

Valor de retorno

Atribui um valor a um SAFEARRAY apontador.

CComSafeArray::Resize

Redimensiona um CComSafeArray objeto.

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

Parâmetros

pBound
Um apontador para uma SAFEARRAYBOUND estrutura que contém informação sobre o número de elementos e o limite inferior de um array.

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

lLBound
O limite inferior.

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

Este método apenas redimensiona a dimensão mais à direita. Não irá redimensionar arrays que retornam IsResizable como FALSE.

CComSafeArray::SetAt

Define o valor de um elemento num array unidimensional.

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

Parâmetros

lIndex
O número de índice do elemento do array a definir.

t
O novo valor do elemento especificado.

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

Valor de retorno

Retornos S_OK do sucesso, ou um erro HRESULT em caso de falha.

Observações

O bCopy flag é tido em conta quando elementos do tipo BSTR ou VARIANT são adicionados a um array. O valor padrão de TRUE garante que é feita uma nova cópia dos dados quando o elemento é adicionado ao array.

Consulte também

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