CComSafeArray Třída

Tato třída je obálka pro SAFEARRAY strukturu.

Syntaxe

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

Parametry

T
Typ dat, která mají být uložena v poli.

Členové

Veřejné konstruktory

Název	Popis
CComSafeArray::CComSafeArray	Konstruktor
CComSafeArray::~CComSafeArray	Destruktor.

Veřejné metody

Název	Popis
CComSafeArray::Add	Přidá jeden nebo více prvků nebo SAFEARRAY strukturu do objektu CComSafeArray.
CComSafeArray::Attach	SAFEARRAY Připojí strukturu k objektuCComSafeArray.
CComSafeArray::CopyFrom	Zkopíruje obsah SAFEARRAY struktury do objektu CComSafeArray .
CComSafeArray::CopyTo	Vytvoří kopii objektu CComSafeArray .
CComSafeArray::Create	CComSafeArray Vytvoří objekt.
CComSafeArray::Destroy	CComSafeArray Zničí objekt.
CComSafeArray::Detach	Odpojte objekt SAFEARRAY od objektu CComSafeArray .
CComSafeArray::GetAt	Načte jeden prvek z jednorozměrného pole.
CComSafeArray::GetCount	Vrátí počet prvků v matici.
CComSafeArray::GetDimensions	Vrátí počet dimenzí v matici.
CComSafeArray::GetLowerBound	Vrátí dolní mez pro danou dimenzi pole.
CComSafeArray::GetSafeArrayPtr	Vrátí adresu datového člena m_psa .
CComSafeArray::GetType	Vrátí typ dat uložených v poli.
CComSafeArray::GetUpperBound	Vrátí horní mez pro libovolnou dimenzi pole.
CComSafeArray::IsSizable	Testuje, jestli lze změnit velikost objektu CComSafeArray .
CComSafeArray::MultiDimGetAt	Načte jeden prvek z multidimenzionálního pole.
CComSafeArray::MultiDimSetAt	Nastaví hodnotu prvku v multidimenzionálním poli.
CComSafeArray::Resize	Změní velikost objektu CComSafeArray .
CComSafeArray::SetAt	Nastaví hodnotu prvku v jednorozměrném poli.

Veřejné operátory

Název	Popis
CComSafeArray::operator LPSAFEARRAY	Přetypuje hodnotu na SAFEARRAY ukazatel.
CComSafeArray::operator[]	Načte prvek z pole.
CComSafeArray::operator =	Operátor přiřazení.

Veřejné datové členy

Název	Popis
CComSafeArray::m_psa	Tento datový člen obsahuje adresu SAFEARRAY struktury.

Poznámky

CComSafeArray poskytuje obálku pro třídu datového SAFEARRAY typu , což usnadňuje vytváření a správu jednorozměrných a multidimenzionálních polí téměř všech podporovaných VARIANT typů.

CComSafeArray zjednodušuje předávání polí mezi procesy a navíc poskytuje dodatečné zabezpečení tím, že kontroluje hodnoty indexu pole proti horním a dolním hranicím.

Dolní mez objektu CComSafeArray může začínat na libovolné uživatelem definované hodnotě. Pole, ke kterým se přistupuje prostřednictvím jazyka C++, by však měla používat dolní mez 0. Jiné jazyky, jako je Visual Basic, mohou používat jiné ohraničující hodnoty (například -10 až 10).

Slouží CComSafeArray::Create k vytvoření objektu CComSafeArray a CComSafeArray::Destroy k jeho odstranění.

A CComSafeArray může obsahovat následující podmnožinu datových VARIANT typů:

VARTYPE	Popis
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	desetinná čárka
VT_VARIANT	ukazatel varianty
VT_CY	Měna – datový typ

Požadavky

Záhlaví: atlsafe.h

Příklad

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

Přidá jeden nebo více prvků nebo SAFEARRAY strukturu do objektu CComSafeArray.

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

Parametry

psaSrc
Ukazatel na SAFEARRAY objekt.

ulCount
Počet objektů, které se mají přidat do pole.

pT
Ukazatel na jeden nebo více objektů, které se mají přidat do pole.

t
Odkaz na objekt, který se má přidat do pole.

bCopy
Určuje, jestli se má vytvořit kopie dat. Výchozí hodnota je TRUE.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Nové objekty jsou připojeny na konec existujícího SAFEARRAY objektu. Přidání objektu do multidimenzionálního SAFEARRAY objektu není podporováno. Při přidávání existujícího pole objektů musí obě pole obsahovat prvky stejného typu.

