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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour