Compartir a través de

Clase CComSafeArray

  • Artículo

Esta clase es un contenedor de la estructura SAFEARRAY.

Sintaxis

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

Parámetros

T
Tipo de datos que se va a almacenar en la matriz.

Miembros

Constructores públicos

Nombre Descripción
CComSafeArray::CComSafeArray Constructor .
CComSafeArray::~CComSafeArray El destructor .

Métodos públicos

Nombre Descripción
CComSafeArray::Add Agrega uno o varios elementos, o una estructura SAFEARRAY, a CComSafeArray.
CComSafeArray::Attach Asocia una estructura SAFEARRAY a un objeto CComSafeArray.
CComSafeArray::CopyFrom Copia el contenido de una estructura SAFEARRAYen el objeto CComSafeArray.
CComSafeArray::CopyTo Crea una copia del objeto CComSafeArray .
CComSafeArray::Create Crea un objeto CComSafeArray.
CComSafeArray::Destroy Destruye un objeto CComSafeArray .
CComSafeArray::Detach Desasocia SAFEARRAY de un objeto CComSafeArray.
CComSafeArray::GetAt Recupera un único elemento de una matriz unidimensional.
CComSafeArray::GetCount Devuelve el número de elementos de la matriz.
CComSafeArray::GetDimensions Devuelve el número de dimensiones de la matriz.
CComSafeArray::GetLowerBound Devuelve el límite inferior de una determinada dimensión de la matriz.
CComSafeArray::GetSafeArrayPtr Devuelve la dirección del miembro de datos m_psa .
CComSafeArray::GetType Devuelve el tipo de datos almacenado en la matriz.
CComSafeArray::GetUpperBound Devuelve el límite superior de cualquier dimensión de la matriz.
CComSafeArray::IsSizable Comprueba si se puede cambiar el tamaño de un objeto CComSafeArray .
CComSafeArray::MultiDimGetAt Recupera un único elemento de una matriz multidimensional.
CComSafeArray::MultiDimSetAt Establece el valor de un elemento de una matriz multidimensional.
CComSafeArray::Resize Cambia el tamaño de un objeto CComSafeArray .
CComSafeArray::SetAt Establece el valor de un elemento de una matriz unidimensional.

Operadores públicos

Nombre Descripción
CComSafeArray::operator LPSAFEARRAY Convierte un valor en un puntero SAFEARRAY.
CComSafeArray::operator[] Recupera un elemento de la matriz.
CComSafeArray::operator = Operador de asignación.

Miembros de datos públicos

Nombre Descripción
CComSafeArray::m_psa Este miembro de datos contiene la dirección de la estructura SAFEARRAY.

Comentarios

CComSafeArray proporciona un contenedor para la clase SAFEARRAYtipo de datos, lo que facilita la creación y administración de matrices unidimensionales y multidimensionales de casi cualquiera de los tipos VARIANT compatibles.

CComSafeArray simplifica el paso de matrices entre procesos y, además, proporciona seguridad adicional al comprobar los valores de índice de matriz con los limites superior e inferior.

El límite inferior de CComSafeArray puede empezar por cualquier valor definido por el usuario, pero las matrices a las que se accede a través de C++ usan un límite inferior de 0. Otros lenguajes como Visual Basic pueden usar otros valores límite (por ejemplo, de -10 a 10).

Use CComSafeArray::Create para crear un objeto CComSafeArray y CComSafeArray::Destroy para eliminarlo.

CComSafeArray puede contener el siguiente subconjunto de tipos de datos VARIANT:

VARTYPE Descripción
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 puntero decimal
VT_VARIANT puntero variant
VT_CY Currency (tipo de datos)

Requisitos

Encabezado: atlsafe.h

Ejemplo

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

Agrega uno o varios elementos, o una estructura SAFEARRAY, a 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
Puntero a un objeto SAFEARRAY .

ulCount
Número de objetos que se agregan a la matriz.

pT
Puntero a uno o varios objetos que se van a agregar a la matriz.

t
Referencia al objeto que se va a agregar a la matriz.

bCopy
Indica si se debe crear una copia de los datos. El valor predeterminado es TRUE.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Los nuevos objetos se anexan al final del objeto SAFEARRAY existente. No se admite la adición de un objeto a un objeto SAFEARRAY multidimensional. Al agregar una matriz existente de objetos, ambas matrices deben contener elementos del mismo tipo.

La marca bCopy se tiene en cuenta cuando se agregan elementos de tipo BSTR o VARIANT a una matriz. El valor predeterminado de TRUE garantiza que se realice una nueva copia de los datos cuando el elemento se agrega a la matriz.

CComSafeArray::Attach

Asocia una estructura SAFEARRAY a un objeto CComSafeArray.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parámetros

psaSrc
Un puntero a la estructura SAFEARRAY.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Asocia una estructura SAFEARRAY a un objeto CComSafeArray, lo que hace que los métodos CComSafeArray existentes estén disponibles.

CComSafeArray::CComSafeArray

Constructor .

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
Un estructura SAFEARRAYBOUND.

ulCount
Número de elementos de la matriz.

lLBound
Valor de límite inferior; es decir, el índice del primer elemento de la matriz.

pBound
Un puntero a una estructura SAFEARRAYBOUND.

uDims
Número de dimensiones de la matriz.

saSrc
Referencia a una estructura SAFEARRAY o a un objeto CComSafeArray. En cualquier caso, el constructor usa esta referencia para realizar una copia de la matriz, por lo que no se hace referencia a la matriz después de la construcción.

psaSrc
Un puntero a una estructura SAFEARRAY. El constructor usa esta dirección para realizar una copia de la matriz, por lo que nunca se hace referencia a la matriz después de la construcción.

Comentarios

Crea un objeto CComSafeArray.

CComSafeArray::~CComSafeArray

El destructor .

~CComSafeArray() throw()

Comentarios

Libera todos los recursos asignados.

CComSafeArray::CopyFrom

Copia el contenido de una estructura SAFEARRAYen el objeto CComSafeArray.

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parámetros

ppArray
Puntero al que SAFEARRAY se copia.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Este método copia el contenido de SAFEARRAY objeto en el objeto CComSafeArray actual. Se reemplaza el contenido existente de la matriz.

CComSafeArray::CopyTo

Crea una copia del objeto CComSafeArray .

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parámetros

ppArray
Puntero a una ubicación en la que se crea el elemento SAFEARRAY.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Este método copia el contenido de un objeto CComSafeArray en una estructura SAFEARRAY.

CComSafeArray::Create

Crea una interfaz CComSafeArray.

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

Parámetros

pBound
Puntero a un objeto SAFEARRAYBOUND .

uDims
Número de dimensiones de la matriz.

ulCount
Número de elementos de la matriz.

lLBound
Valor de límite inferior; es decir, el índice del primer elemento de la matriz.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Un objeto CComSafeArray se puede crear a partir de una estructura SAFEARRAYBOUND existente y el número de dimensiones, o bien especificando el número de elementos de la matriz y el límite inferior. Si se va a acceder a la matriz desde C++, el límite inferior debe ser 0. Otros lenguajes pueden permitir otros valores para el límite inferior (por ejemplo, Visual Basic admite matrices con elementos con un intervalo como -10 a 10).

CComSafeArray::Destroy

Destruye un objeto CComSafeArray .

HRESULT Destroy();

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Destruye un objeto CComSafeArray existente y todos los datos que contiene.

CComSafeArray::Detach

Desasocia SAFEARRAY de un objeto CComSafeArray.

LPSAFEARRAY Detach();

Valor devuelto

Devuelve un puntero a un objeto SAFEARRAY.

Comentarios

Este método desasocia el objeto SAFEARRAY del objeto CComSafeArray.

CComSafeArray::GetAt

Recupera un único elemento de una matriz unidimensional.

T& GetAt(LONG lIndex) const;

Parámetros

lIndex
Número de índice del valor de la matriz que se devuelve.

Valor devuelto

Devuelve una referencia al prototipo para una matriz.

CComSafeArray::GetCount

Devuelve el número de elementos de la matriz.

ULONG GetCount(UINT uDim = 0) const;

Parámetros

uDim
Dimensión de la matriz.

Valor devuelto

Devuelve el número de elementos de la matriz.

Comentarios

Cuando se usa con una matriz multidimensional, este método devolverá solo el número de elementos de una dimensión específica.

CComSafeArray::GetDimensions

Devuelve el número de dimensiones de la matriz.

UINT GetDimensions() const;

Valor devuelto

Devuelve el número de dimensiones de la matriz.

CComSafeArray::GetLowerBound

Devuelve el límite inferior de una determinada dimensión de la matriz.

LONG GetLowerBound(UINT uDim = 0) const;

Parámetros

uDim
Dimensión de matriz para la que se va a obtener el límite inferior. Si se omite, el valor predeterminado es 0.

Valor devuelto

Devuelve el valor inferior.

Comentarios

