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
Kopfball: 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.
Weitere Informationen
SAFEARRAY Datentyp
CComSafeArray::Create
CComSafeArray::Destroy
Klassenübersicht
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für