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 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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for