CComSafeArray Class
This class is a wrapper for the SAFEARRAY structure.
template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray
T
The type of data to be stored in the array.
| Name | Description |
|---|---|
CComSafeArray::CComSafeArray |
The constructor. |
CComSafeArray::~CComSafeArray |
The destructor. |
| 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. |
| Name | Description |
|---|---|
CComSafeArray::operator LPSAFEARRAY |
Casts a value to a SAFEARRAY pointer. |
CComSafeArray::operator[] |
Retrieves an element from the array. |
CComSafeArray::operator = |
Assignment operator. |
| Name | Description |
|---|---|
CComSafeArray::m_psa |
This 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 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 |
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(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]);
}
}
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);
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.
Returns S_OK on success, or an error HRESULT on failure.
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.
Attaches a SAFEARRAY structure to a CComSafeArray object.
HRESULT Attach(const SAFEARRAY* psaSrc);
psaSrc
A pointer to the SAFEARRAY structure.
Returns S_OK on success, or an error HRESULT on failure.
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);
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.
Creates a CComSafeArray object.
The destructor.
~CComSafeArray() throw()
Frees all allocated resources.
Copies the contents of a SAFEARRAY structure into the CComSafeArray object.
HRESULT CopyFrom(LPSAFEARRAY* ppArray);
ppArray
Pointer to the SAFEARRAY to copy.
Returns S_OK on success, or an error HRESULT on failure.
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);
ppArray
A pointer to a location in which to create the new SAFEARRAY.
Returns S_OK on success, or an error HRESULT on failure.
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);
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.
Returns S_OK on success, or an error HRESULT on failure.
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).
Destroys a CComSafeArray object.
HRESULT Destroy();
Returns S_OK on success, or an error HRESULT on failure.
Destroys an existing CComSafeArray object and all of the data it contains.
Detaches a SAFEARRAY from a CComSafeArray object.
LPSAFEARRAY Detach();
Returns a pointer to a SAFEARRAY object.
This method detaches the SAFEARRAY object from the CComSafeArray object.
Retrieves a single element from a single-dimensional array.
T& GetAt(LONG lIndex) const;
lIndex
The index number of the value in the array to return.
Returns a reference to the required array element.
Returns the number of elements in the array.
ULONG GetCount(UINT uDim = 0) const;
uDim
The array dimension.
Returns the number of elements in the array.
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;
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;
uDim
The array dimension for which to get the lower bound. If omitted, the default is 0.
Returns the lower bound.
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();
Returns a pointer to the CComSafeArray::m_psa data member.
Returns the type of data stored in the array.
VARTYPE GetType() const;
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 |
Returns the upper bound for any dimension of the array.
LONG GetUpperBound(UINT uDim = 0) const;
uDim
The array dimension for which to get the upper bound. If omitted, the default is 0.
Returns the upper bound. This value is inclusive, the maximum valid index for this dimension.
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;
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);
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.
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);
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.
Returns S_OK on success, or an error HRESULT on failure.
This is a multidimensional version of CComSafeArray::SetAt.
Retrieves an element from the array.
T& operator[](long lindex) const;
T& operator[](int nindex) const;
lIndex, nIndex
The index number of the required element in the array.
Returns the appropriate array element.
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);
saSrc
A reference to a CComSafeArray object.
psaSrc
A pointer to a SAFEARRAY object.
Returns the type of data stored in the array.
Casts a value to a SAFEARRAY pointer.
operator LPSAFEARRAY() const;
Casts a value to a SAFEARRAY pointer.
Resizes a CComSafeArray object.
HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);
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.
Returns S_OK on success, or an error HRESULT on failure.
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);
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.
Returns S_OK on success, or an error HRESULT on failure.
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