CComSafeArray Class

Article
01/08/2013

This class is a wrapper for the SAFEARRAY structure.

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

Parameters

T
The type of data to be stored in the array.

Members

Public Constructors

Name	Description
CComSafeArray::CComSafeArray	The constructor.
CComSafeArray::~CComSafeArray	The destructor.

Public Methods

Name	Description
CComSafeArray::Add	Adds one or more elements, or a SAFEARRAY structure, to a CComSafeArray.
CComSafeArray::Attach	Attaches a SAFEARRAY structure to a CComSafeArray object.
CComSafeArray::CopyFrom	Copies the contents of a SAFEARRAY structure into the CComSafeArray object.
CComSafeArray::CopyTo	Creates a copy of the CComSafeArray object.
CComSafeArray::Create	Creates a CComSafeArray object.
CComSafeArray::Destroy	Destroys a CComSafeArray object.
CComSafeArray::Detach	Detaches a SAFEARRAY from a CComSafeArray object.
CComSafeArray::GetAt	Retrieves a single element from a single-dimensional array.
CComSafeArray::GetCount	Returns the number of elements in the array.
CComSafeArray::GetDimensions	Returns the number of dimensions in the array.
CComSafeArray::GetLowerBound	Returns the lower bound for a given dimension of the array.
CComSafeArray::GetSafeArrayPtr	Returns the address of the m_psa data member.
CComSafeArray::GetType	Returns the type of data stored in the array.
CComSafeArray::GetUpperBound	Returns the upper bound for any dimension of the array.
CComSafeArray::IsSizable	Tests if a CComSafeArray object can be resized.
CComSafeArray::MultiDimGetAt	Retrieves a single element from a multidimensional array.
CComSafeArray::MultiDimSetAt	Sets the value of an element in a multidimensional array.
CComSafeArray::Resize	Resizes a CComSafeArray object.
CComSafeArray::SetAt	Sets the value of an element in a single-dimensional array.

Public Operators

Name	Description
CComSafeArray::operator LPSAFEARRAY	Casts a value to a SAFEARRAY pointer.
CComSafeArray::operator []	Retrieves an element from the array.
CComSafeArray::operator =	Assignment operator.

Public Data Members

Name	Description
CComSafeArray::m_psa	This data member holds the address of the SAFEARRAY structure.

Remarks

CComSafeArray provides a wrapper for the SAFEARRAY Data Type [Automation] class, making it a simple matter to create and manage single- and multidimensional arrays of almost any of the VARIANT-supported types.

CComSafeArray simplifies passing arrays between processes, and in addition provides extra security by checking array index values against upper and lower bounds.

The lower bound of a CComSafeArray can start at any user-defined value; however, arrays that are accessed through C++ should use a lower bound of 0. Other languages such as Visual Basic may use other bounding values (for example, -10 to 10).

Use CComSafeArray::Create to create a CComSafeArray object, and CComSafeArray::Destroy to delete it.

A CComSafeArray can contain the following subset of VARIANT data types:

VARTYPE	Description
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	decimal pointer
VT_VARIANT	variant pointer
VT_CY	Currency data type

Requirements

Header: 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(3);
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]);
   }   
}

Share via