CComSafeArray Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CComSafeArray Class on docs.microsoft.com. 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.

Public Constructors

NameDescription
CComSafeArray::CComSafeArrayThe constructor.
CComSafeArray::~CComSafeArrayThe destructor.

Public Methods

NameDescription
CComSafeArray::AddAdds one or more elements, or a SAFEARRAY structure, to a CComSafeArray.
CComSafeArray::AttachAttaches a SAFEARRAY structure to a CComSafeArray object.
CComSafeArray::CopyFromCopies the contents of a SAFEARRAY structure into the CComSafeArray object.
CComSafeArray::CopyToCreates a copy of the CComSafeArray object.
CComSafeArray::CreateCreates a CComSafeArray object.
CComSafeArray::DestroyDestroys a CComSafeArray object.
CComSafeArray::DetachDetaches a SAFEARRAY from a CComSafeArray object.
CComSafeArray::GetAtRetrieves a single element from a single-dimensional array.
CComSafeArray::GetCountReturns the number of elements in the array.
CComSafeArray::GetDimensionsReturns the number of dimensions in the array.
CComSafeArray::GetLowerBoundReturns the lower bound for a given dimension of the array.
CComSafeArray::GetSafeArrayPtrReturns the address of the m_psa data member.
CComSafeArray::GetTypeReturns the type of data stored in the array.
CComSafeArray::GetUpperBoundReturns the upper bound for any dimension of the array.
CComSafeArray::IsSizableTests if a CComSafeArray object can be resized.
CComSafeArray::MultiDimGetAtRetrieves a single element from a multidimensional array.
CComSafeArray::MultiDimSetAtSets the value of an element in a multidimensional array.
CComSafeArray::ResizeResizes a CComSafeArray object.
CComSafeArray::SetAtSets the value of an element in a single-dimensional array.

Public Operators

NameDescription
CComSafeArray::operator LPSAFEARRAYCasts a value to a SAFEARRAY pointer.
CComSafeArray::operatorRetrieves an element from the array.
CComSafeArray::operator =Assignment operator.

Public Data Members

NameDescription
CComSafeArray::m_psaThis data member holds the address of the SAFEARRAY structure.

CComSafeArray provides a wrapper for the SAFEARRAY Data Type 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:

VARTYPEDescription
VT_I1char
VT_I2short
VT_I4int
VT_I4long
VT_I8longlong
VT_UI1byte
VT_UI2ushort
VT_UI4uint
VT_UI4ulong
VT_UI8ulonglong
VT_R4float
VT_R8double
VT_DECIMALdecimal pointer
VT_VARIANTvariant pointer
VT_CYCurrency data type

Header: atlsafe.h

   // 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]);
      }   
   }

Adds one or more elements, or a SAFEARRAY structure, to 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);

Parameters

psaSrc
A pointer to a SAFEARRAY object.

ulCount
The number of objects to add to the array.

pT
A pointer to one or more objects to be added to the array.

t
A reference to the object to be added to the array.

bCopy
Indicates whether a copy of the data should be created. The default value is TRUE.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The new objects are appended to the end of the existing SAFEARRAY object. Adding an object to a multidimensional SAFEARRAY object is not supported. When adding an existing array of objects, both arrays must contain elements of the same type.

The bCopy flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array.

Attaches a SAFEARRAY structure to a CComSafeArray object.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parameters

psaSrc
A pointer to the SAFEARRAY structure.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Attaches a SAFEARRAY structure to a CComSafeArray object, making the existing CComSafeArray methods available.

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

Parameters

bound
A SAFEARRAYBOUND structure.

ulCount
The number of elements in the array.

lLBound
The lower bound value; that is, the index of the first element in the array.

pBound
A pointer to a SAFEARRAYBOUND structure.

uDims
The count of dimensions in the array.

saSrc
A reference to a SAFEARRAY structure or CComSafeArray object. In either case the constructor uses this reference to make a copy of the array, so the array is not referenced after construction.

psaSrc
A pointer to a SAFEARRAY structure. The constructor uses this address to make a copy of the array, so the array is not referenced after construction.

Remarks

Creates a CComSafeArray object.

The destructor.

~CComSafeArray() throw()

Remarks

Frees all allocated resources.

Copies the contents of a SAFEARRAY structure into the CComSafeArray object.

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parameters

ppArray
Pointer to the SAFEARRAY to copy.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This method copies the contents of a SAFEARRAY into the current CComSafeArray object. The existing contents of the array are replaced.

Creates a copy of the CComSafeArray object.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parameters

ppArray
A pointer to a location in which to create the new SAFEARRAY.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This method copies the contents of a CComSafeArray object into a SAFEARRAY structure.

Creates a CComSafeArray.

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

Parameters

pBound
A pointer to a SAFEARRAYBOUND object.

uDims
The number of dimensions in the array.

ulCount
The number of elements in the array.

lLBound
The lower bound value; that is, the index of the first element in the array.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

