CComSafeArray-Klasse

Diese Klasse ist ein Wrapper für die SAFEARRAY Struktur.

Syntax

template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray

Parameter

T
Der Typ der im Array gespeicherten Daten.

Member

Öffentliche Konstruktoren

Name	Beschreibung
CComSafeArray::CComSafeArray	Der Konstruktor.
CComSafeArray::~CComSafeArray	Der Destruktor.

Öffentliche Methoden

Name	Beschreibung
CComSafeArray::Add	Fügt ein oder mehrere Elemente oder eine SAFEARRAY Struktur zu einem CComSafeArray.
CComSafeArray::Attach	Fügt eine SAFEARRAY Struktur an ein CComSafeArray Objekt an.
CComSafeArray::CopyFrom	Kopiert den Inhalt einer SAFEARRAY Struktur in das CComSafeArray Objekt.
CComSafeArray::CopyTo	Erstellt eine Kopie des CComSafeArray-Objekts.
CComSafeArray::Create	Erstellt ein CComSafeArray-Objekt.
CComSafeArray::Destroy	Zerstört ein CComSafeArray -Objekt.
CComSafeArray::Detach	Trennt ein SAFEARRAY Objekt CComSafeArray .
CComSafeArray::GetAt	Ruft ein einzelnes Element aus einem eindimensionalen Array ab.
CComSafeArray::GetCount	Gibt die Anzahl der Elemente des Arrays zurück.
CComSafeArray::GetDimensions	Gibt die Anzahl der Dimensionen des Arrays zurück.
CComSafeArray::GetLowerBound	Gibt die untere Grenze für eine bestimmte Dimension des Arrays zurück.
CComSafeArray::GetSafeArrayPtr	Gibt die Adresse des m_psa -Datenelements zurück.
CComSafeArray::GetType	Gibt den Typ der im Array gespeicherten Daten zurück.
CComSafeArray::GetUpperBound	Gibt die obere Grenze für eine bestimmte Dimension des Arrays zurück.
CComSafeArray::IsSizable	Testet, ob die Größe eines CComSafeArray -Objekts geändert werden kann.
CComSafeArray::MultiDimGetAt	Ruft ein einzelnes Element aus einem mehrdimensionalen Array ab.
CComSafeArray::MultiDimSetAt	Legt den Wert eines Elements in einem mehrdimensionalen Array fest.
CComSafeArray::Resize	Ändert die Größe eines CComSafeArray -Objekts.
CComSafeArray::SetAt	Legt den Wert eines Elements in einem eindimensionalen Array fest.

Öffentliche Operatoren

Name	Beschreibung
CComSafeArray::operator LPSAFEARRAY	Wandelt einen Wert in einen SAFEARRAY Zeiger um.
CComSafeArray::operator[]	Ruft ein Element aus dem Array ab.
CComSafeArray::operator =	Zuweisungsoperator.

Öffentliche Datenmember

Name	Beschreibung
CComSafeArray::m_psa	Dieses Datenelement enthält die Adresse der SAFEARRAY Struktur.

Hinweise

CComSafeArray stellt einen Wrapper für die SAFEARRAY Datentypklasse bereit, wodurch es einfach ist, einzelne und multidimensionale Arrays von fast allen unterstützten VARIANT Typen zu erstellen und zu verwalten.

CComSafeArray vereinfacht die Übergabe von Arrays zwischen Prozessen und bietet darüber hinaus zusätzliche Sicherheit durch Überprüfen der Arrayindexwerte anhand der oberen und unteren Grenzen.

Die untere Grenze eines CComSafeArray kann bei einem beliebigen benutzerdefinierten Wert beginnen, Arrays, auf die über C++ zugegriffen wird, sollte jedoch eine Untergrenze von 0 verwenden. Andere Sprachen wie Visual Basic können andere Begrenzungswerte (z. B. -10 bis 10) verwenden.

Dient CComSafeArray::Create zum Erstellen eines CComSafeArray Objekts und CComSafeArray::Destroy zum Löschen.

A CComSafeArray kann die folgende Teilmenge von VARIANT Datentypen enthalten:

VARTYPE	Beschreibung
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	Dezimalzeiger
VT_VARIANT	Variant-Zeiger
VT_CY	Currency-Datentyp

