Udostępnij za pośrednictwem

CComSafeArray Klasa

  • Artykuł

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.

Elementy członkowskie

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łówek: 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. Domyślna wartość 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. Domyślna wartość 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