A CComSafeArray object can be created from an existing SAFEARRAYBOUND structure and the number of dimensions, or by specifying the number of elements in the array and the lower bound. If the array is to be accessed from Visual C++, the lower bound should be 0. Other languages may allow other values for the lower bound (for example, Visual Basic supports arrays with elements with a range such as -10 to 10).

Destroys a CComSafeArray object.

HRESULT Destroy();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Destroys an existing CComSafeArray object and all of the data it contains.

Detaches a SAFEARRAY from a CComSafeArray object.

LPSAFEARRAY Detach();

Return Value

Returns a pointer to a SAFEARRAY object.

Remarks

This method detaches the SAFEARRAY object from the CComSafeArray object.

Retrieves a single element from a single-dimensional array.

T& GetAt(LONG lIndex) const;

Parameters

lIndex
The index number of the value in the array to return.

Return Value

Returns a reference to the required array element.

Returns the number of elements in the array.

ULONG GetCount(UINT uDim = 0) const;

Parameters

uDim
The array dimension.

Return Value

Returns the number of elements in the array.

Remarks

When used with a multidimensional array, this method will return the number of elements in a specific dimension only.

Returns the number of dimensions in the array.

UINT GetDimensions() const;

Return Value

Returns the number of dimensions in the array.

Returns the lower bound for a given dimension of the array.

LONG GetLowerBound(UINT uDim = 0) const;

Parameters

uDim
The array dimension for which to get the lower bound. If omitted, the default is 0.

Return Value

Returns the lower bound.

Remarks

If the lower bound is 0, this indicates a C-like array whose first element is element number 0. In the event of an error, for example, an invalid dimension argument, this method calls AtlThrow with an HRESULT describing the error.

Returns the address of the m_psa data member.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Return Value

Returns a pointer to the CComSafeArray::m_psa data member.

Returns the type of data stored in the array.

VARTYPE GetType() const;

Return Value

Returns the type of data stored in the array, which could be any of the following types:

VARTYPEDescription
VT_I1char
VT_I2short
VT_I4int
VT_I4long
VT_I8longlong
VT_UI1byte
VT_UI2ushort
VT_UI4uint
VT_UI4ulong
VT_UI8ulonglong
VT_R4float
VT_R8double
VT_DECIMALdecimal pointer
VT_VARIANTvariant pointer
VT_CYCurrency data type

Returns the upper bound for any dimension of the array.

LONG GetUpperBound(UINT uDim = 0) const;

Parameters

uDim
The array dimension for which to get the upper bound. If omitted, the default is 0.

Return Value

Returns the upper bound. This value is inclusive, the maximum valid index for this dimension.

Remarks

In the event of an error, for example, an invalid dimension argument, this method calls AtlThrow with an HRESULT describing the error.

Tests if a CComSafeArray object can be resized.

bool IsSizable() const;

Return Value

Returns true if the CComSafeArray can be resized, false if it cannot.

Holds the address of the SAFEARRAY structure accessed.

LPSAFEARRAY m_psa;

Retrieves a single element from a multidimensional array.

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

Parameters

alIndex
Pointer to a vector of indexes for each dimension in the array. The leftmost (most significant) dimension is alIndex[0] .

t
A reference to the data returned.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Sets the value of an element in a multidimensional array.

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

Parameters

alIndex
Pointer to a vector of indexes for each dimension in the array. The rightmost (least significant) dimension is alIndex[0].

T
Specifies the value of the new element.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This is a multidimensional version of CComSafeArray::SetAt.

Retrieves an element from the array.

T& operator[](LONG   lIndex) const;

    T& operator[](int   nIndex) const;

Parameters

lIndex, nIndex
The index number of the required element in the array.

Return Value

Returns the appropriate array element.

Remarks

Performs a similar function to CComSafeArray::GetAt, however this operator only works with single-dimensional arrays.

Assignment operator.

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

Parameters

saSrc
A reference to a CComSafeArray object.

psaSrc
A pointer to a SAFEARRAY object.

Return Value

Returns the type of data stored in the array.

Casts a value to a SAFEARRAY pointer.

operator LPSAFEARRAY() const;

Return Value

Casts a value to a SAFEARRAY pointer.

Resizes a CComSafeArray object.

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

Parameters

pBound
A pointer to a SAFEARRAYBOUND structure that contains information on the number of elements and the lower bound of an array.

ulCount
The requested number of objects in the resized array.

lLBound
The lower bound.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This method only resizes the rightmost dimension. It will not resize arrays that return IsResizable as false.

Sets the value of an element in a single-dimensional array.

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

Parameters

lIndex
The index number of the array element to set.

t
The new value of the specified element.

bCopy
Indicates whether a copy of the data should be created. The default value is TRUE.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The bCopy flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array.

SAFEARRAY Data Type
CComSafeArray::Create
CComSafeArray::Destroy
Class Overview

Show: