Bagikan melalui

CComSafeArray Kelas

  • Artikel

Kelas ini adalah pembungkus untuk SAFEARRAY struktur.

Sintaks

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

Parameter

T
Jenis data yang akan disimpan dalam array.

Anggota

Konstruktor Publik

Nama Deskripsi
CComSafeArray::CComSafeArray Konstruktor.
CComSafeArray::~CComSafeArray Destruktor.

Metode Publik

Nama Deskripsi
CComSafeArray::Add Menambahkan satu atau beberapa elemen, atau SAFEARRAY struktur, ke CComSafeArray.
CComSafeArray::Attach Melampirkan SAFEARRAY struktur ke CComSafeArray objek.
CComSafeArray::CopyFrom Menyalin konten SAFEARRAY struktur ke CComSafeArray dalam objek.
CComSafeArray::CopyTo Membuat salinan CComSafeArray objek.
CComSafeArray::Create CComSafeArray Membuat objek.
CComSafeArray::Destroy Menghancurkan objek CComSafeArray .
CComSafeArray::Detach Mencopot SAFEARRAY dari CComSafeArray objek.
CComSafeArray::GetAt Mengambil elemen tunggal dari array dimensi tunggal.
CComSafeArray::GetCount Mengembalikan jumlah elemen dalam array.
CComSafeArray::GetDimensions Mengembalikan jumlah dimensi dalam array.
CComSafeArray::GetLowerBound Mengembalikan batas bawah untuk dimensi array tertentu.
CComSafeArray::GetSafeArrayPtr Mengembalikan alamat m_psa anggota data.
CComSafeArray::GetType Mengembalikan jenis data yang disimpan dalam array.
CComSafeArray::GetUpperBound Mengembalikan batas atas untuk dimensi array apa pun.
CComSafeArray::IsSizable Menguji apakah CComSafeArray objek dapat diubah ukurannya.
CComSafeArray::MultiDimGetAt Mengambil elemen tunggal dari array multididat.
CComSafeArray::MultiDimSetAt Mengatur nilai elemen dalam array multidimensi.
CComSafeArray::Resize Mengubah ukuran CComSafeArray objek.
CComSafeArray::SetAt Mengatur nilai elemen dalam array dimensi tunggal.

Operator Publik

Nama Deskripsi
CComSafeArray::operator LPSAFEARRAY Melemparkan nilai ke SAFEARRAY penunjuk.
CComSafeArray::operator[] Mengambil elemen dari array.
CComSafeArray::operator = Operator penugasan.

Anggota Data Publik

Nama Deskripsi
CComSafeArray::m_psa Anggota data ini memegang alamat SAFEARRAY struktur.

Keterangan

CComSafeArray menyediakan pembungkus untuk SAFEARRAY kelas jenis data, menjadikannya masalah sederhana untuk membuat dan mengelola array tunggal dan multidansa dari hampir semua jenis yang didukung VARIANT .

CComSafeArray menyederhanakan larik passing antar proses, dan selain itu memberikan keamanan ekstra dengan memeriksa nilai indeks array terhadap batas atas dan bawah.

Batas bawah CComSafeArray dapat dimulai pada nilai yang ditentukan pengguna; namun, array yang diakses melalui C++ harus menggunakan batas bawah 0. Bahasa lain seperti Visual Basic dapat menggunakan nilai batas lainnya (misalnya, -10 hingga 10).

Gunakan CComSafeArray::Create untuk membuat CComSafeArray objek, dan CComSafeArray::Destroy untuk menghapusnya.

CComSafeArray Bisa berisi subset jenis VARIANT data berikut:

VARTYPE Deskripsi
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 penunjuk desimal
VT_VARIANT penunjuk varian
VT_CY Jenis data mata uang

Persyaratan

Header: atlsafe.h

Contoh

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

Menambahkan satu atau beberapa elemen, atau SAFEARRAY struktur, ke 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
Penunjuk ke SAFEARRAY objek.

ulCount
Jumlah objek yang akan ditambahkan ke array.

pT
Penunjuk ke satu atau beberapa objek yang akan ditambahkan ke array.

t
Referensi ke objek yang akan ditambahkan ke array.

bCopy
Menunjukkan apakah salinan data harus dibuat. Nilai defaultnya adalah TRUE.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Objek baru ditambahkan ke akhir objek yang ada SAFEARRAY . Menambahkan objek ke objek multidimensi SAFEARRAY tidak didukung. Saat menambahkan array objek yang ada, kedua array harus berisi elemen dengan jenis yang sama.

Bendera bCopy diperhitungkan ketika elemen jenis BSTR atau VARIANT ditambahkan ke array. Nilai TRUE default memastikan bahwa salinan baru terbuat dari data saat elemen ditambahkan ke array.

CComSafeArray::Attach

Melampirkan SAFEARRAY struktur ke CComSafeArray objek.

HRESULT Attach(const SAFEARRAY* psaSrc);

Parameter

psaSrc
Penunjuk ke SAFEARRAY struktur.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Melampirkan SAFEARRAY struktur ke CComSafeArray objek, membuat metode yang ada CComSafeArray tersedia.

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

Parameter

bound
Sebuah SAFEARRAYBOUND struktur.

ulCount
Jumlah elemen dalam array.

lLBound
Nilai terikat yang lebih rendah; yaitu, indeks elemen pertama dalam array.

pBound
Penunjuk ke SAFEARRAYBOUND struktur.

uDims
Jumlah dimensi dalam array.

saSrc
Referensi ke SAFEARRAY struktur atau CComSafeArray objek. Dalam kedua kasus, konstruktor menggunakan referensi ini untuk membuat salinan array, sehingga array tidak dirujuk setelah konstruksi.

psaSrc
Penunjuk ke SAFEARRAY struktur. Konstruktor menggunakan alamat ini untuk membuat salinan array, sehingga array tidak pernah dirujuk setelah konstruksi.

Keterangan

CComSafeArray Membuat objek.

CComSafeArray::~CComSafeArray

Destruktor.

~CComSafeArray() throw()

Keterangan

Membebaskan semua sumber daya yang dialokasikan.

CComSafeArray::CopyFrom

Menyalin konten SAFEARRAY struktur ke CComSafeArray dalam objek.

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Parameter

ppArray
Arahkan ke SAFEARRAY untuk menyalin.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Metode ini menyalin isi ke SAFEARRAY dalam objek saat ini CComSafeArray . Konten array yang ada diganti.

CComSafeArray::CopyTo

Membuat salinan CComSafeArray objek.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Parameter

ppArray
Penunjuk ke lokasi untuk membuat yang baru SAFEARRAY.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Metode ini menyalin konten CComSafeArray objek ke dalam SAFEARRAY struktur.

CComSafeArray::Create

CComSafeArrayMembuat .

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

Parameter

pBound
Penunjuk ke SAFEARRAYBOUND objek.

uDims
Jumlah dimensi dalam array.

ulCount
Jumlah elemen dalam array.

lLBound
Nilai terikat yang lebih rendah; yaitu, indeks elemen pertama dalam array.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Objek CComSafeArray dapat dibuat dari struktur yang ada SAFEARRAYBOUND dan jumlah dimensi, atau dengan menentukan jumlah elemen dalam array dan batas bawah. Jika array akan diakses dari C++, batas bawah harus 0. Bahasa lain dapat memungkinkan nilai lain untuk batas bawah (misalnya, Visual Basic mendukung array dengan elemen dengan rentang seperti -10 hingga 10).

CComSafeArray::Destroy

Menghancurkan objek CComSafeArray .

HRESULT Destroy();

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Menghancurkan objek yang ada CComSafeArray dan semua data yang ada di dalamnya.

CComSafeArray::Detach

Mencopot SAFEARRAY dari CComSafeArray objek.

LPSAFEARRAY Detach();

Nilai hasil

Mengembalikan penunjuk ke SAFEARRAY objek.

Keterangan

Metode ini mencopot SAFEARRAY objek dari CComSafeArray objek.

CComSafeArray::GetAt

Mengambil elemen tunggal dari array dimensi tunggal.

T& GetAt(LONG lIndex) const;

Parameter

lIndex
Jumlah indeks nilai dalam array yang akan dikembalikan.

Nilai hasil

Mengembalikan referensi ke elemen array yang diperlukan.

CComSafeArray::GetCount

Mengembalikan jumlah elemen dalam array.

ULONG GetCount(UINT uDim = 0) const;

Parameter

uDim
Dimensi array.

Nilai hasil

Mengembalikan jumlah elemen dalam array.

Keterangan

Ketika digunakan dengan array multidireksional, metode ini akan mengembalikan jumlah elemen dalam dimensi tertentu saja.

CComSafeArray::GetDimensions

Mengembalikan jumlah dimensi dalam array.

UINT GetDimensions() const;

Nilai hasil

Mengembalikan jumlah dimensi dalam array.

CComSafeArray::GetLowerBound

Mengembalikan batas bawah untuk dimensi array tertentu.

LONG GetLowerBound(UINT uDim = 0) const;

Parameter

uDim
Dimensi array untuk mendapatkan batas bawah. Jika dihilangkan, defaultnya adalah 0.

Nilai hasil

Mengembalikan batas bawah.

Keterangan

Jika batas bawah adalah 0, ini menunjukkan array seperti C yang elemen pertamanya adalah elemen nomor 0. Jika terjadi kesalahan, misalnya, argumen dimensi yang tidak valid, metode ini memanggil AtlThrow dengan menjelaskan HRESULT kesalahan.

CComSafeArray::GetSafeArrayPtr

Mengembalikan alamat m_psa anggota data.

LPSAFEARRAY* GetSafeArrayPtr() throw();

Nilai hasil

Mengembalikan penunjuk ke CComSafeArray::m_psa anggota data.

CComSafeArray::GetType

Mengembalikan jenis data yang disimpan dalam array.

VARTYPE GetType() const;

Nilai hasil

Mengembalikan jenis data yang disimpan dalam array, yang bisa menjadi salah satu jenis berikut:

VARTYPE Deskripsi
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 penunjuk desimal
VT_VARIANT penunjuk varian
VT_CY Jenis data mata uang

CComSafeArray::GetUpperBound

Mengembalikan batas atas untuk dimensi array apa pun.

LONG GetUpperBound(UINT uDim = 0) const;

Parameter

uDim
Dimensi array untuk mendapatkan batas atas. Jika dihilangkan, defaultnya adalah 0.

Nilai hasil

Mengembalikan batas atas. Nilai ini inklusif, indeks maksimum yang valid untuk dimensi ini.

Keterangan

Jika terjadi kesalahan, misalnya, argumen dimensi yang tidak valid, metode ini memanggil AtlThrow dengan menjelaskan HRESULT kesalahan.

CComSafeArray::IsSizable

Menguji apakah CComSafeArray objek dapat diubah ukurannya.

bool IsSizable() const;

Nilai hasil

Mengembalikan TRUE jika CComSafeArray dapat diubah ukurannya, FALSE jika tidak dapat.

CComSafeArray::m_psa

Memegang alamat struktur yang SAFEARRAY diakses.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Mengambil elemen tunggal dari array multididat.

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

Parameter

alIndex
Penunjuk ke vektor indeks untuk setiap dimensi dalam array. Dimensi paling kiri (paling signifikan) adalah alIndex[0].

t
Referensi ke data yang dikembalikan.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

CComSafeArray::MultiDimSetAt

Mengatur nilai elemen dalam array multidimensi.

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

Parameter

alIndex
Penunjuk ke vektor indeks untuk setiap dimensi dalam array. Dimensi paling kanan (paling tidak signifikan) adalah alIndex[0].

T
Menentukan nilai elemen baru.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Ini adalah versi multidisipional dari CComSafeArray::SetAt.

CComSafeArray::operator []

Mengambil elemen dari array.

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

Parameter

lIndex, nIndex
Jumlah indeks elemen yang diperlukan dalam array.

Nilai hasil

Mengembalikan elemen array yang sesuai.

Keterangan

Melakukan fungsi CComSafeArray::GetAtserupa dengan , namun operator ini hanya berfungsi dengan array dimensi tunggal.

CComSafeArray::operator =

Operator penugasan.

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

Parameter

saSrc
Referensi ke CComSafeArray objek.

psaSrc
Penunjuk ke SAFEARRAY objek.

Nilai hasil

Mengembalikan jenis data yang disimpan dalam array.

CComSafeArray::operator LPSAFEARRAY

Melemparkan nilai ke SAFEARRAY penunjuk.

operator LPSAFEARRAY() const;

Nilai hasil

Melemparkan nilai ke SAFEARRAY penunjuk.

CComSafeArray::Resize

Mengubah ukuran CComSafeArray objek.

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

Parameter

pBound
Penunjuk ke SAFEARRAYBOUND struktur yang berisi informasi tentang jumlah elemen dan batas bawah array.

ulCount
Jumlah objek yang diminta dalam array yang diubah ukurannya.

lLBound
Batas bawah.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Metode ini hanya mengubah ukuran dimensi paling kanan. Ini tidak akan mengubah ukuran array yang kembali IsResizable sebagai FALSE.

CComSafeArray::SetAt

Mengatur nilai elemen dalam array dimensi tunggal.

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

Parameter

lIndex
Jumlah indeks elemen array yang akan diatur.

t
Nilai baru elemen yang ditentukan.

bCopy
Menunjukkan apakah salinan data harus dibuat. Nilai defaultnya adalah TRUE.

Nilai hasil

Mengembalikan S_OK keberhasilan, atau kesalahan HRESULT saat gagal.

Keterangan

Bendera bCopy diperhitungkan ketika elemen jenis BSTR atau VARIANT ditambahkan ke array. Nilai TRUE default memastikan bahwa salinan baru terbuat dari data saat elemen ditambahkan ke array.

Lihat juga

SAFEARRAY Tipe Data
CComSafeArray::Create
CComSafeArray::Destroy
Gambaran Umum Kelas