Anforderungen

Header: atlsafe.h

Beispiel

// 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

Fügt ein oder mehrere Elemente oder eine SAFEARRAY Struktur zu einem CComSafeArray.

HRESULT Add(const SAFEARRAY* psaSrc);
HRESULT Add(ULONG ulCount, const T* pT, BOOL bCopy = TRUE);
HRESULT Add(const T& t, BOOL bCopy = TRUE);

Parameter

psaSrc
Ein Zeiger auf ein SAFEARRAY-Objekt.

ulCount
Die Anzahl der Objekte, die dem Array hinzugefügt werden sollen.

pT
Ein Zeiger auf ein oder mehrere Objekte, die dem Array hinzugefügt werden sollen.

t
Ein Verweis auf das Objekt, das dem Array hinzugefügt werden soll.

bCopy
Gibt an, ob eine Kopie der Daten erstellt werden soll. Der Standardwert ist TRUE.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Die neuen Objekte werden am Ende des vorhandenen SAFEARRAY Objekts angefügt. Das Hinzufügen eines Objekts zu einem multidimensionalen SAFEARRAY Objekt wird nicht unterstützt. Beim Hinzufügen eines vorhandenen Arrays von Objekten müssen beide Arrays Elemente desselben Typs enthalten.

Das bCopy Kennzeichen wird berücksichtigt, wenn Elemente vom Typ BSTR oder VARIANT einem Array hinzugefügt werden. Der Standardwert stellt TRUE sicher, dass eine neue Kopie aus den Daten erstellt wird, wenn das Element dem Array hinzugefügt wird.

CComSafeArray::Attach

Fügt eine SAFEARRAY Struktur an ein CComSafeArray Objekt an.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parameter

psaSrc
Ein Zeiger auf die SAFEARRAY Struktur.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Fügt eine SAFEARRAY Struktur an ein CComSafeArray Objekt an und stellt die vorhandenen CComSafeArray Methoden zur Verfügung.

CComSafeArray::CComSafeArray

Der Konstruktor.

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

Parameter

bound
Eine SAFEARRAYBOUND-Struktur.

ulCount
Die Anzahl der Elemente im Array.

lLBound
Der untere Begrenzungswert; d. h. der Index des ersten Elements im Array.

pBound
Ein Zeiger auf eine SAFEARRAYBOUND Struktur.

uDims
Die Anzahl der Dimensionen im Array.

saSrc
Ein Verweis auf eine Struktur oder CComSafeArray ein SAFEARRAY Objekt. In beiden Fällen verwendet der Konstruktor diesen Verweis, um eine Kopie des Arrays zu erstellen, sodass das Array nach der Konstruktion nicht referenziert wird.

psaSrc
Ein Zeiger auf eine SAFEARRAY Struktur. Der Konstruktor verwendet diese Adresse, um eine Kopie des Arrays zu erstellen, sodass nach der Konstruktion nie auf das Array verwiesen wird.

Hinweise

Erstellt ein CComSafeArray-Objekt.

CComSafeArray::~CComSafeArray

Der Destruktor.

~CComSafeArray() throw()

Hinweise

Gibt alle zugeordneten Ressourcen frei.

CComSafeArray::CopyFrom

Kopiert den Inhalt einer SAFEARRAY Struktur in das CComSafeArray Objekt.

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parameter

ppArray
Zeigen Sie auf den SAFEARRAY zu kopierenden Zeiger.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Mit dieser Methode wird der Inhalt eines SAFEARRAY Objekts in das aktuelle CComSafeArray Objekt kopiert. Der vorhandene Inhalt des Arrays wird ersetzt.

CComSafeArray::CopyTo

Erstellt eine Kopie des CComSafeArray-Objekts.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parameter

ppArray
Ein Zeiger auf eine Position, an der das neue SAFEARRAYerstellt werden soll.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Diese Methode kopiert den Inhalt eines CComSafeArray Objekts in eine SAFEARRAY Struktur.

CComSafeArray::Create

Erstellt eine CComSafeArray.

HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0);

Parameter

pBound
Ein Zeiger auf ein SAFEARRAYBOUND-Objekt.

uDims
Die Anzahl der Dimensionen im Array.

ulCount
Die Anzahl der Elemente im Array.

lLBound
Der untere Begrenzungswert; d. h. der Index des ersten Elements im Array.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Ein CComSafeArray Objekt kann aus einer vorhandenen SAFEARRAYBOUND Struktur und der Anzahl der Dimensionen oder durch Angeben der Anzahl der Elemente im Array und der unteren Grenze erstellt werden. Wenn auf das Array von C++ zugegriffen werden soll, sollte die untere Grenze 0 sein. Andere Sprachen können andere Werte für die untere Grenze zulassen (z. B. unterstützt Visual Basic Arrays mit Elementen mit einem Bereich wie -10 bis 10).

CComSafeArray::Destroy

Zerstört ein CComSafeArray -Objekt.

HRESULT Destroy();

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Zerstört ein vorhandenes CComSafeArray Objekt und alle darin enthaltenen Daten.

CComSafeArray::Detach

Trennt ein SAFEARRAY Objekt CComSafeArray .

LPSAFEARRAY Detach();

Rückgabewert

Gibt einen Zeiger auf ein SAFEARRAY Objekt zurück.

Hinweise

Mit dieser Methode wird das SAFEARRAY Objekt vom CComSafeArray Objekt getrennt.

CComSafeArray::GetAt

Ruft ein einzelnes Element aus einem eindimensionalen Array ab.

T& GetAt(LONG lIndex) const;

Parameter

lIndex
Die Indexnummer des Zurückzugebenden Werts im Array.

Rückgabewert

Gibt einen Verweis auf das erforderliche Arrayelement zurück.

CComSafeArray::GetCount

Gibt die Anzahl der Elemente des Arrays zurück.

ULONG GetCount(UINT uDim = 0) const;

Parameter

uDim
Die Arraydimension.

Rückgabewert

Gibt die Anzahl der Elemente des Arrays zurück.

Hinweise

Bei Verwendung mit einem multidimensionalen Array gibt diese Methode nur die Anzahl der Elemente in einer bestimmten Dimension zurück.

CComSafeArray::GetDimensions

Gibt die Anzahl der Dimensionen des Arrays zurück.

UINT GetDimensions() const;

Rückgabewert

Gibt die Anzahl der Dimensionen des Arrays zurück.

CComSafeArray::GetLowerBound

Gibt die untere Grenze für eine bestimmte Dimension des Arrays zurück.

LONG GetLowerBound(UINT uDim = 0) const;

Parameter

uDim
Die Arraydimension, für die die untere Grenze abgerufen werden soll. Wenn nicht angegeben, ist der Standardwert 0.

Rückgabewert

Gibt die untere Grenze zurück.

Hinweise

Wenn die untere Grenze 0 ist, gibt dies ein C-ähnliches Array an, dessen erstes Element die Elementnummer 0 ist. Im Falle eines Fehlers, z. B. ein ungültiges Dimensionsargument, ruft diese Methode mit einer HRESULT Beschreibung des Fehlers aufAtlThrow.

CComSafeArray::GetSafeArrayPtr

Gibt die Adresse des m_psa -Datenelements zurück.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Rückgabewert

Gibt einen Zeiger auf das CComSafeArray::m_psa Datenelement zurück.

CComSafeArray::GetType

Gibt den Typ der im Array gespeicherten Daten zurück.

VARTYPE GetType() const;

Rückgabewert

Gibt den Datentyp zurück, der im Array gespeichert ist, was eine der folgenden Typen sein kann:

VARTYPE	Beschreibung
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	Dezimalzeiger
VT_VARIANT	Variant-Zeiger
VT_CY	Currency-Datentyp

CComSafeArray::GetUpperBound

Gibt die obere Grenze für eine bestimmte Dimension des Arrays zurück.

LONG GetUpperBound(UINT uDim = 0) const;

Parameter

uDim
Die Arraydimension, für die die obere Grenze abgerufen werden soll. Wenn nicht angegeben, ist der Standardwert 0.

Rückgabewert

Gibt die obere Grenze zurück. Dieser Wert ist einschließlich, der maximal gültige Index für diese Dimension.

Hinweise

Im Falle eines Fehlers, z. B. ein ungültiges Dimensionsargument, ruft diese Methode mit einer HRESULT Beschreibung des Fehlers aufAtlThrow.

CComSafeArray::IsSizable

Testet, ob die Größe eines CComSafeArray -Objekts geändert werden kann.

bool IsSizable() const;

Rückgabewert

Gibt zurück TRUE , wenn die CComSafeArray Größe geändert werden kann, FALSE wenn sie nicht möglich ist.

CComSafeArray::m_psa

Enthält die Adresse der Struktur, auf die SAFEARRAY zugegriffen wird.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Ruft ein einzelnes Element aus einem mehrdimensionalen Array ab.

HRESULT MultiDimGetAt(const LONG* alIndex, T& t);

Parameter

alIndex
Zeiger auf einen Vektor von Indizes für jede Dimension im Array. Die äußerste (wichtigste) Dimension von links ist alIndex[0].

t
Ein Verweis auf die zurückgegebenen Daten.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

CComSafeArray::MultiDimSetAt

Legt den Wert eines Elements in einem mehrdimensionalen Array fest.

HRESULT MultiDimSetAt(const LONG* alIndex, const T& t);

Parameter

alIndex
Zeiger auf einen Vektor von Indizes für jede Dimension im Array. Die äußerst rechte (am wenigsten signifikante) Dimension ist alIndex[0].

T
Gibt den Wert des neuen Elements an.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Dies ist eine multidimensionale Version von CComSafeArray::SetAt.

CComSafeArray::operator []

Ruft ein Element aus dem Array ab.

T& operator[](long lindex) const;
T& operator[]int nindex) const;

Parameter

lIndex, nIndex
Die Indexnummer des erforderlichen Elements im Array.

Rückgabewert

Gibt das entsprechende Arrayelement zurück.

Hinweise

Führt eine ähnliche Funktion CComSafeArray::GetAtwie dieser Operator aus, funktioniert jedoch nur mit eindimensionalen Arrays.

CComSafeArray::operator =

Zuweisungsoperator.

ATL::CComSafeArray<T>& operator=(const ATL::CComSafeArray& saSrc);
ATL::CComSafeArray<T>& operator=(const SAFEARRAY* psaSrc);

Parameter

saSrc
Ein Verweis auf ein CComSafeArray-Objekt.

psaSrc
Ein Zeiger auf ein SAFEARRAY-Objekt.

Rückgabewert

Gibt den Typ der im Array gespeicherten Daten zurück.

CComSafeArray::operator LPSAFEARRAY

Wandelt einen Wert in einen SAFEARRAY Zeiger um.

operator LPSAFEARRAY() const;

Rückgabewert

Wandelt einen Wert in einen SAFEARRAY Zeiger um.

CComSafeArray::Resize

Ändert die Größe eines CComSafeArray -Objekts.

HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);

Parameter

pBound
Ein Zeiger auf eine SAFEARRAYBOUND Struktur, die Informationen über die Anzahl der Elemente und die untere Grenze eines Arrays enthält.

ulCount
Die angeforderte Anzahl von Objekten im Array mit geänderter Größe.

lLBound
Die untere Grenze.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Diese Methode ändert nur die Größe der äußerst rechten Dimension. Die Größe von Arrays, die zurückgegeben werdenIsResizable, werden nicht geändert.FALSE

CComSafeArray::SetAt

Legt den Wert eines Elements in einem eindimensionalen Array fest.

HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE);

Parameter

lIndex
Die Indexnummer des festzulegenden Arrayelements.

t
Der neue Wert des angegebenen Elements.

bCopy
Gibt an, ob eine Kopie der Daten erstellt werden soll. Der Standardwert ist TRUE.

Rückgabewert

Gibt S_OK bei Erfolg oder bei Einem Fehler einen Fehler HRESULT zurück.

Hinweise

Das bCopy Kennzeichen wird berücksichtigt, wenn Elemente vom Typ BSTR oder VARIANT einem Array hinzugefügt werden. Der Standardwert stellt TRUE sicher, dass eine neue Kopie aus den Daten erstellt wird, wenn das Element dem Array hinzugefügt wird.

Siehe auch

SAFEARRAY Datentyp
CComSafeArray::Create
CComSafeArray::Destroy
Klassenübersicht