Classe COleSafeArray

Uma classe para trabalhar com arrays de tipo e dimensão arbitrários.

Sintaxe

class COleSafeArray : public tagVARIANT

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

COleSafeArray deriva da estrutura OLE VARIANT . As funções membros OLE SAFEARRAY estão disponíveis através COleSafeArrayde , bem como um conjunto de funções membros especificamente concebidas para arrays unidimensionais de bytes.

Hierarquia de herança

tagVARIANT

COleSafeArray

Requerimentos

Cabeçalho: afxdisp.h

COleSafeArray::AccessData

Recupera um ponteiro para os dados do array.

void AccessData(void** ppvData);

Parâmetros

ppvData
Um ponteiro para um ponteiro para os dados do array.

Observações

Em caso de erro, a função lança uma CMemoryException ou COleException.

Example

void CMainFrame::Sort(VARIANT* vArray)
{
   COleSafeArray sa;
   BSTR* pbstr;
   TCHAR buf[1024];
   LONG cElements, lLBound, lUBound;

   //needed for OLE2T macro below, include afxpriv.h
   USES_CONVERSION;

   // Type check VARIANT parameter. It should contain a BSTR array
   // passed by reference. The array must be passed by reference it is
   // an in-out-parameter.
   if (V_VT(vArray) != (VT_ARRAY | VT_BSTR))
   {
      AfxThrowOleDispatchException(1001,
         _T("Type Mismatch in Parameter. Pass a string array by reference"));
   }

   // clears data in sa and copies the variant data into sa
   sa.Attach(*vArray);

   // Check that array is 1 dimensional
   if (sa.GetDim() != 1)
   {
      AfxThrowOleDispatchException(1002,
         _T("Type Mismatch in Parameter. Pass a one-dimensional array"));
   }

   try
   {
      // Get array bounds.
      sa.GetLBound(1, &lLBound);
      sa.GetUBound(1, &lUBound);

      // Get a pointer to the elements of the array
      // and increments the lock count on the array
      sa.AccessData((LPVOID*)& pbstr);

      //get no. of elements in array
      cElements = lUBound - lLBound + 1;
      for (int i = 0; i < cElements; i++)
      {
         //output the elements of the array
         _stprintf_s(buf, 1024, _T("[%s]\n"), OLE2T(pbstr[i]));
         OutputDebugString(buf);
      }

      //decrement lock count
      sa.UnaccessData();
   }
   catch (COleException* pEx)
   {
      AfxThrowOleDispatchException(1003,
         _T("Unexpected Failure in FastSort method"));
      pEx->Delete();
   }
}

COleSafeArray::AllocData

Aloca memória para um array seguro.

void AllocData();

Observações

Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::AllocDescriptor

Aloca memória para o descritor de um array seguro.

void AllocDescriptor(DWORD dwDims);

Parâmetros

dwDims
Número de dimensões na matriz segura.

Observações

Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::Anexar

Dá controlo dos dados num array existente VARIANT ao COleSafeArray objeto.

void Attach(VARIANT& varSrc);

Parâmetros

varSrc
Um objeto VARIANT. O parâmetro varSrc deve ter o VT_ARRAY VARTYPE.

Observações

O tipo da fonte VARIANTestá definido para VT_EMPTY. Esta função limpa os dados atuais do array, se existirem.

Example

Veja o exemplo de COleSafeArray::AccessData.

ColeSafeArray::Limpar

Limpa a matriz segura.

void Clear();

Observações

A função limpa um array seguro ao definir o VARTYPE do objeto para VT_EMPTY. O conteúdo atual é libertado e o array é libertado.

COleSafeArray::COleSafeArray

Constrói um COleSafeArray objeto.

COleSafeArray();

COleSafeArray(
    const SAFEARRAY& saSrc,
    VARTYPE vtSrc);

COleSafeArray(
    LPCSAFEARRAY pSrc,
    VARTYPE vtSrc);

COleSafeArray(const COleSafeArray& saSrc);
COleSafeArray(const VARIANT& varSrc);
COleSafeArray(LPCVARIANT pSrc);
COleSafeArray(const COleVariant& varSrc);

Parâmetros

saSrc
Um objeto existente COleSafeArray ou SAFEARRAY a ser copiado para o novo COleSafeArray objeto.

vtSrc
O VARTYPE do novo COleSafeArray objeto.

psaSrc
Um apontador para um SAFEARRAY a ser copiado para o novo COleSafeArray objeto.

varSrc
Um existente VARIANT ou COleVariant objeto a ser copiado para o novo COleSafeArray objeto.

pSrc
Um apontador para um VARIANT objeto a ser copiado para o novo COleSafeArray objeto.

Observações

Todos estes construtores criam novos COleSafeArray objetos. Se não houver parâmetro, é criado um objeto vazio COleSafeArray (VT_EMPTY). Se o COleSafeArray for copiado de outro array cujo VARTYPE é conhecido implicitamente (a COleSafeArray, COleVariant, ou VARIANT), o VARTYPE do array de origem é mantido e não precisa de ser especificado. Se o COleSafeArray for copiado de outro array cujo VARTYPE não é conhecido (SAFEARRAY), o VARTYPE deve ser especificado no parâmetro vtSrc .

Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::Copiado

Cria uma cópia de um array seguro existente.

void Copy(LPSAFEARRAY* ppsa);

Parâmetros

PPSA
Apontar para um local onde deves devolver o novo descritor do array.

Observações

Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::Create

Aloca e inicializa os dados para o array.

void Create(
    VARTYPE vtSrc,
    DWORD dwDims,
    DWORD* rgElements);

void Create(
    VARTYPE vtSrc,
    DWORD dwDims,
    SAFEARRAYBOUND* rgsabounds);

Parâmetros

vtSrc
O tipo base do array (isto é, o VARTYPE de cada elemento do array). O VARTYPE é restrito a um subconjunto dos tipos variantes. Nem a bandeira VT_ARRAY nem a VT_BYREF podem ser definidas. VT_EMPTY e VT_NULL não são tipos base válidos para o array. Todos os outros tipos são legais.

dwDims
Número de dimensões na matriz. Isto pode ser alterado depois de o array ser criado com o Redim.

rgElements
Apontar para um array do número de elementos para cada dimensão no array.

rgsabounds
Apontar para um vetor de limites (um para cada dimensão) para alocar para o array.

Observações

Esta função irá limpar os dados atuais do array, se necessário. Em caso de erro, a função lança uma CMemoryException.

Example

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

ASSERT(saMatrix.GetDim() == 2);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 2} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 2
saVector.Create(VT_I1, 1, rgsabounds);

ASSERT(saVector.GetDim() == 1);

COleSafeArray::CreateOneDim

Cria um novo objeto unidimensional COleSafeArray .

void CreateOneDim(
    VARTYPE vtSrc,
    DWORD dwElements,
    const void* pvSrcData = NULL,
    long nLBound = 0);

Parâmetros

vtSrc
O tipo base do array (isto é, o VARTYPE de cada elemento do array).

dwElements
Número de elementos no array. Isto pode ser alterado depois de o array ser criado com o ResizeOneDim.

pvSrcData
Aponta para os dados para copiar para o array.

nLBound
O limite inferior da matriz.

Observações

A função aloca e inicializa os dados do array, copiando os dados especificados se o ponteiro pvSrcData não for NULL.

Em caso de erro, a função lança uma CMemoryException.

Example

VARIANT varColInfo[3];

//initialize VARIANTs
for (int i = 0; i < 3; i++)
   VariantInit(&varColInfo[i]);

// Column Name
varColInfo[0].vt = VT_BSTR;
varColInfo[0].bstrVal = ::SysAllocString(L"Name");

// Column Type
varColInfo[1].vt = VT_UI4;
varColInfo[1].lVal = 1;

COleSafeArray sa;
//create a 1 dimensional safearray of VARIANTs
//& initialize it with varColInfo VARIANT array
sa.CreateOneDim(VT_VARIANT, 2, varColInfo);

//check that the dimension is 2
ASSERT(sa.GetOneDimSize() == 2);

//increase safearray size by 1
sa.ResizeOneDim(3);

// populate the last element of the safearray, (Column Size)
varColInfo[2].vt = VT_I4;
varColInfo[2].lVal = 30;
long el = 2;
sa.PutElement(&el, &varColInfo[2]);

COleSafeArray::D estroy

Destrói um descritor de array existente e todos os dados do array.

void Destroy();

Observações

Se os objetos estiverem armazenados no array, cada objeto é libertado. Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::D estroyData

Destrói todos os dados num array seguro.

void DestroyData();

Observações

Se os objetos estiverem armazenados no array, cada objeto é libertado. Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::D estroyDescriptor

Destrói um termo de matriz segura.

void DestroyDescriptor();

Observações

Em caso de erro, a função lança uma CMemoryException ou COleException.

COleSafeArray::D etach

Desliga os VARIANT dados do COleSafeArray objeto.

VARIANT Detach();

Valor de retorno

O valor subjacente VARIANT no COleSafeArray objeto.

Observações

A função desanexa os dados num array seguro definindo o VARTYPE do objeto para VT_EMPTY. É responsabilidade do chamador libertar o array chamando a função do Windows como VariantClear.

Em caso de erro, a função lança uma COleException.

Example

Veja o exemplo de COleSafeArray::P utElement.

COleSafeArray::GetByteArray

Copia o conteúdo do array seguro para um CByteArrayarquivo .

void GetByteArray(CByteArray& bytes);

Parâmetros

bytes
Uma referência a um objeto CByteArray .

COleSafeArray::GetDim

Devolve o número de dimensões no COleSafeArray objeto.

DWORD GetDim();

Valor de retorno

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

Example

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

ASSERT(saMatrix.GetDim() == 2);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 2} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 2
saVector.Create(VT_I1, 1, rgsabounds);

ASSERT(saVector.GetDim() == 1);

COleSafeArray::GetElement

Recupera um único elemento do array seguro.

void GetElement(
    long* rgIndices,
    void* pvData);

Parâmetros

rgÍndices
Apontar para um array de índices para cada dimensão do array.

pvData
Aponta para o local onde se coloca o elemento do array.

Observações

Esta função chama automaticamente as funções SafeArrayLock do Windows e SafeArrayUnlock antes e depois de recuperar o elemento. Se o elemento de dados for uma cadeia, objeto ou variante, a função copia o elemento da forma correta. O parâmetro pvData deve apontar para um buffer suficientemente grande para conter o elemento.

Em caso de erro, a função lança uma CMemoryException ou COleException.

Example

//sa is of type COleSafeArray with 2 dimensions

//Determine upper bounds for both dimensions
long lNumRows;
long lNumCols;
sa.GetUBound(1, &lNumRows);
sa.GetUBound(2, &lNumCols);

//Display the elements in the SAFEARRAY.
long index[2];
VARIANT val;

//Determine lower bounds for both dimensions
long lowRow, lowCol;
sa.GetLBound(1, &lowRow);
sa.GetLBound(2, &lowCol);

for (long r = lowRow; r <= lNumRows; r++)
{
   for (long c = lowCol; c <= lNumCols; c++)
   {
      index[0] = r;
      index[1] = c;

      //retrieve each element of the safearray
      sa.GetElement(index, &val);

      switch (val.vt)
      {
      case VT_R8:
         TRACE(_T("%1.2f\n"), val.dblVal);
         break;

      case VT_BSTR:
         TRACE(_T("%s\n"), (CString)val.bstrVal);
         break;

         // other cases omitted

      case VT_EMPTY:
         TRACE(_T("<empty>\n"));
         break;
      }
   }
}

COleSafeArray::GetElemSize

Recupera o tamanho de um elemento num COleSafeArray objeto.

DWORD GetElemSize();

Valor de retorno

O tamanho, em bytes, dos elementos de um array seguro.

COleSafeArray::GetLBound

Devolve o limite inferior para qualquer dimensão de um COleSafeArray objeto.

void GetLBound(
    DWORD dwDim,
    long* pLBound);

Parâmetros

dwDim
A dimensão do array para a qual se obtém o limite inferior.

pLBound
Aponta para a localização para devolver o limite inferior.

Observações

Em caso de erro, a função lança uma COleException.

Example

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

long lLBound;

//get lower bound for 1st dimension
saMatrix.GetLBound(1, &lLBound);

ASSERT(lLBound == 0);

//get lower for 2nd dimension
saMatrix.GetLBound(2, &lLBound);

ASSERT(lLBound == 0);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 1} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 1
saVector.Create(VT_I1, 1, rgsabounds);

//get lower bound for 1st dimension
saVector.GetLBound(1, &lLBound);

ASSERT(lLBound == 1);

COleSafeArray::GetOneDimSize

Devolve o número de elementos no objeto unidimensional COleSafeArray .

DWORD GetOneDimSize();

Valor de retorno

O número de elementos na matriz segura unidimensional.

Example

Veja o exemplo de COleSafeArray::CreateOneDim.

COleSafeArray::GetUBound

Devolve o limite superior para qualquer dimensão de um array seguro.

void GetUBound(
    DWORD dwDim,
    long* pUBound);

Parâmetros

dwDim
A dimensão do array para a qual se obtém o limite superior.

pUBound
Aponta para a localização para devolver o limite superior.

Observações

Em caso de erro, a função lança uma COleException.

Example

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

long lUBound;
ASSERT(saMatrix.GetDim() == 2);

//get upper bound for 1st dimension
saMatrix.GetUBound(1, &lUBound);

ASSERT(lUBound == 9);

//get upper bound for 2nd dimension
saMatrix.GetUBound(2, &lUBound);

ASSERT(lUBound == 4);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 1} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 1
saVector.Create(VT_I1, 1, rgsabounds);

//get upper bound for 1st dimension
saVector.GetUBound(1, &lUBound);

ASSERT(lUBound == 5);

ColeSafeArray::Trancar

Incrementa a contagem de bloqueios de um array e coloca um ponteiro para os dados do array no descritor do array.

void Lock();

Observações

Em caso de erro, gera uma ColeException.

O ponteiro no descritor do array é válido até Unlock ser chamado. Chamadas para Lock podem ser aninhadas; é necessário um número igual de chamadas para Unlock .

Um array não pode ser eliminado enquanto está bloqueado.

COleSafeArray::operator LPCVARIANT

Chame este operador de casting para aceder à estrutura subjacente VARIANT deste COleSafeArray objeto.

operator LPCVARIANT() const;

COleSafeArray::operator LPVARIANT

Chame este operador de casting para aceder à estrutura subjacente VARIANT deste COleSafeArray objeto.

operator LPVARIANT();

Observações

Note que alterar o valor na VARIANT estrutura acedido pelo ponteiro devolvido por esta função alterará o valor deste COleSafeArray objeto.

COleSafeArray::operator =

Estes operadores de atribuição sobrecarregados copiam o valor fonte para este COleSafeArray objeto.

COleSafeArray& operator=(const COleSafeArray& saSrc);
COleSafeArray& operator=(const VARIANT& varSrc);
COleSafeArray& operator=(LPCVARIANT pSrc);
COleSafeArray& operator=(const COleVariant& varSrc);

Observações

Segue-se uma breve descrição de cada operador:

• operador =(saSrc) Copia um objeto existente COleSafeArray para esse objeto.

• operador =(varSrc) Copia um array existente VARIANTCOleVariant para este objeto.

• operador =(pSrc) Copia o VARIANT objeto array acedido por pSrc para este objeto.

COleSafeArray::operator ==

Este operador compara dois arrays (SAFEARRAY, VARIANT, COleVariant, ou COleSafeArray arrays) e retorna não nulo se forem iguais; caso contrário, 0.

BOOL operator==(const SAFEARRAY& saSrc) const;
BOOL operator==(LPCSAFEARRAY pSrc) const;

BOOL operator==(const COleSafeArray& saSrc) const;
BOOL operator==(const VARIANT& varSrc) const;

