Edit

Share via

CComSafeArray Class

  • Article

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 supported VARIANT 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(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

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 isn't 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 isn't 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 never 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 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