CComSafeArray Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CComSafeArray Class.

This class is a wrapper for the SAFEARRAY structure.

Syntax

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

CComSafeArray::Add

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.

CComSafeArray::Attach

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.

CComSafeArray::CComSafeArray

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.

CComSafeArray::~CComSafeArray

The destructor.

~CComSafeArray
() throw
()

Remarks

Frees all allocated resources.

CComSafeArray::CopyFrom

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.

CComSafeArray::CopyTo

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.

CComSafeArray::Create

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).

CComSafeArray::Destroy

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.

CComSafeArray::Detach

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.

CComSafeArray::GetAt

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.

CComSafeArray::GetCount

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.

CComSafeArray::GetDimensions

Returns the number of dimensions in the array.

UINT GetDimensions() const;

Return Value

Returns the number of dimensions in the array.

CComSafeArray::GetLowerBound

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.

CComSafeArray::GetSafeArrayPtr

Returns the address of the m_psa data member.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Return Value

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

CComSafeArray::GetType

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:

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

CComSafeArray::GetUpperBound

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.

CComSafeArray::IsSizable

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.

CComSafeArray::m_psa

Holds the address of the SAFEARRAY structure accessed.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

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.

CComSafeArray::MultiDimSetAt

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.

CComSafeArray::operator []

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.

CComSafeArray::operator =

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.

CComSafeArray::operator LPSAFEARRAY

Casts a value to a SAFEARRAY pointer.

operator LPSAFEARRAY() const;

Return Value

Casts a value to a SAFEARRAY pointer.

CComSafeArray::Resize

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.

CComSafeArray::SetAt

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.

See Also

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