Příznak bCopy se bere v úvahu, když jsou prvky typu BSTR nebo VARIANT jsou přidány do pole. Výchozí hodnota TRUE zajišťuje, že se při přidání prvku do pole vytvoří nová kopie dat.

CComSafeArray::Attach

SAFEARRAY Připojí strukturu k objektuCComSafeArray.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parametry

psaSrc
Ukazatel na SAFEARRAY strukturu.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

SAFEARRAY Připojí strukturu k objektu CComSafeArray a zpřístupní existující CComSafeArray metody.

CComSafeArray::CComSafeArray

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

Parametry

bound
Struktura SAFEARRAYBOUND .

ulCount
Počet prvků v poli.

lLBound
Dolní mez hodnoty; to znamená index prvního prvku v poli.

pBound
Ukazatel na SAFEARRAYBOUND strukturu.

uDims
Počet dimenzí v matici.

saSrc
Odkaz na SAFEARRAY strukturu nebo CComSafeArray objekt. V obou případech konstruktor použije tento odkaz k vytvoření kopie pole, takže pole není odkazováno po konstrukci.

psaSrc
Ukazatel na SAFEARRAY strukturu. Konstruktor používá tuto adresu k vytvoření kopie pole, takže pole není nikdy odkazováno po konstrukci.

Poznámky

CComSafeArray Vytvoří objekt.

CComSafeArray::~CComSafeArray

Destruktor.

~CComSafeArray() throw()

Poznámky

Uvolní všechny přidělené prostředky.

CComSafeArray::CopyFrom

Zkopíruje obsah SAFEARRAY struktury do objektu CComSafeArray .

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parametry

ppArray
Ukazatel na kopii SAFEARRAY .

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Tato metoda zkopíruje obsah objektu SAFEARRAY do aktuálního CComSafeArray objektu. Stávající obsah pole se nahradí.

CComSafeArray::CopyTo

Vytvoří kopii objektu CComSafeArray .

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parametry

ppArray
Ukazatel na umístění, ve kterém chcete vytvořit nový SAFEARRAY.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Tato metoda zkopíruje obsah objektu CComSafeArray SAFEARRAY do struktury.

CComSafeArray::Create

Vytvoří .CComSafeArray

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

Parametry

pBound
Ukazatel na SAFEARRAYBOUND objekt.

uDims
Počet dimenzí v matici

ulCount
Počet prvků v poli.

lLBound
Dolní mez hodnoty; to znamená index prvního prvku v poli.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Objekt CComSafeArray lze vytvořit z existující SAFEARRAYBOUND struktury a počtu dimenzí nebo zadáním počtu prvků v poli a dolní mez. Pokud má být pole přístupné z jazyka C++, dolní mez by měla být 0. Jiné jazyky mohou povolit jiné hodnoty pro dolní mez (například Visual Basic podporuje pole s prvky s rozsahem, například -10 až 10).

CComSafeArray::Destroy

CComSafeArray Zničí objekt.

HRESULT Destroy();

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Zničí existující CComSafeArray objekt a všechna data, která obsahuje.

CComSafeArray::Detach

Odpojte objekt SAFEARRAY od objektu CComSafeArray .

LPSAFEARRAY Detach();

Vrácená hodnota

Vrátí ukazatel na SAFEARRAY objekt.

Poznámky

Tato metoda odpojte SAFEARRAY objekt od objektu CComSafeArray .

CComSafeArray::GetAt

Načte jeden prvek z jednorozměrného pole.

T& GetAt(LONG lIndex) const;

Parametry

lIndex
Číslo indexu hodnoty v matici, která se má vrátit.

Vrácená hodnota

Vrátí odkaz na požadovaný prvek pole.

CComSafeArray::GetCount

Vrátí počet prvků v matici.

ULONG GetCount(UINT uDim = 0) const;

Parametry

uDim
Dimenze pole.

Vrácená hodnota

Vrátí počet prvků v matici.

Poznámky

Při použití s multidimenzionálním polem tato metoda vrátí počet prvků pouze v konkrétní dimenzi.

CComSafeArray::GetDimensions

Vrátí počet dimenzí v matici.

UINT GetDimensions() const;

Vrácená hodnota

Vrátí počet dimenzí v matici.

CComSafeArray::GetLowerBound

Vrátí dolní mez pro danou dimenzi pole.

LONG GetLowerBound(UINT uDim = 0) const;

Parametry

uDim
Dimenze pole, pro kterou chcete získat dolní mez. Pokud tuto hodnotu vynecháte, výchozí hodnota je 0.

Vrácená hodnota

Vrátí dolní mez.

Poznámky

Pokud je dolní mez 0, označuje pole podobné jazyku C, jehož prvním prvkem je prvek číslo 0. V případě chyby, například neplatný argument dimenze, tato metoda volá AtlThrow s popisem HRESULT chyby.

CComSafeArray::GetSafeArrayPtr

Vrátí adresu datového člena m_psa .

LPSAFEARRAY* GetSafeArrayPtr() throw();

Vrácená hodnota

Vrátí ukazatel na CComSafeArray::m_psa datový člen.

CComSafeArray::GetType

Vrátí typ dat uložených v poli.

VARTYPE GetType() const;

Vrácená hodnota

Vrátí typ dat uložených v poli, což může být některý z následujících typů:

VARTYPE	Popis
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	desetinná čárka
VT_VARIANT	ukazatel varianty
VT_CY	Měna – datový typ

CComSafeArray::GetUpperBound

Vrátí horní mez pro libovolnou dimenzi pole.

LONG GetUpperBound(UINT uDim = 0) const;

Parametry

uDim
Rozměr pole, pro který se má získat horní mez. Pokud tuto hodnotu vynecháte, výchozí hodnota je 0.

Vrácená hodnota

Vrátí horní mez. Tato hodnota je inkluzivní, maximální platný index pro tuto dimenzi.

Poznámky

V případě chyby, například neplatný argument dimenze, tato metoda volá AtlThrow s popisem HRESULT chyby.

CComSafeArray::IsSizable

Testuje, jestli lze změnit velikost objektu CComSafeArray .

bool IsSizable() const;

Vrácená hodnota

Vrátí TRUE hodnotu, pokud CComSafeArray je možné změnit velikost, FALSE pokud ji nelze.

CComSafeArray::m_psa

Obsahuje adresu struktury, ke které se SAFEARRAY přistupuje.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Načte jeden prvek z multidimenzionálního pole.

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

Parametry

alIndex
Ukazatel na vektor indexů pro každou dimenzi v poli. Nejvýraznější (nejvýznamnější) dimenze je alIndex[0].

t
Odkaz na vrácená data.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

CComSafeArray::MultiDimSetAt

Nastaví hodnotu prvku v multidimenzionálním poli.

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

Parametry

alIndex
Ukazatel na vektor indexů pro každou dimenzi v poli. Nejvýraznější (nejméně významný) rozměr je alIndex[0].

T
Určuje hodnotu nového prvku.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Toto je multidimenzionální verze CComSafeArray::SetAt.

CComSafeArray::operator []

Načte prvek z pole.

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

Parametry

lIndex, nIndex
Číslo indexu požadovaného prvku v poli.

Vrácená hodnota

Vrátí příslušný prvek pole.

Poznámky

Provádí podobnou funkci, jako CComSafeArray::GetAtje však tento operátor funguje pouze s jednorozměrnými poli.

CComSafeArray::operator =

Operátor přiřazení.

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

Parametry

saSrc
Odkaz na CComSafeArray objekt.

psaSrc
Ukazatel na SAFEARRAY objekt.

Vrácená hodnota

Vrátí typ dat uložených v poli.

CComSafeArray::operator LPSAFEARRAY

Přetypuje hodnotu na SAFEARRAY ukazatel.

operator LPSAFEARRAY() const;

Vrácená hodnota

Přetypuje hodnotu na SAFEARRAY ukazatel.

CComSafeArray::Resize

Změní velikost objektu CComSafeArray .

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

Parametry

pBound
Ukazatel na SAFEARRAYBOUND strukturu, která obsahuje informace o počtu prvků a dolní hranici pole.

ulCount
Požadovaný počet objektů v poli se změněnou velikostí

lLBound
Dolní mez.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Tato metoda změní velikost pouze dimenze úplně vpravo. Velikost polí, která se vrátí IsResizable jako FALSE.

CComSafeArray::SetAt

Nastaví hodnotu prvku v jednorozměrném poli.

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

Parametry

lIndex
Číslo indexu prvku pole, který chcete nastavit.

t
Nová hodnota zadaného prvku.

bCopy
Určuje, jestli se má vytvořit kopie dat. Výchozí hodnota je TRUE.

Vrácená hodnota

Vrátí S_OK úspěch nebo chybu při selhání HRESULT .

Poznámky

Příznak bCopy se bere v úvahu, když jsou prvky typu BSTR nebo VARIANT jsou přidány do pole. Výchozí hodnota TRUE zajišťuje, že se při přidání prvku do pole vytvoří nová kopie dat.

Viz také

SAFEARRAY Datový typ
CComSafeArray::Create
CComSafeArray::Destroy
Přehled třídy