CComSafeArray クラス
このクラスは、SAFEARRAY 構造体用のラッパーです。
構文
template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray
パラメーター
T
配列に格納されるデータの型。
メンバー
パブリック コンストラクター
| 名前 | 説明 |
|---|---|
CComSafeArray::CComSafeArray |
コンストラクター。 |
CComSafeArray::~CComSafeArray |
デストラクター。 |
パブリック メソッド
| 名前 | 説明 |
|---|---|
CComSafeArray::Add |
1 つまたは複数の要素、あるいは 1 つの SAFEARRAY 構造体を CComSafeArray に追加します。 |
CComSafeArray::Attach |
SAFEARRAY 構造体を CComSafeArray オブジェクトにアタッチします。 |
CComSafeArray::CopyFrom |
SAFEARRAY 構造体のコンテンツを CComSafeArray オブジェクトにコピーします。 |
CComSafeArray::CopyTo |
CComSafeArray オブジェクトのコピーを作成します。 |
CComSafeArray::Create |
CComSafeArray オブジェクトを作成します。 |
CComSafeArray::Destroy |
CComSafeArray オブジェクトを破棄します。 |
CComSafeArray::Detach |
CComSafeArray オブジェクトから SAFEARRAY をデタッチします。 |
CComSafeArray::GetAt |
1 次元配列から 1 つの要素を取得します。 |
CComSafeArray::GetCount |
配列内の要素の数を返します。 |
CComSafeArray::GetDimensions |
配列内の次元数を返します。 |
CComSafeArray::GetLowerBound |
配列の指定した次元の下限を返します。 |
CComSafeArray::GetSafeArrayPtr |
m_psa データ メンバーのアドレスを返します。 |
CComSafeArray::GetType |
配列に格納されているデータの型を返します。 |
CComSafeArray::GetUpperBound |
配列の任意の次元の上限を返します。 |
CComSafeArray::IsSizable |
CComSafeArray オブジェクトのサイズを変更できるかどうかをテストします。 |
CComSafeArray::MultiDimGetAt |
多次元配列から 1 つの要素を取得します。 |
CComSafeArray::MultiDimSetAt |
多次元配列の要素の値を設定します。 |
CComSafeArray::Resize |
CComSafeArray オブジェクトのサイズを変更します。 |
CComSafeArray::SetAt |
1 次元配列の要素の値を設定します。 |
パブリック演算子
| 名前 | 説明 |
|---|---|
CComSafeArray::operator LPSAFEARRAY |
値を SAFEARRAY ポインターにキャストします。 |
CComSafeArray::operator[] |
配列から要素を取得します。 |
CComSafeArray::operator = |
代入演算子。 |
パブリック データ メンバー
| 名前 | 説明 |
|---|---|
CComSafeArray::m_psa |
このデータ メンバーで SAFEARRAY 構造体のアドレスが保持されます。 |
解説
CComSafeArray は、SAFEARRAY データ型クラスのラッパーを提供して、ほぼすべてのサポートされている VARIANT 型の 1 次元配列と多次元配列を簡単に作成および管理できるようにします。
CComSafeArray によりプロセス間での配列の受け渡しが単純化され、配列インデックスの値を上限と下限に照合することでセキュリティがさらに向上します。
CComSafeArray の下限は任意のユーザー定義値で開始できますが、C++ を通じてアクセスされる配列の下限は 0 にする必要があります。 Visual Basic などの他の言語では、別の境界値 (たとえば、-10 ～ 10) を使用できます。
CComSafeArray::Create を使用して CComSafeArray オブジェクトを作成し、CComSafeArray::Destroy を使用して削除します。
CComSafeArray には、VARIANT データ型の次のサブセットを格納できます。
VARTYPE |
説明 |
|---|---|
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 |
10 進ポインター |
VT_VARIANT |
バリアント ポインター |
VT_CY |
Currency データ型 |
要件
ヘッダー: 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]);
}
}
CComSafeArray::Add
1 つまたは複数の要素、あるいは 1 つの SAFEARRAY 構造体を 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
SAFEARRAY オブジェクトを指すポインターです。
ulCount
配列に追加するオブジェクトの数。
pT
配列に追加する 1 つまたは複数のオブジェクトへのポインター。
t
配列に追加するオブジェクトへの参照。
bCopy
データのコピーを作成する必要があるかどうかを示します。 既定値は TRUE です。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
新しいオブジェクトは、既存の SAFEARRAY オブジェクトの末尾に追加されます。 多次元 SAFEARRAY オブジェクトへのオブジェクトの追加はサポートされていません。 オブジェクトの既存の配列を追加する場合、両方の配列に同じ型の要素が含まれている必要があります。
bCopy フラグは、BSTR または VARIANT 型の要素が配列に追加されるときに考慮されます。 既定値の TRUE は、要素が配列に追加されるときにデータの新しいコピーが作成されることを保証します。
CComSafeArray::Attach
SAFEARRAY 構造体を CComSafeArray オブジェクトにアタッチします。
HRESULT Attach(const SAFEARRAY* psaSrc);
パラメーター
psaSrc
SAFEARRAY 構造体へのポインター。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
SAFEARRAY 構造体を CComSafeArray オブジェクトにアタッチし、既存の CComSafeArray メソッドを使用できるようにします。
CComSafeArray::CComSafeArray
コンストラクター。
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
SAFEARRAYBOUND 構造。
ulCount
配列内の 要素の数。
lLBound
下限値。つまり、配列内の最初の要素のインデックスです。
pBound
SAFEARRAYBOUND 構造体へのポインター。
uDims
配列内の次元の数。
saSrc
SAFEARRAY 構造体または CComSafeArray オブジェクトへの参照。 いずれの場合も、コンストラクターではこの参照を使用して配列のコピーを作成するため、配列は構築後に参照されません。
psaSrc
SAFEARRAY 構造体へのポインター。 コンストラクターではこのアドレスを使用して配列のコピーを作成するため、構築後に配列が参照されることはありません。
解説
CComSafeArray オブジェクトを作成します。
CComSafeArray::~CComSafeArray
デストラクター。
~CComSafeArray() throw()
解説
割り当てられているすべてのリソースを解放します。
CComSafeArray::CopyFrom
SAFEARRAY 構造体のコンテンツを CComSafeArray オブジェクトにコピーします。
HRESULT CopyFrom(LPSAFEARRAY* ppArray);
パラメーター
ppArray
コピーする SAFEARRAY へのポインター。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
このメソッドでは、SAFEARRAY のコンテンツを現在の CComSafeArray オブジェクトにコピーします。 配列の既存のコンテンツが置き換えられます。
CComSafeArray::CopyTo
CComSafeArray オブジェクトのコピーを作成します。
HRESULT CopyTo(LPSAFEARRAY* ppArray);
パラメーター
ppArray
新しい SAFEARRAY を作成する場所へのポインター。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
このメソッドでは、CComSafeArray オブジェクトのコンテンツを SAFEARRAY 構造体にコピーします。
CComSafeArray::Create
CComSafeArray を作成します。
HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0);
パラメーター
pBound
SAFEARRAYBOUND オブジェクトを指すポインターです。
uDims
配列内の次元の数。
ulCount
配列内の 要素の数。
lLBound
下限値。つまり、配列内の最初の要素のインデックスです。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
CComSafeArray オブジェクトは、既存の SAFEARRAYBOUND 構造体と次元の数から作成することも、配列内の要素の数と下限を指定することによって作成することもできます。 配列に C++ からアクセスする場合、下限は 0 にする必要があります。 他の言語では、下限に対して他の値が許可される場合があります (たとえば、Visual Basic では、-10 から 10 などの範囲の要素を持つ配列がサポートされます)。
CComSafeArray::Destroy
CComSafeArray オブジェクトを破棄します。
HRESULT Destroy();
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
既存の CComSafeArray オブジェクトとそれに含まれるすべてのデータを破棄します。
CComSafeArray::Detach
CComSafeArray オブジェクトから SAFEARRAY をデタッチします。
LPSAFEARRAY Detach();
戻り値
SAFEARRAY オブジェクトへのポインターを返します。
解説
このメソッドでは、SAFEARRAY オブジェクトを CComSafeArray オブジェクトからデタッチします。
CComSafeArray::GetAt
1 次元配列から 1 つの要素を取得します。
T& GetAt(LONG lIndex) const;
パラメーター
lIndex
返される配列内の値のインデックス番号。
戻り値
必須の配列要素への参照を返します。
CComSafeArray::GetCount
配列内の要素の数を返します。
ULONG GetCount(UINT uDim = 0) const;
パラメーター
uDim
配列の次元。
戻り値
配列内の要素の数を返します。
解説
多次元配列と共に使用される場合、このメソッドでは特定の次元の要素の数のみを返します。
CComSafeArray::GetDimensions
配列内の次元数を返します。
UINT GetDimensions() const;
戻り値
配列内の次元数を返します。
CComSafeArray::GetLowerBound
配列の指定した次元の下限を返します。
LONG GetLowerBound(UINT uDim = 0) const;
パラメーター
uDim
下限を取得する対象の配列の次元。 省略した場合、既定値は 0 となります。
戻り値
下限を返します。
解説
下限が 0 の場合、これは、最初の要素が要素番号 0 である C のような配列を示します。 たとえば、無効な次元引数などのエラーが発生した場合、このメソッドでは、そのエラーを説明する HRESULT を使用して AtlThrow を呼び出します。
CComSafeArray::GetSafeArrayPtr
m_psa データ メンバーのアドレスを返します。
LPSAFEARRAY* GetSafeArrayPtr() throw();
戻り値
CComSafeArray::m_psa データ メンバーを指すポインターを返します。
CComSafeArray::GetType
配列に格納されているデータの型を返します。
VARTYPE GetType() const;
戻り値
配列に格納されているデータの型を返します。これは次のいずれかの型になります。
VARTYPE |
説明 |
|---|---|
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 |
10 進ポインター |
VT_VARIANT |
バリアント ポインター |
VT_CY |
Currency データ型 |
CComSafeArray::GetUpperBound
配列の任意の次元の上限を返します。
LONG GetUpperBound(UINT uDim = 0) const;
パラメーター
uDim
上限を取得する対象の配列の次元。 省略した場合、既定値は 0 となります。
戻り値
上限を返します。 この値には、この次元の有効な最大インデックス数が含まれます。
解説
たとえば、無効な次元引数などのエラーが発生した場合、このメソッドでは、そのエラーを説明する HRESULT を使用して AtlThrow を呼び出します。
CComSafeArray::IsSizable
CComSafeArray オブジェクトのサイズを変更できるかどうかをテストします。
bool IsSizable() const;
戻り値
CComSafeArray のサイズを変更できる場合は TRUE、できない場合は FALSE を返します。
CComSafeArray::m_psa
アクセスされる SAFEARRAY 構造体のアドレスを保持します。
LPSAFEARRAY m_psa;
CComSafeArray::MultiDimGetAt
多次元配列から 1 つの要素を取得します。
HRESULT MultiDimGetAt(const LONG* alIndex, T& t);
パラメーター
alIndex
配列内の各次元のインデックスのベクトルへのポインター。 左端 (最上位) の次元は alIndex[0] です。
t
返されるデータへの参照。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
CComSafeArray::MultiDimSetAt
多次元配列の要素の値を設定します。
HRESULT MultiDimSetAt(const LONG* alIndex, const T& t);
パラメーター
alIndex
配列内の各次元のインデックスのベクトルへのポインター。 右端 (最下位) の次元は alIndex[0] です。
T
新しい要素の値を指定します。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
これは、CComSafeArray::SetAt の多次元バージョンです。
CComSafeArray::operator []
配列から要素を取得します。
T& operator[](long lindex) const;
T& operator[](int nindex) const;
パラメーター
lIndex, nIndex
配列内の必須要素のインデックス番号。
戻り値
適切な配列要素を返します。
解説
CComSafeArray::GetAt と同様の関数を実行しますが、この演算子は 1 次元配列でのみ機能します。
CComSafeArray::operator =
代入演算子。
ATL::CComSafeArray<T>& operator=(const ATL::CComSafeArray& saSrc);
ATL::CComSafeArray<T>& operator=(const SAFEARRAY* psaSrc);
パラメーター
saSrc
CComSafeArray オブジェクトへの参照です。
psaSrc
SAFEARRAY オブジェクトを指すポインターです。
戻り値
配列に格納されているデータの型を返します。
CComSafeArray::operator LPSAFEARRAY
値を SAFEARRAY ポインターにキャストします。
operator LPSAFEARRAY() const;
戻り値
値を SAFEARRAY ポインターにキャストします。
CComSafeArray::Resize
CComSafeArray オブジェクトのサイズを変更します。
HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);
パラメーター
pBound
要素の数と配列の下限に関する情報を含む SAFEARRAYBOUND 構造体へのポインター。
ulCount
サイズ変更された配列内の要求されたオブジェクトの数。
lLBound
下限。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
このメソッドでは、右端の次元のサイズのみを変更します。 FALSE として IsResizable を返す配列のサイズは変更しません。
CComSafeArray::SetAt
1 次元配列の要素の値を設定します。
HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE);
パラメーター
lIndex
設定する配列要素のインデックス番号。
t
指定した要素の新しい値。
bCopy
データのコピーを作成する必要があるかどうかを示します。 既定値は TRUE です。
戻り値
成功した場合は S_OK を返し、失敗した場合はエラー HRESULT を返します。
解説
bCopy フラグは、BSTR または VARIANT 型の要素が配列に追加されるときに考慮されます。 既定値の TRUE は、要素が配列に追加されるときにデータの新しいコピーが作成されることを保証します。
関連項目
SAFEARRAY データ型
CComSafeArray::Create
CComSafeArray::Destroy
クラスの概要