Fournit l'accès à une table de données. Elle est utilisée pour accéder aux Rendez-vous (
Appointments), Contacts, Tâches (
Tasks), Messages et à d'autres données.
La classe
DataTable est extrêmement importante. Elle fournit une structure générique pour beaucoup de tables de données qui proviennent de l'appareil comme les rendez-vous, les contacts, les tâches, les messages, les applications actives et même des documents XML. Plutôt que d'utiliser un moyen d'accès spécifique à chacun de ces types de données, nous avons décidé de créer une classe DataTable permettant d'en uniformiser l'accès. Il est important que vous deveniez familier avec l'usage d'objets de type DataTable car la plupart des choses dont vous avez besoin les utilisent.
Une DataTable contient de 0 à n lignes (
rows). Chaque ligne peut représenter une entité (comme un rendez-vous ou un contact,), une ligne contenant les détails d'une seule entité. Étant donné que votre calendrier contient plusieurs rendez-vous, cela signifie que la DataTable contiendra beaucoup de lignes, une ligne par rendez-vous.
Chaque ligne contient une ou plusieurs colonnes (
columns). Une colonne correspond à une information rattachée à l'entité représentée par la ligne. Par exemple, si une ligne correspond à un rendez-vous, elle contiendra alors les colonnes «Objet», « Début », « Fin », « Fréquence », etc. Mais si une ligne correspond à un message elle contiendra alors les colonnes « Sujet », « Destinataire », « Est lu », etc.
La plupart des types de données contenus dans des objets DataTable supportent uniquement une navigation séquentielle dans les lignes de la structure. Pour être plus précis, l'accès aléatoire à une ligne n'est pas supporté. Habituellement, une DataTable est initialisée et exploitée jusqu'à la ligne finale comme le montre l'exemple suivant :
DataTable rendezvous;
//Alimentation de la table avec tous les rendez-vous
Appointments.GetAppointments(rendezvous);
//Boucle pour parcourir la table des rendez-vous
while (rendezvous.MoveNext())
{
//faire quelque chose avec ce rendez-vous
DateTime dt;
appts.GetValue(“StartDate”, dt);
}
Certains types de données autorisent l'instruction
MoveTo(index) pour un accès ciblé à une occurrence. Dans ce cas, la documentation le précise.
Une liste entière d'élément est généralement requise pour une DataTable et cette liste est alors restreinte en utilisant
SetRestriction() à partir d'une requête si nécessaire. Il n'est pas plus performant de requêter toute la table et de la restreindre étant donné que la restriction effectue une tentative pour parcourir la DataTable en utilisant
MoveNext() etc.
Le nombre de lignes d'une DataTable peut être limité en utilisant
SetMaxItems().
Méthodes
bool MoveNext()
Lit la ligne suivante dans la table.
Remarque importante : Il est impératif d'utiliser au moins une fois cette méthode avant de pouvoir récupérer la première ligne avec la méthode
GetValue() (voir exemple ci-dessous).
Valeur retournée
Retourne
true si la ligne suivante existe et a été lue avec succès. Si une valeur
true est retournée, un
GetValue() peut être alors utilisé pour récupérer les valeurs de la ligne. Si plus aucune ligne n'existe dans la table, la valeur
false est retournée.
Compatibilité
- Supporté pour toute table de données.
Exemple
DataTable rendezvous;
// Récupération de tous les rendez-vous
Appointments.GetAppointments(rendezvous);
//lecture de tous les rendez-vous
//remarquez que MoveNext est appeler avant d'accéder aux valeurs de la première ligne
while (rendezvous.MoveNext())
{
//récupération de la date et l'heure de début du rendez-vous lu
DateTime debut;
appts.GetValue("StartDate", debut);
}
bool MoveTo(int index)
Accède à une ligne spécifique dans la table.
Valeur retournée
- Retourne
true si la ligne suivante existe et a été lue avec succès. Si une valeur true est retournée, un GetValue() peut être alors utilisé pour récupérer les valeurs de la ligne. Si plus aucune ligne n'existe dans la table, la valeur false est retournée.
Compatibilité
- Uniquement supporté pour les tables de données retournées par :
void GetValue(String columnName, Strign result)
void GetValue(String columnName, int result)
void GetValue(String columnName, DateTime result)
Délivre la valeur de la colonne spécifiée et copie sa valeur dans le paramètre résultat. Cela permet de récupérer les valeurs des colonnes de la ligne courante.
Paramètres
- columnName nom de la colonne dont la valeur doit être retournée (sensible à la casse)
- result valeur retournée qui est le contenu de la colonne. Le type de variable déclaré doit correspondre au type de valeur demandé.
Compatibilité
- Supporté pour toute table de données.
Exemple
DataTable rendezvous;
Appointments.GetAppointments(rendezvous);
while (rendezvous .MoveNext())
{
//récupération de la date et heure de début du rendez-vous
DateTime rvDebut;
rendezvous.GetValue(“StartDate”, rvDebut);
//récupération de l'objet du rendez-vous
String rvObjet;
rendezvous.GetValue(“Subject”, rvObjet);
}
void SetColumns(String columns)
Définit les colonnes qui sont retournée dans la table. Seules les colonnes spécifiées peuvent être accédées par GetValue() pour les tables de données qui comportent des colonnes spéicifiques. Voir la compatibilité ci-dessous.
Paramètre
- columns contient une liste de noms de colonnes séparés par des vrigules. Ces colonnes seront ajoutées dans la table lors de sa préparation.
Compatibilité
- Uniquement supporté pour les tables de données retournées par :
Exemple
DataTable rendezvous;
Appointments.GetAppointments(rendezvous);
while (rendezvous .MoveNext())
{
//récupération de la date et heure de début du rendez-vous
DateTime rvDebut;
rendezvous.GetValue(“StartDate”, rvDebut);
//récupération de l'objet du rendez-vous
String rvObjet;
rendezvous.GetValue(“Subject”, rvObjet);
}
void SetSort(String columnName, String sortDirection)
Définit le nom de colonne à trier ainsi que le sens du tri.
Paramètres
- columnName nom de la colonne utilisée comme critère de tri
- sortDirection (optionnel) sens du tri qui peut prendre une des valeurs suivantes :
- "Ascending" tri en ascendant (valeur par défaut si non spécifié)
- "Descending" tri en descendant
Compatibilité
- Uniquement supporté pour les tables de données retournées par :
Appointments.GetAppointments()Contacts.GetContacts()Messages.GetMessages()Tasks.GetTasks()
void SetRestriction(String query)
Restreint la table afin qu'elle ne contienne que les lignes correspondant à la requête fournie en paramètre.
Paramètre
- query requête à appliquer à la table pour limiter les lignes retournées.
Le format de la requête peut être différent selon le type de données contenu de la table.
Exemple
//récupération des rendez-vous
DataTable rendezvous;
Appointments.GetAppointments(rendezvous);
//ne pas retourner plus de 4 éléments
rendezvous.SetMaxItems(4);
//Tri des de la table sur la date et heure de début
rendezvous.SetSort("Start");
//élaboration d'une requête qui sera utilisé pour filtrer les rendez-vous
String filtre;
filtre = "End >= <{Now} AND Start < <{End}";
//récupération de la date et heure courante
DateTime aujourdhui;
aujourdhui.Now();
//conversion de l'heure courante au format attendu par POOM
String tmp;
float f;
f = aujourdhui.ToVariantTime();
tmp = f.ToString("%.5f");
filtre = filtre.Replace("{Now}", tmp);
//récupération de l'heure de début du jour suivant
aujourdhui.AddDays(1);
f = aujourdhui.ToVariantTime();
f.Trunc();
tmp = f.ToString("%.0f");
filtre = filtre.Replace("{End}", tmp);
//application de la restriction (avec le filtre)
rendezvous.SetRestriction(filtre);
//faire quelque chose avec les rendez-vous obtenus
while (rendezvous .MoveNext())
{
//…
}
void SetMaxitems(int maxItems)
Définit le nombre maximum d'éléments de la table à retourner même si elle en contient plus.
Paramètres
- maxItems nombre maximum d'éléments à retourner
Compatibilité
- Supporté pour toute table de données.
int GetCount()
Retourne le nombre de lignes contenues dans la table.
Compatibilité
- Uniquement supporté pour les tables de données retournées par :
Process.GetRunningApplications()