BOOL operator==(LPCVARIANT pSrc) const;
BOOL operator==(const COleVariant& varSrc) const;

Observações

Dois arrays são iguais se tiverem um número igual de dimensões, tamanho igual em cada dimensão e valores iguais dos elementos.

COleSafeArray::operator <<

O COleSafeArray operador de inserção (<<) suporta o despejo diagnóstico e o armazenamento de um COleSafeArray objeto num arquivo.

CDumpContext& AFXAPI operator<<(
    CDumpContext& dc,
    COleSafeArray& saSrc);

COleSafeArray::P trOfIndex

Devolve um ponteiro para o elemento especificado pelos valores do índice.

void PtrOfIndex(
    long* rgIndices,
    void** ppvData);

Parâmetros

rgÍndices
Um array de valores de índice que identifica um elemento do array. Todos os índices para o elemento devem ser especificados.

ppvData
Ao retornar, aponta para o elemento identificado pelos valores em rgIndices.

COleSafeArray::P utElement

Atribui um único elemento ao array.

void PutElement(
    long* rgIndices,
    void* pvData);

Parâmetros

rgÍndices
Apontar para um array de índices para cada dimensão do array.

pvData
Aponta para os dados a atribuir ao array. VT_DISPATCH, VT_UNKNOWN e VT_BSTR tipos variantes são ponteiros e não requerem outro nível de indireção.

Observações

Esta função chama automaticamente as funções do Windows SafeArrayLock e SafeArrayUnlock antes e depois de atribuir o elemento. Se o elemento de dados for uma cadeia, objeto ou variante, a função copia-o corretamente, e se o elemento existente for uma cadeia, objeto ou variante, é limpo corretamente.

Note que pode ter múltiplos bloqueios num array, por isso pode colocar elementos num array enquanto o array está bloqueado por outras operações.

Em caso de erro, a função lança uma CMemoryException ou COleException.

Example

VARIANT retVariantArray()
{
   COleSafeArray saRet;
   DWORD numElements[] = { 10, 10 }; // 10x10

   // Create the 2 dimensional safe-array of type VT_R8 with size 10x10
   saRet.Create(VT_R8, 2, numElements);

   // Initialize safearray  with values...
   long index[2];
   for (index[0] = 0; index[0] < 10; index[0]++)
   {
      for (index[1] = 0; index[1] < 10; index[1]++)
      {
         double val = index[0] + index[1] * 10;
         //populate the safearray elements with double values
         saRet.PutElement(index, &val);
      }
   }
   // Return the safe-array encapsulated in a VARIANT...
   return saRet.Detach();
}

COleSafeArray::Redim

Altera o limite menos significativo (mais à direita) de um array seguro.

void Redim(SAFEARRAYBOUND* psaboundNew);

Parâmetros

psaboundNew
Apontar para uma nova estrutura segura de limites de array contendo o novo limite de array. Apenas a dimensão menos significativa de um array pode ser alterada.

Observações

Em caso de erro, a função lança uma COleException.

COleSafeArray::ResizeOneDim

Altera o número de elementos num objeto unidimensional COleSafeArray .

void ResizeOneDim(DWORD dwElements);

Parâmetros

dwElements
Número de elementos na matriz segura unidimensional.

Observações

Em caso de erro, a função lança uma COleException.

Example

Veja o exemplo de COleSafeArray::CreateOneDim.

COleSafeArray::UnaccessData

Diminui a contagem de bloqueios de um array e invalida o ponteiro recuperado por AccessData.

void UnaccessData();

Observações

Em caso de erro, a função lança uma COleException.

Example

Veja o exemplo de COleSafeArray::AccessData.

COleSafeArray::Desbloquear

Diminui o número de bloqueios de um array para que possa ser libertado ou redimensionado.

void Unlock();

Observações

Esta função é chamada após o acesso aos dados de um array estar concluído. Em caso de erro, gera uma ColeException.

Consulte também

Gráfico de Hierarquia
Classe COleVariant
Classe CRecordset
Classe CDatabase