La classe CComSafeArray

Cette classe est un wrapper pour la SAFEARRAY structure.

Syntaxe

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

Paramètres

T
Type de données à stocker dans le tableau.

Membres

Constructeurs publics

Nom	Description
CComSafeArray::CComSafeArray	Constructeur .
CComSafeArray::~CComSafeArray	Destructeur.

Méthodes publiques

Nom	Description
CComSafeArray::Add	Ajoute un ou plusieurs éléments, ou une SAFEARRAY structure, à un CComSafeArray.
CComSafeArray::Attach	Attache une SAFEARRAY structure à un CComSafeArray objet.
CComSafeArray::CopyFrom	Copie le contenu d’une SAFEARRAY structure dans l’objet CComSafeArray .
CComSafeArray::CopyTo	Crée une copie de l'objet CComSafeArray.
CComSafeArray::Create	Crée un objet CComSafeArray.
CComSafeArray::Destroy	Détruit un objet CComSafeArray .
CComSafeArray::Detach	Détache un SAFEARRAY CComSafeArray objet.
CComSafeArray::GetAt	Récupère un élément unique à partir d’un tableau unidimensionnel.
CComSafeArray::GetCount	Retourne le nombre d'éléments du tableau.
CComSafeArray::GetDimensions	Retourne le nombre de dimensions du tableau.
CComSafeArray::GetLowerBound	Retourne la limite inférieure d’une dimension donnée du tableau.
CComSafeArray::GetSafeArrayPtr	Retourne l’adresse du membre de données m_psa .
CComSafeArray::GetType	Retourne le type de données stocké dans le tableau.
CComSafeArray::GetUpperBound	Retourne la limite supérieure d’une dimension du tableau.
CComSafeArray::IsSizable	Teste si un objet CComSafeArray peut être redimensionné.
CComSafeArray::MultiDimGetAt	Récupère un élément unique à partir d’un tableau multidimensionnel.
CComSafeArray::MultiDimSetAt	Définit la valeur d’un élément d’un tableau multidimensionnel.
CComSafeArray::Resize	Redimensionne un objet CComSafeArray .
CComSafeArray::SetAt	Définit la valeur d’un élément d’un tableau unidimensionnel.

Opérateurs publics

Nom	Description
CComSafeArray::operator LPSAFEARRAY	Convertit une valeur en pointeur SAFEARRAY .
CComSafeArray::operator[]	Récupère un élément du tableau.
CComSafeArray::operator =	Opérateur d'assignation.

Membres de données publics

Nom	Description
CComSafeArray::m_psa	Ce membre de données contient l’adresse de la SAFEARRAY structure.

Notes

CComSafeArray fournit un wrapper pour la SAFEARRAY classe de type de données, ce qui permet de créer et de gérer des tableaux multidimensionnels uniques et multidimensionnels de presque tous les types pris en charge VARIANT .

CComSafeArray simplifie le transmission de tableaux entre processus et offre en outre une sécurité renforcée en vérifiant les valeurs d’index de tableau par rapport aux limites inférieure et supérieure.

La limite inférieure d’un CComSafeArray peut commencer à n’importe quelle valeur définie par l’utilisateur ; cependant, les tableaux accessibles via C++ doivent utiliser une limite inférieure de 0. D’autres langages comme Visual Basic peuvent utiliser d’autres valeurs de délimitation (par exemple, de -10 à 10).

Permet CComSafeArray::Create de créer un CComSafeArray objet et CComSafeArray::Destroy de le supprimer.

Un CComSafeArray peut contenir le sous-ensemble suivant de types de VARIANT données :

VARTYPE	Description
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	pointeur décimal
VT_VARIANT	pointeur de type Variant
VT_CY	Currency (type de données)

Spécifications

En-tête : atlsafe.h

Exemple

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

Ajoute un ou plusieurs éléments, ou une SAFEARRAY structure, à un CComSafeArray.

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

Paramètres

psaSrc
Pointeur vers un objet SAFEARRAY.

ulCount
Nombre d’objets à ajouter au tableau.

pT
Pointeur vers un ou plusieurs objets à ajouter au tableau.

t
Référence à l’objet à ajouter au tableau.

bCopy
Indique si une copie des données doit être créée. La valeur par défaut est TRUE.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Les nouveaux objets sont ajoutés à la fin de l’objet existant SAFEARRAY . L’ajout d’un objet à un objet multidimensionnel SAFEARRAY n’est pas pris en charge. Lors de l’ajout d’un tableau d’objets existant, les deux tableaux doivent contenir des éléments du même type.

L’indicateur bCopy est pris en compte lorsque des éléments de type BSTR ou VARIANT sont ajoutés à un tableau. La valeur par défaut garantit TRUE qu’une nouvelle copie est faite des données lorsque l’élément est ajouté au tableau.

CComSafeArray::Attach

Attache une SAFEARRAY structure à un CComSafeArray objet.

HRESULT Attach(const SAFEARRAY* psaSrc);

Paramètres

psaSrc
Pointeur vers la SAFEARRAY structure.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Attache une SAFEARRAY structure à un CComSafeArray objet, rendant les méthodes existantes CComSafeArray disponibles.

CComSafeArray::CComSafeArray

Constructeur .

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

Paramètres

bound
Structure SAFEARRAYBOUND.

ulCount
Nombre d’éléments dans le tableau.

lLBound
Valeur limite inférieure ; autrement dit, l’index du premier élément du tableau.

pBound
Pointeur vers une SAFEARRAYBOUND structure.

uDims
Nombre de dimensions dans le tableau.

saSrc
Référence à une structure ou CComSafeArray à un SAFEARRAY objet. Dans les deux cas, le constructeur utilise cette référence pour effectuer une copie du tableau, de sorte que le tableau n’est pas référencé après la construction.

psaSrc
Pointeur vers une SAFEARRAY structure. Le constructeur utilise cette adresse pour effectuer une copie du tableau, de sorte que le tableau n’est jamais référencé après la construction.

Notes

Crée un objet CComSafeArray.

CComSafeArray::~CComSafeArray

Destructeur.

~CComSafeArray() throw()

Notes

Libère toutes les ressources allouées.

CComSafeArray::CopyFrom

Copie le contenu d’une SAFEARRAY structure dans l’objet CComSafeArray .

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

Paramètres

ppArray
Pointeur vers la SAFEARRAY copie.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Cette méthode copie le contenu d’un SAFEARRAY objet actif CComSafeArray . Le contenu existant du tableau est remplacé.

CComSafeArray::CopyTo

Crée une copie de l'objet CComSafeArray.

HRESULT CopyTo(LPSAFEARRAY* ppArray);

Paramètres

ppArray
Pointeur vers un emplacement dans lequel créer le nouveau SAFEARRAY.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Cette méthode copie le contenu d’un CComSafeArray objet dans une SAFEARRAY structure.

CComSafeArray::Create

Crée un CComSafeArray.

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

Paramètres

pBound
Pointeur vers un objet SAFEARRAYBOUND.

uDims
Nombre de dimensions dans le tableau.

ulCount
Nombre d’éléments dans le tableau.

lLBound
Valeur limite inférieure ; autrement dit, l’index du premier élément du tableau.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Un CComSafeArray objet peut être créé à partir d’une structure existante SAFEARRAYBOUND et du nombre de dimensions, ou en spécifiant le nombre d’éléments dans le tableau et la limite inférieure. Si le tableau est accessible à partir de C++, la limite inférieure doit être 0. D’autres langages peuvent autoriser d’autres valeurs pour la limite inférieure (par exemple, Visual Basic prend en charge les tableaux avec des éléments avec une plage telle que -10 à 10).

CComSafeArray::Destroy

Détruit un objet CComSafeArray .

HRESULT Destroy();

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Détruit un objet existant CComSafeArray et toutes les données qu’il contient.

CComSafeArray::Detach

Détache un SAFEARRAY CComSafeArray objet.

LPSAFEARRAY Detach();

Valeur retournée

Retourne un pointeur vers un SAFEARRAY objet.

Notes

Cette méthode détache l’objet SAFEARRAY de l’objet CComSafeArray .

CComSafeArray::GetAt

Récupère un élément unique à partir d’un tableau unidimensionnel.

T& GetAt(LONG lIndex) const;

Paramètres

lIndex
Numéro d’index de la valeur dans le tableau à retourner.

Valeur retournée

Retourne une référence à l’élément de tableau requis.

CComSafeArray::GetCount

Retourne le nombre d'éléments du tableau.

ULONG GetCount(UINT uDim = 0) const;

Paramètres

uDim
Dimension de tableau.

Valeur retournée

Retourne le nombre d'éléments du tableau.

Notes

Lorsqu’elle est utilisée avec un tableau multidimensionnel, cette méthode retourne le nombre d’éléments dans une dimension spécifique uniquement.

CComSafeArray::GetDimensions

Retourne le nombre de dimensions du tableau.

UINT GetDimensions() const;

Valeur retournée

Retourne le nombre de dimensions du tableau.

CComSafeArray::GetLowerBound

Retourne la limite inférieure d’une dimension donnée du tableau.

LONG GetLowerBound(UINT uDim = 0) const;

Paramètres

uDim
Dimension de tableau pour laquelle obtenir la limite inférieure. S’il est omis, la valeur par défaut est 0.

Valeur retournée

Retourne la limite inférieure.

Notes

Si la limite inférieure est 0, cela indique un tableau de type C dont le premier élément est le numéro d’élément 0. En cas d’erreur, par exemple, un argument de dimension non valide, cette méthode appelle AtlThrow avec une HRESULT description de l’erreur.

CComSafeArray::GetSafeArrayPtr

Retourne l’adresse du membre de données m_psa .

LPSAFEARRAY* GetSafeArrayPtr() throw();

Valeur retournée

Retourne un pointeur vers le membre de CComSafeArray::m_psa données.

CComSafeArray::GetType

Retourne le type de données stocké dans le tableau.

VARTYPE GetType() const;

Valeur retournée

Retourne le type de données stockées dans le tableau, qui peut être l’un des types suivants :

VARTYPE	Description
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	pointeur décimal
VT_VARIANT	pointeur de type Variant
VT_CY	Currency (type de données)

CComSafeArray::GetUpperBound

Retourne la limite supérieure d’une dimension du tableau.

LONG GetUpperBound(UINT uDim = 0) const;

Paramètres

uDim
Dimension de tableau pour laquelle obtenir la limite supérieure. S’il est omis, la valeur par défaut est 0.

Valeur retournée

Retourne la limite supérieure. Cette valeur est inclusive, l’index valide maximal pour cette dimension.

Notes

En cas d’erreur, par exemple, un argument de dimension non valide, cette méthode appelle AtlThrow avec une HRESULT description de l’erreur.

CComSafeArray::IsSizable

Teste si un objet CComSafeArray peut être redimensionné.

bool IsSizable() const;

Valeur retournée

Retourne TRUE si la valeur CComSafeArray peut être redimensionnée, FALSE si elle ne peut pas être redimensionnée.

CComSafeArray::m_psa

Contient l’adresse de la SAFEARRAY structure accessible.

LPSAFEARRAY m_psa;

CComSafeArray::MultiDimGetAt

Récupère un élément unique à partir d’un tableau multidimensionnel.

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

Paramètres

alIndex
Pointeur vers un vecteur d’index pour chaque dimension du tableau. La dimension la plus à gauche (la plus importante) est alIndex[0].

t
Référence aux données retournées.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

CComSafeArray::MultiDimSetAt

Définit la valeur d’un élément d’un tableau multidimensionnel.

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

Paramètres

alIndex
Pointeur vers un vecteur d’index pour chaque dimension du tableau. La dimension la plus à droite (la moins significative) est alIndex[0].

T
Spécifie la valeur du nouvel élément.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Il s’agit d’une version multidimensionnelle de CComSafeArray::SetAt.

CComSafeArray::operator []

Récupère un élément du tableau.

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

Paramètres

lIndex, nIndex
Numéro d’index de l’élément requis dans le tableau.

Valeur retournée

Retourne l’élément de tableau approprié.

Notes

Effectue une fonction similaire à CComSafeArray::GetAt, mais cet opérateur fonctionne uniquement avec des tableaux unidimensionnels.

CComSafeArray::operator =

Opérateur d'assignation.

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

Paramètres

saSrc
Référence à un objet CComSafeArray.

psaSrc
Pointeur vers un objet SAFEARRAY.

Valeur retournée

Retourne le type de données stocké dans le tableau.

CComSafeArray::operator LPSAFEARRAY

Convertit une valeur en pointeur SAFEARRAY .

operator LPSAFEARRAY() const;

Valeur retournée

Convertit une valeur en pointeur SAFEARRAY .

CComSafeArray::Resize

Redimensionne un objet CComSafeArray .

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

Paramètres

pBound
Pointeur vers une SAFEARRAYBOUND structure qui contient des informations sur le nombre d’éléments et la limite inférieure d’un tableau.

ulCount
Nombre demandé d’objets dans le tableau redimensionné.

lLBound
Limite inférieure.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

Cette méthode redimensionne uniquement la dimension la plus à droite. Il ne redimensionne pas les tableaux qui retournent IsResizable en tant que FALSE.

CComSafeArray::SetAt

Définit la valeur d’un élément d’un tableau unidimensionnel.

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

Paramètres

lIndex
Numéro d’index de l’élément de tableau à définir.

t
Nouvelle valeur de l’élément spécifié.

bCopy
Indique si une copie des données doit être créée. La valeur par défaut est TRUE.

Valeur retournée

Retourne S_OK la réussite ou une erreur en cas d’échec HRESULT .

Notes

L’indicateur bCopy est pris en compte lorsque des éléments de type BSTR ou VARIANT sont ajoutés à un tableau. La valeur par défaut garantit TRUE qu’une nouvelle copie est faite des données lorsque l’élément est ajouté au tableau.

Voir aussi

SAFEARRAY Type de données
CComSafeArray::Create
CComSafeArray::Destroy
Vue d’ensemble de la classe