Si el límite inferior es 0, indica una matriz similar a C cuyo primer elemento es el número de elemento 0. En el caso de un error, por ejemplo, un argumento de dimensión no válido, este método llama a AtlThrow y HRESULT describe el error.

CComSafeArray::GetSafeArrayPtr

Devuelve la dirección del miembro de datos m_psa .

LPSAFEARRAY* GetSafeArrayPtr() throw();

Valor devuelto

Devuelve un puntero al miembro de datos CComSafeArray::m_psa.

CComSafeArray::GetType

Devuelve el tipo de datos almacenado en la matriz.

VARTYPE GetType() const;

Valor devuelto

Devuelve el tipo de datos almacenados en la matriz, que puede ser cualquiera de los siguientes tipos:

VARTYPE Descripción
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 puntero decimal
VT_VARIANT puntero variant
VT_CY Currency (tipo de datos)

CComSafeArray::GetUpperBound

Devuelve el límite superior de cualquier dimensión de la matriz.

LONG GetUpperBound(UINT uDim = 0) const;

Parámetros

uDim
Dimensión de matriz para la que se va a obtener el límite superior. Si se omite, el valor predeterminado es 0.

Valor devuelto

Devuelve el límite superior. Este valor es inclusivo, el índice máximo válido para esta dimensión.

Comentarios

En el caso de un error, por ejemplo, un argumento de dimensión no válido, este método llama a AtlThrow y HRESULT describe el error.

CComSafeArray::IsSizable

Comprueba si se puede cambiar el tamaño de un objeto CComSafeArray .

bool IsSizable() const;

Valor devuelto

Devuelve TRUE si se puede cambiar el tamaño de CComSafeArray y FALSE si no se puede cambiar.

CComSafeArray::m_psa

Contiene la dirección de la estructura SAFEARRAY a la que se accede.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Recupera un único elemento de una matriz multidimensional.

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

Parámetros

alIndex
Puntero a un vector de índices para cada dimensión de la matriz. La dimensión más a la izquierda (la más significativa) es alIndex[0].

t
Referencia a los datos devueltos.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

CComSafeArray::MultiDimSetAt

Establece el valor de un elemento de una matriz multidimensional.

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

Parámetros

alIndex
Puntero a un vector de índices para cada dimensión de la matriz. La dimensión más a la derecha (la menos significativa) es alIndex[0].

T
Especifica el valor del elemento nuevo.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Se trata de una versión multidimensional de CComSafeArray::SetAt.

CComSafeArray::operator []

Recupera un elemento de la matriz.

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

Parámetros

lIndex, nIndex
Número de índice del elemento necesario en la matriz.

Valor devuelto

Devuelve el elemento de matriz adecuado.

Comentarios

Realiza una función similar a CComSafeArray::GetAt, pero este operador solo funciona con matrices unidimensionales.

CComSafeArray::operator =

Operador de asignación.

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

Parámetros

saSrc
Referencia a un objeto CComSafeArray.

psaSrc
Puntero a un objeto SAFEARRAY .

Valor devuelto

Devuelve el tipo de datos almacenado en la matriz.

CComSafeArray::operator LPSAFEARRAY

Convierte un valor en un puntero SAFEARRAY.

operator LPSAFEARRAY() const;

Valor devuelto

Convierte un valor en un puntero SAFEARRAY.

CComSafeArray::Resize

Cambia el tamaño de un objeto CComSafeArray .

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

Parámetros

pBound
Puntero a una estructura SAFEARRAYBOUND que contiene información sobre el número de elementos y el límite inferior de una matriz.

ulCount
Número solicitado de objetos en la matriz cuyo tamaño se haya cambiado.

lLBound
Límite inferior.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Este método solo cambia el tamaño de la dimensión situada más a la derecha. No cambiará el tamaño de las matrices que devuelven IsResizable como FALSE.

CComSafeArray::SetAt

Establece el valor de un elemento de una matriz unidimensional.

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

Parámetros

lIndex
Número de índice del elemento de matriz que se establece.

t
Nuevo valor del elemento especificado.

bCopy
Indica si se debe crear una copia de los datos. El valor predeterminado es TRUE.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

La marca bCopy se tiene en cuenta cuando se agregan elementos de tipo BSTR o VARIANT a una matriz. El valor predeterminado de TRUE garantiza que se realice una nueva copia de los datos cuando el elemento se agrega a la matriz.

Consulte también

SAFEARRAY Tipo de datos
CComSafeArray::Create
CComSafeArray::Destroy
Información general sobre la clase