CComSafeArray Klasa
Ta klasa jest otoką struktury SAFEARRAY .
Składnia
template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray
Parametry
T
Typ danych, które mają być przechowywane w tablicy.
Członkowie
Konstruktory publiczne
| Nazwa/nazwisko | opis |
|---|---|
CComSafeArray::CComSafeArray |
Konstruktor. |
CComSafeArray::~CComSafeArray |
Destruktora. |
Metody publiczne
| Nazwa/nazwisko | opis |
|---|---|
CComSafeArray::Add |
Dodaje co najmniej jeden element lub SAFEARRAY strukturę do elementu CComSafeArray. |
CComSafeArray::Attach |
SAFEARRAY Dołącza strukturę do CComSafeArray obiektu. |
CComSafeArray::CopyFrom |
Kopiuje zawartość SAFEARRAY struktury do CComSafeArray obiektu. |
CComSafeArray::CopyTo |
Tworzy kopię CComSafeArray obiektu. |
CComSafeArray::Create |
Tworzy obiekt CComSafeArray. |
CComSafeArray::Destroy |
CComSafeArray Niszczy obiekt. |
CComSafeArray::Detach |
Odłącza obiekt SAFEARRAY od CComSafeArray obiektu. |
CComSafeArray::GetAt |
Pobiera pojedynczy element z tablicy jednowymiarowej. |
CComSafeArray::GetCount |
Zwraca liczbę elementów w tablicy. |
CComSafeArray::GetDimensions |
Zwraca liczbę wymiarów w tablicy. |
CComSafeArray::GetLowerBound |
Zwraca dolną granicę dla danego wymiaru tablicy. |
CComSafeArray::GetSafeArrayPtr |
Zwraca adres m_psa elementu członkowskiego danych. |
CComSafeArray::GetType |
Zwraca typ danych przechowywanych w tablicy. |
CComSafeArray::GetUpperBound |
Zwraca górną granicę dla dowolnego wymiaru tablicy. |
CComSafeArray::IsSizable |
Sprawdza, czy CComSafeArray można zmienić rozmiar obiektu. |
CComSafeArray::MultiDimGetAt |
Pobiera pojedynczy element z tablicy wielowymiarowej. |
CComSafeArray::MultiDimSetAt |
Ustawia wartość elementu w tablicy wielowymiarowej. |
CComSafeArray::Resize |
CComSafeArray Zmienia rozmiar obiektu. |
CComSafeArray::SetAt |
Ustawia wartość elementu w tablicy jednowymiarowej. |
Operatory publiczne
| Nazwa/nazwisko | opis |
|---|---|
CComSafeArray::operator LPSAFEARRAY |
Rzutuje wartość na SAFEARRAY wskaźnik. |
CComSafeArray::operator[] |
Pobiera element z tablicy. |
CComSafeArray::operator = |
Operator przypisania. |
Publiczne elementy członkowskie danych
| Nazwa/nazwisko | opis |
|---|---|
CComSafeArray::m_psa |
Ten element członkowski danych przechowuje adres SAFEARRAY struktury. |
Uwagi
CComSafeArray Udostępnia otokę dla SAFEARRAY klasy typów danych, co ułatwia tworzenie tablic jednowymiarowych i wielowymiarowych niemal każdego z obsługiwanych VARIANT typów i zarządzanie nimi.
CComSafeArray Upraszcza przekazywanie tablic między procesami, a ponadto zapewnia dodatkowe zabezpieczenia, sprawdzając wartości indeksów tablicowych względem granic górnych i dolnych.
Dolna granica CComSafeArray elementu może zaczynać się od dowolnej wartości zdefiniowanej przez użytkownika. Jednak tablice, do których uzyskuje się dostęp za pośrednictwem języka C++, powinny używać dolnej granicy 0. Inne języki, takie jak Visual Basic, mogą używać innych wartości ograniczenia (na przykład od -10 do 10).
Użyj CComSafeArray::Create polecenia , aby utworzyć CComSafeArray obiekt i CComSafeArray::Destroy usunąć go.
Element CComSafeArray może zawierać następujący podzestaw VARIANT typów danych:
VARTYPE |
opis |
|---|---|
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 |
wskaźnik dziesiętny |
VT_VARIANT |
wskaźnik wariantu |
VT_CY |
Currency — Typ danych |
Wymagania
Nagłówka:atlsafe.h
Przykład
// 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
Dodaje co najmniej jeden element lub SAFEARRAY strukturę do elementu 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
Wskaźnik do SAFEARRAY obiektu.
ulCount
Liczba obiektów do dodania do tablicy.
pT
Wskaźnik do co najmniej jednego obiektu, który ma zostać dodany do tablicy.
t
Odwołanie do obiektu, który ma zostać dodany do tablicy.
bCopy
Wskazuje, czy należy utworzyć kopię danych. Wartość domyślna to TRUE.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Nowe obiekty są dołączane na końcu istniejącego SAFEARRAY obiektu. Dodawanie obiektu do obiektu wielowymiarowego SAFEARRAY nie jest obsługiwane. Podczas dodawania istniejącej tablicy obiektów obie tablice muszą zawierać elementy tego samego typu.
Flaga jest brana bCopy pod uwagę, gdy elementy typu BSTR lub VARIANT są dodawane do tablicy. Wartość domyślna TRUE gwarantuje, że nowa kopia zostanie wykonana z danych po dodaniu elementu do tablicy.
CComSafeArray::Attach
SAFEARRAY Dołącza strukturę do CComSafeArray obiektu.
HRESULT Attach(const SAFEARRAY* psaSrc);
Parametry
psaSrc
Wskaźnik do SAFEARRAY struktury.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
SAFEARRAY Dołącza strukturę do CComSafeArray obiektu, udostępniając istniejące 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
Liczba elementów w tablicy.
lLBound
Niższa wartość ograniczenia; oznacza to indeks pierwszego elementu w tablicy.
pBound
Wskaźnik do SAFEARRAYBOUND struktury.
uDims
Liczba wymiarów w tablicy.
saSrc
Odwołanie do SAFEARRAY struktury lub CComSafeArray obiektu. W obu przypadkach konstruktor używa tego odwołania, aby utworzyć kopię tablicy, więc tablica nie jest przywołyna po konstrukcji.
psaSrc
Wskaźnik do SAFEARRAY struktury. Konstruktor używa tego adresu, aby utworzyć kopię tablicy, więc tablica nigdy nie jest przywoływała po konstrukcji.
Uwagi
Tworzy obiekt CComSafeArray.
CComSafeArray::~CComSafeArray
Destruktora.
~CComSafeArray() throw()
Uwagi
Zwalnia wszystkie przydzielone zasoby.
CComSafeArray::CopyFrom
Kopiuje zawartość SAFEARRAY struktury do CComSafeArray obiektu.
HRESULT CopyFrom(LPSAFEARRAY* ppArray);
Parametry
ppArray
Wskaźnik do SAFEARRAY skopiowania.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Ta metoda kopiuje zawartość obiektu SAFEARRAY do bieżącego CComSafeArray obiektu. Istniejąca zawartość tablicy jest zastępowana.
CComSafeArray::CopyTo
Tworzy kopię CComSafeArray obiektu.
HRESULT CopyTo(LPSAFEARRAY* ppArray);
Parametry
ppArray
Wskaźnik do lokalizacji, w której ma zostać utworzony nowy SAFEARRAYelement .
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Ta metoda kopiuje zawartość CComSafeArray obiektu do SAFEARRAY struktury.
CComSafeArray::Create
Tworzy element CComSafeArray.
HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0);
Parametry
pBound
Wskaźnik do SAFEARRAYBOUND obiektu.
uDims
Liczba wymiarów w tablicy.
ulCount
Liczba elementów w tablicy.
lLBound
Niższa wartość ograniczenia; oznacza to indeks pierwszego elementu w tablicy.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
CComSafeArray Obiekt można utworzyć na podstawie istniejącej SAFEARRAYBOUND struktury i liczby wymiarów lub określając liczbę elementów w tablicy i dolną granicę. Jeśli dostęp do tablicy ma być uzyskiwany z języka C++, dolna granica powinna wynosić 0. Inne języki mogą zezwalać na inne wartości dla dolnej granicy (na przykład język Visual Basic obsługuje tablice z elementami z zakresem, takim jak -10 do 10).
CComSafeArray::Destroy
CComSafeArray Niszczy obiekt.
HRESULT Destroy();
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Niszczy istniejący CComSafeArray obiekt i wszystkie zawarte w nim dane.
CComSafeArray::Detach
Odłącza obiekt SAFEARRAY od CComSafeArray obiektu.
LPSAFEARRAY Detach();
Wartość zwracana
Zwraca wskaźnik do SAFEARRAY obiektu.
Uwagi
Ta metoda odłącza SAFEARRAY obiekt od CComSafeArray obiektu.
CComSafeArray::GetAt
Pobiera pojedynczy element z tablicy jednowymiarowej.
T& GetAt(LONG lIndex) const;
Parametry
lIndex
Liczba indeksów wartości w tablicy do zwrócenia.
Wartość zwracana
Zwraca odwołanie do wymaganego elementu tablicy.
CComSafeArray::GetCount
Zwraca liczbę elementów w tablicy.
ULONG GetCount(UINT uDim = 0) const;
Parametry
uDim
Wymiar tablicy.
Wartość zwracana
Zwraca liczbę elementów w tablicy.
Uwagi
W przypadku użycia z tablicą wielowymiarową ta metoda zwróci tylko liczbę elementów w określonym wymiarze.
CComSafeArray::GetDimensions
Zwraca liczbę wymiarów w tablicy.
UINT GetDimensions() const;
Wartość zwracana
Zwraca liczbę wymiarów w tablicy.
CComSafeArray::GetLowerBound
Zwraca dolną granicę dla danego wymiaru tablicy.
LONG GetLowerBound(UINT uDim = 0) const;
Parametry
uDim
Wymiar tablicy, dla którego ma być uzyskiwana dolna granica. W przypadku pominięcia wartość domyślna to 0.
Wartość zwracana
Zwraca dolną granicę.
Uwagi
Jeśli dolna granica wynosi 0, oznacza to tablicę przypominającą język C, której pierwszym elementem jest numer 0. W przypadku błędu, na przykład nieprawidłowy argument wymiaru, ta metoda wywołuje AtlThrow błąd z opisem HRESULT błędu.
CComSafeArray::GetSafeArrayPtr
Zwraca adres m_psa elementu członkowskiego danych.
LPSAFEARRAY* GetSafeArrayPtr() throw();
Wartość zwracana
Zwraca wskaźnik do CComSafeArray::m_psa elementu członkowskiego danych.
CComSafeArray::GetType
Zwraca typ danych przechowywanych w tablicy.
VARTYPE GetType() const;
Wartość zwracana
Zwraca typ danych przechowywanych w tablicy, który może być dowolnym z następujących typów:
VARTYPE |
opis |
|---|---|
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 |
wskaźnik dziesiętny |
VT_VARIANT |
wskaźnik wariantu |
VT_CY |
Currency — Typ danych |
CComSafeArray::GetUpperBound
Zwraca górną granicę dla dowolnego wymiaru tablicy.
LONG GetUpperBound(UINT uDim = 0) const;
Parametry
uDim
Wymiar tablicy, dla którego ma być pobierana górna granica. W przypadku pominięcia wartość domyślna to 0.
Wartość zwracana
Zwraca górną granicę. Ta wartość jest inkluzywna— maksymalny prawidłowy indeks dla tego wymiaru.
Uwagi
W przypadku błędu, na przykład nieprawidłowy argument wymiaru, ta metoda wywołuje AtlThrow błąd z opisem HRESULT błędu.
CComSafeArray::IsSizable
Sprawdza, czy CComSafeArray można zmienić rozmiar obiektu.
bool IsSizable() const;
Wartość zwracana
Zwraca wartość TRUE , jeśli CComSafeArray można zmienić rozmiar, FALSE jeśli nie.
CComSafeArray::m_psa
Przechowuje adres struktury, do której SAFEARRAY uzyskiwano dostęp.
LPSAFEARRAY m_psa;
CComSafeArray::MultiDimGetAt
Pobiera pojedynczy element z tablicy wielowymiarowej.
HRESULT MultiDimGetAt(const LONG* alIndex, T& t);
Parametry
alIndex
Wskaźnik do wektora indeksów dla każdego wymiaru w tablicy. Najbardziej znaczący (najbardziej znaczący) wymiar po lewej stronie to alIndex[0].
t
Odwołanie do zwróconych danych.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
CComSafeArray::MultiDimSetAt
Ustawia wartość elementu w tablicy wielowymiarowej.
HRESULT MultiDimSetAt(const LONG* alIndex, const T& t);
Parametry
alIndex
Wskaźnik do wektora indeksów dla każdego wymiaru w tablicy. Najbardziej znaczący (najmniej znaczący) wymiar to alIndex[0].
T
Określa wartość nowego elementu.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Jest to wersja wielowymiarowa programu CComSafeArray::SetAt.
CComSafeArray::operator []
Pobiera element z tablicy.
T& operator[](long lindex) const;
T& operator[]int nindex) const;
Parametry
lIndex, nIndex
Numer indeksu wymaganego elementu w tablicy.
Wartość zwracana
Zwraca odpowiedni element tablicy.
Uwagi
Wykonuje podobną funkcję do CComSafeArray::GetAt, jednak ten operator działa tylko z tablicami jednowymiarowymi.
CComSafeArray::operator =
Operator przypisania.
ATL::CComSafeArray<T>& operator=(const ATL::CComSafeArray& saSrc);
ATL::CComSafeArray<T>& operator=(const SAFEARRAY* psaSrc);
Parametry
saSrc
Odwołanie do CComSafeArray obiektu.
psaSrc
Wskaźnik do SAFEARRAY obiektu.
Wartość zwracana
Zwraca typ danych przechowywanych w tablicy.
CComSafeArray::operator LPSAFEARRAY
Rzutuje wartość na SAFEARRAY wskaźnik.
operator LPSAFEARRAY() const;
Wartość zwracana
Rzutuje wartość na SAFEARRAY wskaźnik.
CComSafeArray::Resize
CComSafeArray Zmienia rozmiar obiektu.
HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);
Parametry
pBound
Wskaźnik do SAFEARRAYBOUND struktury zawierającej informacje o liczbie elementów i dolnej granicy tablicy.
ulCount
Żądana liczba obiektów w tablicy o zmienionym rozmiarze.
lLBound
Dolna granica.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Ta metoda zmienia rozmiar tylko najbardziej odpowiedniego wymiaru. Nie spowoduje to zmiany rozmiaru tablic zwracanych IsResizable jako FALSE.
CComSafeArray::SetAt
Ustawia wartość elementu w tablicy jednowymiarowej.
HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE);
Parametry
lIndex
Numer indeksu elementu tablicy do ustawienia.
t
Nowa wartość określonego elementu.
bCopy
Wskazuje, czy należy utworzyć kopię danych. Wartość domyślna to TRUE.
Wartość zwracana
Zwraca wartość S_OK powodzenia lub błąd HRESULT po niepowodzeniu.
Uwagi
Flaga jest brana bCopy pod uwagę, gdy elementy typu BSTR lub VARIANT są dodawane do tablicy. Wartość domyślna TRUE gwarantuje, że nowa kopia zostanie wykonana z danych po dodaniu elementu do tablicy.
Zobacz też
SAFEARRAY Typ danych
CComSafeArray::Create
CComSafeArray::Destroy
Omówienie klasy
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla