WinLog : une bibliothèque de génération de messages de trace

ram-0000

Ce document a pour but de présenter l'implémentation de la bibliothèque WinLog capable de générer des messages de trace de manière générique. Cette bibliothèque devrait être utilisée dès le début de la réalisation d'un projet. Ce document contient la spécification des fonctions et interfaces de cette bibliothèque ainsi que le code source permettant de la générer.

Votre avis et vos suggestions sur ce tutoriel m'intéressent ! Alors après votre lecture, n'hésitez pas : Commentez ♪

- Titre : WinLog : une bibliothèque de génération de messages de trace

- Auteur : ram-0000

- Parution : 8 février 2009

- Mise à jour : 13 juin 2011

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2008-2010 ram-0000. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts. Droits de diffusion permanents accordés à Developpez LLC.

Sommaire

- 1. Introduction

- 1-1. Avant-propos

- 1-2. But de ce document

- 1-3. Historique des versions

- 2. Format des messages de trace

- 2-1. Niveau de fonctionnalité

- 2-2. Type des messages de trace

- 2-3. Format des messages de trace

- 3. Implémentation de la bibliothèque WinLog

- 3-1. Format de la bibliothèque

- 3-2. Autres choix techniques

- 3-3. Les formats de sortie disponibles

- 3-4. Modification du comportement

- 3-5. Fichiers livrés

- 3-6. Format de la DLL

- 4. L'interface avec WinLog

- 4-1. Les types prédéfinis de WinLog

- 4-1-1. Le type WinLogRet_t

- 4-1-2. Le type WinLogType_t

- 4-1-3. Le type WinLogCallBack_Info_t

- 4-1-4. Le type WinLogCallBack_t

- 4-2. Les fonctions d'initialisation

- 4-3. Les fonctions de sélection des niveaux de fonctionnalités

- 4-4. Les fonctions des méthodes de sortie

- 4-4-1. Les fonctions de la méthode File

- 4-4-2. Les fonctions de la méthode Output

- 4-4-3. Les fonctions de la méthode Debug

- 4-4-4. Les fonctions de la méthode Callback

- 4-4-5. Les fonctions de la méthode PostSend Message

- 4-4-6. Les fonctions de la méthode Pipe

- 4-4-7. Les fonctions de la méthode Syslog

- 4-5. Les fonctions de génération de messages

- 4-6. Les fonctions annexes

- 4-7. Les macros de WinLog

- 4-8. Les variables d'environnement

- 4-9. Fonctionnement par défaut

- 4-9-1. La méthode File

- 4-9-2. La méthode Output

- 4-9-3. La méthode Debug

- 4-9-4. La méthode Callback

- 4-9-5. La méthode PostSend Message

- 4-9-6. La méthode Pipe

- 4-9-7. La méthode Syslog

- 4-9-8. Le niveau de fonctionnalité

- 5. Exemple d'utilisation

- 6. Conclusion

1 - Introduction

1-1 - Avant-propos

La capacité d'un programme à générer des messages de trace est une chose importante dans le cycle de vie d'une application. Cette capacité est utile lors du développement de l'application en phase de tests unitaires et surtout durant la phase des tests d'intégration et de validation. Elle permet aussi lorsqu'elle est déployée chez le client final de remonter les informations nécessaires pour le traitement d'un problème ou d'un bug.

1-2 - But de ce document

Lors de la réalisation de mes différents projets, j'ai toujours été confronté au problème de la génération de messages de trace :

- Quel format de sortie utiliser ?

- Existe-t-il un composant que je pourrais réutiliser ?

- Est-ce que ce que je veux faire dans ce projet est compatible avec les fonctionnalités de ce composant existant ?

Ne trouvant pas de solution correspondant à mes besoins, je me suis lancé dans la réalisation d'une bibliothèque de génération des messages de trace.

Ce document a pour but de présenter l'implémentation d'une bibliothèque capable de générer des messages de trace de manière générique. Cette bibliothèque devrait être utilisée dès le début de la réalisation d'un projet. Ce document contient donc la spécification des fonctions et interfaces de cette bibliothèque ainsi que le code source permettant de la générer.

1-3 - Historique des versions

Version 1.2 du 13 juin 2011

- Les champs date et heure des messages peuvent être en heure UTC ou bien en heure locale. Ajout des fonctions WinLogSetUtcTime() et WinLogSetLocalTime().

Version 1.1 du 6 décembre 2010

- Le champ DateTime de la structure WinLogCallBack_Info_t est maintenant un long long (64 bits) et non plus un long (32 bits).

- Portage de la bibliothèque en 32 bits et en 64 bits.

Version 1.0 du 9 février 2009

- Première version.

2 - Format des messages de trace

2-1 - Niveau de fonctionnalité

WinLog permet de gérer des messages de trace avec la notion de niveau de fonctionnalités.

Il existe 33 niveaux différents qui vont du niveau 0 au niveau 32. Le niveau 0 est toujours affiché alors que les niveaux 1 à 32 peuvent être individuellement affichés ou non affichés.

Ces niveaux de fonctionnalités sont à la libre disposition du développeur afin de lui laisser la possibilité d'organiser ses messages de trace (par exemple les messages de trace de la bibliothèque de gestion des E/S, les messages de trace de gestion de l'interface utilisateur, les messages de trace de gestion des objets systèmes…).

2-2 - Type des messages de trace

Chaque message de trace généré possède un type fixé par le développeur de l'application qui utilise la bibliothèque WinLog. Les types existants sont les suivants :

- Info. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'information pour, par exemple, indiquer le déroulement d'un processus.

- User. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace utilisateur un petit peu plus important que le message précédent pour, par exemple, indiquer un point précis du déroulement d'un processus.

- Warning. Dans l'esprit de la bibliothèque, il s'agit d'un petit message de trace d'attention que le programme peut gérer tout seul. Par exemple, une mauvaise saisie de l'utilisateur.

- Error. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'erreur un peu plus grave que le programme peut gérer probablement tout seul. Par exemple, un fichier de configuration inexistant.

- Fatal. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'erreur grave que le programme ne sait peut-être pas gérer correctement. Par exemple, une erreur lors d'une allocation mémoire.

- Dump. Ce type est particulier, il ne correspond pas à une erreur, mais il est utilisé par exemple pour afficher le contenu d'une structure ou d'un bloc de mémoire à des fins d'analyse.

2-3 - Format des messages de trace

Le format des messages de trace est le suivant :

[<Identifiant>:<ProcessName>:<Type>:<UTC Date>:<Process ID>/<Thread ID>:<Level>] <Texte du message>

dans lequel on retrouve :

- Identifiant. Il s'agit d'un identifiant de messages de trace. Ce nombre est géré par la bibliothèque WinLog. Il vaut 0 pour le premier message de trace et est automatiquement incrémenté lors de la génération des messages de trace suivants. Ce nombre permet de voir si des messages de trace ont été perdus.

- ProcessName. Il s'agit du nom du processus qui génère le message de trace. Ce nom est défini par le développeur lors de l'initialisation de la bibliothèque WinLog.

- Type. Il s'agit du type du message de trace (Info, User, Warning, Error, Fatal, Dump). Ce type permet de catégoriser le message de trace en fonction de son niveau d'importance. Le type du message de trace est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.

- UTC Date. Il s'agit de la date UTC de génération du message de trace. Le format utilisé est le format yyyy-mm-dd hh:mm:ss.

- Process ID. Il s'agit de l'identifiant du process qui génère le message de trace. Cette information est particulièrement importante dans le cas où plusieurs instances du programme sont exécutées simultanément.

- Thread ID. Il s'agit de l'identifiant du thread qui génère le message de trace. Cette information est particulièrement importante dans le cas des programmes multi threadés.

- Level. Il s'agit du niveau de fonctionnalité du message de trace. Cette information n'est pas disponible pour les messages de trace de niveau 0 qui sont toujours traités. Le niveau de fonctionnalité est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.

- Texte du message. Il s'agit du message de trace lui-même. Le contenu de ce message de trace est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.

Exemple de messages de trace :

[0:WinAgentLog:Info:2009-01-08 21:51:49:991/2188:00] Stopping the thread 2220 ...
[1:WinAgentLog:Info:2009-01-08 21:51:49:991/2188:00] Waiting for the end of a thread...
[2:WinAgentLog:Info:2009-01-08 21:51:49:991/2220:00] The service 'Phoenix Team WinAgentLog' is stopping
[3:WinAgentLog:Info:2009-01-08 21:51:50:991/2968:00] The thread CThreadEventLogReader is stopping EventLog location Application
[4:WinAgentLog:Info:2009-01-08 21:51:51:991/2972:00] The thread CThreadEventLogReader is stopping EventLog location Internet Explorer

3 - Implémentation de la bibliothèque WinLog

3-1 - Format de la bibliothèque

L'environnement de développement et d'utilisation de la bibliothèque WinLog est l'environnement Microsoft. L'environnement de développement utilisé est Microsoft Visual Studio 2005 sur une machine Windows XP SP3. Lors de la réalisation de WinLog, plusieurs possibilités se sont offertes :

- La réalisation d'une bibliothèque statique.

- La réalisation d'une bibliothèque dynamique (ou DLL).

- La réalisation d'un composant COM.

Le choix pour une DLL a semblé assez naturel dans le sens où il permet le remplacement de la bibliothèque sans avoir besoin de recompiler l'application à condition que l'interface de la bibliothèque n'ait pas changé.

3-2 - Autres choix techniques

WinLog supporte les jeux de caractères Unicode et ANSI.

WinLog peut être appelée aussi bien depuis un programme C que d'un programme C++. Ce choix n'empêche absolument pas cette bibliothèque d'être écrite en C++ ou d'utiliser des composants C++.

3-3 - Les formats de sortie disponibles

Les messages de trace générés par WinLog peuvent être :

- Affichés sur la console de sortie (stdout).

- Enregistrés dans un fichier texte.

- Envoyés dans la fenêtre de débogage de l'environnement de développement.

- Envoyés dans le programme par une fonction de rappel (callback).

- Envoyés dans le programme par message Windows.

- Envoyés dans un tuyau nommé (pipe).

- Envoyés à destination d'un serveur Syslog en utilisant le protocole Syslog.

3-4 - Modification du comportement

Le comportement de WinLog est modifié à l'aide de variables d'environnement afin de ne pas avoir besoin de recompiler l'application pour changer un des paramètres de la bibliothèque.

3-5 - Fichiers livrés

Les fichiers faisant partie de la bibliothèque WinLog sont :

- Le fichier d'en-tête WinLog.h. Ce fichier doit être inclus par tout module ou programme qui doit utiliser les fonctionnalités de la bibliothèque. Ce fichier est autosuffisant, il ne nécessite ni n'inclut d'autres fichiers include. Ce fichier n'est utile que lors de la phase de développement.

- Le fichier librairie WinLog.lib. Ce fichier définit les points d'entrée de la bibliothèque WinLog. Tout programme utilisant les fonctionnalités de la bibliothèque doit se lier avec. Ce fichier n'est utile que lors de la phase de développement.

- Le fichier DLL WinLog.dll. Ce fichier est la bibliothèque dynamique chargée par le système d'exploitation lors du lancement d'un programme utilisant les fonctionnalités de la bibliothèque WinLog. Ce fichier obligatoire pour pouvoir lancer un programme utilisant les fonctionnalités de la bibliothèque WinLog. Il doit être dans le répertoire du binaire qui utilise les fonctionnalités de WinLog ou bien encore dans un des répertoires définis par la variable d'environnement PATH.

Le fichier WinLog.h peut être téléchargé ici.

Le fichier WinLog.lib au format 32 bits peut être téléchargé ici.

Le fichier WinLog.dll au format 32 bits peut être téléchargé ici.

Le fichier WinLog.lib au format 64 bits peut être téléchargé ici.

Le fichier WinLog.dll au format 64 bits peut être téléchargé ici.

Si une erreur se produit lors du lancement du programme utilisant WinLog.dll, il faut installer les redistribuables VS 2005. Ce setup peut être téléchargé ici pour le format 32 bits et ici pour le format 64 bits.

Le projet Visual Studio 2005 complet peut être téléchargé ici.

3-6 - Format de la DLL

Les fichiers WinLog.dll et WinLog.lib ont été construits avec les caractéristiques de compilations suivantes :

- Environnement : 32 bits ou 64 bits (suivant la définition de la macro WIN64).

- Conventions d'appel : __cdecl.

- Mode : multithread.

4 - L'interface avec WinLog

Ce paragraphe présente l'interface avec la bibliothèque WinLog. Toutes ces informations sont issues du fichier WinLog.h qui est le seul et unique fichier d'interface de la bibliothèque.

4-1 - Les types prédéfinis de WinLog

Ce paragraphe présente les différents types de données spécifiques à la bibliothèque WinLog.

4-1-1 - Le type WinLogRet_t

Ce type est l'énumération des différents codes d'erreur retournés par les différentes fonctions. Les valeurs prises par ce type sont les suivantes :

- WINLOG_OK. Il n'y a pas d'erreur.

- WINLOG_NULLPTR. La fonction appelée a reçu un pointeur NUL ou alors une chaine de caractères vide.

- WINLOG_ALREADY_REGISTER. La bibliothèque WinLog est déjà initialisée.

- WINLOG_NOT_REGISTER. La bibliothèque WinLog n'est pas initialisée.

- WINLOG_TRANSLATE_UTF8. Il y a eu une erreur lors de la transformation d'une chaine de caractères ANSI vers UNICODE.

- WINLOG_BAD_FOLDER_NAME. Le nom de répertoire indiqué n'est pas bon.

- WINLOG_REENTRANCY. Une condition de réentrance a été détectée. Ce type d'erreur se produit typiquement lorsque la fonction d'affichage d'un message de trace est rappelée une nouvelle fois par une fonction de callback ou de message Windows lors du traitement d'un précédent message de trace. Cette condition particulière de réentrance peut amener un problème de stack overflow.

4-1-2 - Le type WinLogType_t

Ce type est l'énumération des différents types de messages de trace. Les différentes valeurs peuvent être :

- WinLog_Info : Il s'agit d'un message de trace d'information pour, par exemple, indiquer le déroulement d'un processus.

- WinLog_User : Il s'agit d'un message de trace utilisateur un petit peu plus important que le message précédent pour, par exemple, indiquer un point précis du déroulement d'un processus.

- WinLog_Warning : Il s'agit d'un petit message de trace d'attention que le programme peut gérer tout seul. Par exemple, une mauvaise saisie de l'utilisateur.

- WinLog_Error : Il s'agit d'un message de trace d'erreur un peu plus grave que le programme peut gérer probablement tout seul. Par exemple, un fichier de configuration inexistant.

- WinLog_Fatal : Il s'agit d'un message de trace d'erreur grave que le programme ne sait peut-être pas gérer correctement. Par exemple, une erreur lors d'une allocation mémoire.

- WinLog_Dump : Il ne correspond pas à une erreur, mais il est utilisé par exemple pour afficher le contenu d'une structure ou d'un bloc de mémoire à des fins d'analyse.

4-1-3 - Le type WinLogCallBack_Info_t

Ce type est le format d'une structure reçue par le programme lors des notifications par les méthodes Callback et PostSend Message.

Le format de cette structure est le suivant :

typedef struct
{    unsigned long       MesgIdentifier;
const wchar_t   *   ProcessName;
WinLogType_t        Type;
unsigned long       Level;
long long           DateTime;
unsigned long       ProcessIdentifier;
unsigned long       ThreadIdentifier;
wchar_t         *   Header;
wchar_t         *   Message;
} WinLogCallBack_Info_t;

Ces structures sont allouées de manière dynamique par la bibliothèque WinLog. Elles doivent être explicitement libérées par un appel à la fonction WinLogReleaseInfo() une fois qu'elles ne sont plus nécessaires.

Les différents champs de cette structure sont :

- Le champ MesgIdentifier. C'est le numéro du message de trace. Ce numéro est géré par la bibliothèque WinLog et incrémenté au fur et à mesure que des messages de trace sont générés.

- Le champ ProcessName : C'est le nom du processus, tel qu'il a été enregistré par la fonction WinLogRegister(), qui génère le message de trace.

- Le champ Type : C'est le type du message de trace. Les valeurs possibles sont WinLog_Info, WinLog_User, WinLog_Warning, WinLog_Error, WinLog_Fatal, WinLog_Dump.

- Le champ Level : C'est le niveau de fonctionnalité du message de trace. La valeur de ce niveau de fonctionnalité peut varier entre 0 et 32.

- Le champ DateTime : C'est la date et l'heure de génération du message de trace. Cette valeur correspond au nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00. Cette valeur correspond au format de date standard time_t. Le type time_t n'a pas été utilisé dans cette structure pour éviter les problèmes de portabilité (certaines machines ou OS ont un format time_t sur 64 bits et d'autres sur 32 bits).

- Le champ ProcessIdentifier : C'est le numéro de processus qui génère le message de trace. Cette information est particulièrement utile lorsque plusieurs instances du même programme sont exécutées simultanément.

- Le champ ThreadIdentifier : C'est le numéro de thread qui génère le message de trace. Cette information est particulièrement utile pour les programmes multi threads.

- Le champ Header : c'est le texte de l'en-tête du message de trace.

- Le champ Message : c'est le texte du message de trace.

4-1-4 - Le type WinLogCallBack_t

Ce type est un pointeur de fonction de traitement de la méthode Callback.

typedef void (*WinLogCallBack_t)(WinLogCallBack_Info_t * CallbackInfo);

Cette fonction ne retourne pas de valeur et reçoit comme paramètre un pointeur sur une structure WinLogCallBack_Info_t.

4-2 - Les fonctions d'initialisation

Les fonctions d'initialisation permettent comme leur nom l'indique de démarrer ou bien d'arrêter l'utilisation de la bibliothèque WinLog.

WinLogRegister( )

La fonction WinLogRegister() permet d'initialiser l'utilisation de la bibliothèque WinLog. Tant que cet appel n'est pas effectué, l'utilisation des fonctions WinLog(), WinLogDump(), WinLogDumpParam() et WinLogUnregister() échoue. L'appel à cette fonction doit donc être effectué le plus tôt possible dans le programme.

Syntaxe

WinLogRet_t WinLogRegisterA ( const char * ProcessName );

WinLogRet_t WinLogRegisterW ( const wchar_t * ProcessName );

Paramètres

[in] ProcessName : C'est le nom du processus tel qu'il apparait ensuite dans le message de trace. Ce nom sert aussi à construire le nom du fichier texte dans lequel sont écrits les messages de trace (si cette fonctionnalité est activée).

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogRegisterW() et une version ANSI WinLogRegisterA(). Il existe aussi une macro WinLogRegister qui permet de choisir automatiquement la bonne fonction.

WinLogUnregister( )

La fonction WinLogUnregister() permet d'arrêter l'utilisation de la bibliothèque WinLog et de libérer les ressources utilisées par celle-ci. L'appel à cette fonction doit être effectué le plus tard possible dans le programme. Une fois que cet appel est effectué, l'utilisation des fonctions WinLog(), WinLogDump(), WinLogDumpParam() et WinLogUnregister() devient impossible.

Syntaxe

WinLogRet_t WinLogUnregister ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

4-3 - Les fonctions de sélection des niveaux de fonctionnalités

WinLogSetFeatureLevel( )

La fonction WinLogSetFeatureLevel() permet de sélectionner le niveau de fonctionnalité à afficher. Le niveau de fonctionnalité à afficher correspond à un masque de bits. Si le bit est positionné, le niveau de fonctionnalité correspondant est affiché, dans le cas contraire, il n'est pas affiché. Le niveau de fonctionnalité 0 est toujours affiché, il ne peut être désactivé.

Syntaxe

WinLogRet_t WinLogSetFeatureLevel ( const unsigned long FeatureLevel );

Paramètres

[in] FeatureLevel : Le masque de bits correspondant au niveau de fonctionnalité à afficher. La valeur de ce paramètre peut être un ou logique des différentes constantes définie à cet effet WINLOG_LEVEL_01 à WINLOG_LEVEL_32.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, tous les niveaux de fonctionnalités sont désactivés (sauf le niveau 0 qui ne peut être désactivé).

4-4 - Les fonctions des méthodes de sortie

Ces fonctions permettent de spécifier le fonctionnement des modes de sortie des messages de trace. Les différents modes de sortie sont :

- Méthode File. Cette méthode permet d'écrire les messages de trace dans un fichier de sortie.

- Méthode Output. Cette méthode permet d'écrire les messages de trace dans le flux standard de la console (stdout).

- Méthode Debug. Cette méthode permet d'écrire les messages de trace dans la fenêtre de visualisation des messages du débogueur.

- Méthode Callback. Cette méthode permet d'envoyer les messages de trace dans une fonction de notification du processus (fonction de callback).

- Méthode PostSend Message. Cette méthode permet d'envoyer les messages de trace en utilisant les fonctions d'envoi de messages Windows (fonctions PostMessage ou SendMessage).

- Méthode Pipe. Cette méthode permet d'envoyer les messages de trace dans un pipe nommé.

- Méthode Syslog. Cette méthode permet d'envoyer les messages de trace dans un socket à destination d'un serveur Syslog.

4-4-1 - Les fonctions de la méthode File

Cette méthode permet de sauvegarder les messages de trace dans un fichier d'archivage. Cette fonctionnalité est équipée d'un système de rotation automatique des fichiers générés. Lorsque la taille du fichier d'archivage courant atteint une certaine valeur limite, une rotation automatique des fichiers est effectuée et un nouveau fichier est créé.

WinLogFileSetFolderName( )

La fonction WinLogFileSetFolderName() permet de spécifier le nom du répertoire dans lequel est créé le fichier d'archivage.

Syntaxe

WinLogRet_t WinLogFileSetFolderNameA ( const char * FolderName );

WinLogRet_t WinLogFileSetFolderNameW ( const wchar_t * FolderName );

Paramètres

[in] FolderName : Le nom du répertoire dans lequel est créé le fichier d'archivage.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogFileSetFolderNameW() et une version ANSI WinLogFileSetFolderNameA().

Il existe aussi une macro WinLogFileSetFolderName qui permet de choisir automatiquement la bonne fonction. Par défaut, le répertoire dans lequel est généré le fichier d'archivage est c:\.

WinLogFileSetSizeMax( )

La fonction WinLogFileSetSizeMax() permet de spécifier la taille maximum du fichier d'archivage. Lorsque cette taille est atteinte, une rotation automatique des fichiers est effectuée et un nouveau fichier est créé.

Syntaxe

WinLogRet_t WinLogFileSetSizeMax ( const unsigned long MaxSize );

Paramètres

[in] MaxSize : La taille maximum du fichier d'archivage. Au-delà de cette taille, une rotation automatique des fichiers d'archivage est effectuée et un nouveau fichier est créé.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la taille maximum du fichier d'archivage est fixée à 10 000 000 octets (10 Mo).

WinLogFileSetHistorySize( )

La fonction WinLogFileSetHistoryMax() permet de spécifier le nombre de fichiers d'archivage à conserver lors de la rotation des fichiers d'archivage.

Syntaxe

WinLogRet_t WinLogFileSetHistorySize ( const unsigned long HistorySize );

Paramètres

[in] HistorySize : Le nombre de fichiers à conserver dans l'historique.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, le nombre de fichiers conservés lors de la rotation est 10.

WinLogFileEnable( )

La fonction WinLogFileEnable() permet d'activer la fonctionnalité de sauvegarde des messages de trace dans un fichier d'archivage.

Syntaxe

WinLogRet_t WinLogFileEnable( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité de sauvegarde des messages de trace est activée.

WinLogFileDisable( )

La fonction WinLogFileDisable() permet de désactiver la fonctionnalité de sauvegarde des messages de trace dans un fichier d'archivage.

Syntaxe

WinLogRet_t WinLogFileDisable( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité de sauvegarde des messages de trace est activée.

4-4-2 - Les fonctions de la méthode Output

Cette méthode permet d'écrire les messages de trace générés dans la console standard (flux stdout).

WinLogOutputEnable( )

La fonction WinLogOutputEnable() permet d'activer la fonctionnalité d'écriture des messages de trace générés dans la console standard (flux stdout).

Syntaxe

WinLogRet_t WinLogOutputEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'écriture des messages de trace dans la console standard (flux stdout) est activée.

WinLogOutputDisable( )

La fonction WinLogOutputDisable() permet de désactiver la fonctionnalité d'écriture des messages de trace générés dans la console standard (flux stdout).

Syntaxe

WinLogRet_t WinLogOutputEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'écriture des messages de trace dans la console standard (flux stdout) est activée.

4-4-3 - Les fonctions de la méthode Debug

Cette méthode permet d'envoyer les messages de trace générés dans la fenêtre de visualisation des traces du débogueur si un débogueur est présent.

WinLogDebugEnable( )

La fonction WinLogDebugDisable() permet d'activer la fonctionnalité d'envoi des messages de trace générés dans la fenêtre de visualisation des traces du débogueur.

Syntaxe

WinLogRet_t WinLogDebugEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi des messages de trace dans la fenêtre de visualisation des traces du débogueur est désactivée.

WinLogDebugDisable( )

La fonction WinLogDebugDisable() permet de désactiver la fonctionnalité d'envoi des messages de trace générés dans la fenêtre de visualisation des traces du débogueur.

Syntaxe

WinLogRet_t WinLogDebugDisable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi des messages de trace dans la fenêtre de visualisation des traces du débogueur est désactivée.

4-4-4 - Les fonctions de la méthode Callback

Cette méthode permet de rappeler une fonction du processus en lui fournissant en paramètre le message de trace généré.

WinLogCallbackEnable( )

La fonction WinLogCallbackEnable() permet d'activer la fonctionnalité de rappel de fonction (callback).

Syntaxe

WinLogRet_t WinLogCallbackEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité de rappel de fonction (callback) est désactivée.

WinLogCallbackDisable( )

La fonction WinLogCallbackDisable() permet de désactiver la fonctionnalité de rappel de fonction (callback).

Syntaxe

WinLogRet_t WinLogCallbackDisable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité de rappel de fonction (callback) est désactivée.

WinLogCallbackSet( )

La fonction WinLogCallbackSet() permet d'indiquer la fonction à rappeler (callback) lors de la génération d'un message de trace.

Syntaxe

WinLogRet_t WinLogCallbackSet ( const WinLogCallBack_t Callback );

Paramètres

[in] Callback : La fonction de callback à rappeler lors de la génération d'un message de trace.

La fonction de callback est une fonction du type WinLogCallBack_t qui ne retourne pas de valeur et qui reçoit en paramètre un pointeur sur une structure du type WinLogCallBack_Info_t. Cette structure doit être libérée par un appel à la fonction WinLogReleaseInfo().

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, aucune fonction de rappel n'est positionnée.

WinLogCallbackClear( )

La fonction WinLogCallbackClear() permet d'invalider la fonction à rappeler (callback) lors de la génération d'un message de trace.

Syntaxe

WinLogRet_t WinLogCallbackClear ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

L'appel à WinLogCallbackClear() est équivalent WinLogCallbackSet(NULL).

4-4-5 - Les fonctions de la méthode PostSend Message

Cette méthode permet d'envoyer un message Windows (PostMessage ou SendMessage) à une fenêtre en lui fournissant en paramètre le message de trace.

WinLogPostSendMessageEnable( )

La fonction WinLogPostSendMessageEnable () permet d'activer la fonctionnalité d'envoi de messages Windows à une fenêtre lors du traitement d'un message de trace.

Syntaxe

WinLogRet_t WinLogPostSendMessageEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages Windows à une fenêtre est désactivée.

WinLogPostSendMessageDisable( )

La fonction WinLogPostSendMessageDisable() permet de désactiver la fonctionnalité d'envoi de messages Windows à une fenêtre.

Syntaxe

WinLogRet_t WinLogPostSendMessageDisable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages Windows à une fenêtre est désactivée.

WinLogPostSendMessageSet( )

La fonction WinLogPostSendMessageSet() permet de spécifier le fonctionnement de la fonctionnalité d'envoi de messages Windows à une fenêtre en indiquant le handle de la fenêtre en question, le message à envoyer, la valeur d'un paramètre supplémentaire et la méthode à utiliser (PostMessage ou SendMessage).

La fonction de traitement du message Windows reçoit dans le paramètre lParam un pointeur sur une structure du type WinLogCallBack_Info_t. Cette structure doit être libérée par un appel à la fonction WinLogReleaseInfo().

Syntaxe

WinLogRet_t WinLogPostSendMessageSet ( const unsigned long long int hWnd, const unsigned long long int message, const unsigned long long int wParam, const int UseSendMessage );

Paramètres

[in] hWnd : Le handle Windows de la fenêtre à qui envoyer le message Windows.

[in] message : La valeur du message Windows. Cette valeur correspond au paramètre Msg des fonctions PostMessage() ou SendMessage().

[in] wParam : La valeur du paramètre wParam. Cette valeur correspond au paramètre wParam des fonctions PostMessage() ou SendMessage().

[in] UseSendMessage : Un indicateur spécifiant s’il faut utiliser la fonction PostMessage() ou SendMessage(). Si la valeur vaut 0, la fonction PostMessage() sera utilisée sinon, c'est la fonction SendMessage() qui sera utilisée.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Les paramètres « hWnd », « message » et « wParam » sont reçus dans une valeur de type « unsigned long long int » de 64 bits afin de s'affranchir des problèmes de portage 64 bits.

WinLogPostSendMessageClear( )

La fonction WinLogPostSendMessageClear() permet d'invalider les paramètres de la fonctionnalité d'envoi de messages Windows à une fenêtre.

Syntaxe

WinLogRet_t WinLogPostSendMessageClear ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

4-4-6 - Les fonctions de la méthode Pipe

Cette fonctionnalité permet d'envoyer le message de trace dans un pipe nommé. Lors de l'envoi, les valeurs suivantes sont envoyées dans le pipe :

- <longueur totale> : c’est la longueur du header et la longueur du message codés sur 4 octets non signés.

- <longueur header> : c'est la longueur du header codée sur 4 octets non signés.

- <texte header> : c'est le texte du header.

- <longueur message> : C'est la longueur du message codée sur 4 octets non signés.

- <texte message> : c'est le texte du message.

WinLogPipeSetName( )

La fonction WinLogPipeSetName() permet de spécifier le nom du pipe nommé à utiliser pour l'envoi des messages de trace.

Syntaxe

WinLogRet_t WinLogPipeSetNameA ( const char * PipeName );

WinLogRet_t WinLogPipeSetNameW ( const wchar_t * PipeName );

Paramètres

[in] PipeName : Le nom du pipe nommé à utiliser.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogPipeSetNameW() et une version ANSI WinLogPipeSetNameA(). Il existe aussi une macro WinLogPipeSetName qui permet de choisir automatiquement la bonne fonction.

Par défaut, le nom du pipe nommé est « \\.\pipe\WinLog_pipe ».

WinLogPipeEnable( )

La fonction WinLogPipeEnable() permet d'activer la fonctionnalité d'envoi de messages de trace dans un pipe nommé.

Syntaxe

WinLogRet_t WinLogPipeEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages de trace dans un pipe nommé est désactivée.

WinLogPipeDisable( )

La fonction WinLogPipeDisable() permet de désactiver la fonctionnalité d'envoi de messages de trace dans un pipe nommé.

Syntaxe

WinLogRet_t WinLogPipeDisable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages de trace dans un pipe nommé est désactivée.

4-4-7 - Les fonctions de la méthode Syslog

Cette fonctionnalité permet d'envoyer le message de trace sur le réseau en utilisant le protocole Syslog à destination d'un serveur Syslog.

Lors de l'envoi de messages Syslog, la sévérité Syslog utilisée est sélectionnée en fonction du type du message de trace :

- WinLog_Dump : sévérité Debug (valeur 7).

- WinLog_Info : sévérité Informational (valeur 6).

- WinLog_User : sévérité Notice (valeur 5).

- WinLog_Warning : sévérité Warning (valeur 4).

- WinLog_Error : sévérité Error (valeur 3).

- WinLog_Fatal : sévérité Critical (valeur 2).

WinLogSyslogSetRemoteServer( )

La fonction WinLogSyslogSetRemoteServer() permet de spécifier l'adresse IP du serveur Syslog vers qui envoyer les messages Syslog.

Syntaxe

WinLogRet_t WinLogSyslogSetRemoteServerA ( const char * DottedRemoteIpAddress );

WinLogRet_t WinLogSyslogSetRemoteServerW ( const wchar_t * DottedRemoteIpAddress );

Paramètres

[in] DottedRemoteIpAddress : L'adresse IP du serveur Syslog à qui envoyer les messages Syslog.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogSyslogSetRemoteServerW() et une version ANSI WinLogSyslogSetRemoteServerA(). Il existe aussi une macro WinLogSyslogSetRemoteServer qui permet de choisir automatiquement la bonne fonction.

WinLogSyslogSetRemotePort( )

La fonction WinLogSyslogSetRemotePort() permet de spécifier le port UDP destination du serveur Syslog vers qui envoyer les messages Syslog.

Syntaxe

WinLogRet_t WinLogSyslogSetRemotePort ( const unsigned long RemotePort );

Paramètres

[in] RemotePort : Le numéro de port du serveur Syslog à qui envoyer les messages Syslog. Le numéro de port ne doit pas être plus grand que 65535.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, cette valeur est fixée à 514, le numéro de port par défaut du protocole Syslog.

WinLogSyslogSetFacility( )

La fonction WinLogSyslogSetFacility() permet de spécifier le numéro de facilité à utiliser lors de l'envoi des messages Syslog au serveur Syslog.

Syntaxe

WinLogRet_t WinLogSyslogSetFacility ( const unsigned long Facility );

Paramètres

[in] Facility : Le numéro de facilité à utiliser. La valeur de la facilité ne doit pas être plus grande que 23.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, le numéro de facilité est fixé à 23 (facilité local use 7).

WinLogSyslogEnable( )

La fonction WinLogSyslogEnable() permet d'activer la fonctionnalité d'envoi de messages de trace à destination d'un serveur Syslog.

Syntaxe

WinLogRet_t WinLogSyslogEnable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages de trace à destination d'un serveur Syslog est désactivée.

WinLogSyslogDisable( )

La fonction WinLogSyslogDisable() permet de désactiver la fonctionnalité d'envoi de messages de trace à destination d'un serveur Syslog.

Syntaxe

WinLogRet_t WinLogSyslogDisable ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la fonctionnalité d'envoi de messages de trace à destination d'un serveur Syslog est désactivée.

4-5 - Les fonctions de génération de messages

WinLog( )

La fonction WinLog() permet de générer un message de trace.

Syntaxe

WinLogRet_t WinLogA ( const WinLogType_t Event, const unsigned long FeatureLevel, const char * Format… );

WinLogRet_t WinLogW ( const WinLogType_t Event, const unsigned long FeatureLevel, const wchar_t * Format… );

Paramètres

[in] Event : Ce paramètre permet de spécifier le niveau du message de trace. Les valeurs possibles sont WinLog_Info , WinLog_User, WinLog_Warning, WinLog_Error, WinLog_Fatal, WinLog_Dump.

[in] FeatureLevel : Ce paramètre est un nombre de 0 à 32 qui permet d'indiquer le niveau de fonctionnalité du message de trace.

[in] Format : Ce paramètre est le format d'affichage du message de trace. Ce format utilise le même formalisme que pour la fonction printf().

[in] … : La liste variable de paramètres utilisés par le format d'affichage défini dans le paramètre précédent. Une attention particulière doit être portée afin que cette liste de paramètres et leurs types correspondent bien avec ce qui est attendu par le format d'affichage.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogW() et une version ANSI WinLogA(). Il existe aussi une macro WinLog qui permet de choisir automatiquement la bonne fonction.

La bibliothèque doit d'abord être initialisée par un appel à la fonction WinLogRegister() pour pouvoir utiliser la fonction WinLog().

WinLogDump( )

La fonction WinLogDump() permet d'afficher le contenu d'un bloc de mémoire ou d'une structure.

Syntaxe

WinLogRet_t WinLogDumpA ( const unsigned long FeatureLevel, const char * Name, const void * Buffer, const unsigned long Size );

WinLogRet_t WinLogDumpW ( const unsigned long FeatureLevel, const wchar_t * Name, const void * Buffer, const unsigned long Size );

Paramètres

[in] FeatureLevel : Ce paramètre est un nombre de 0 à 32 qui permet d'indiquer le niveau de fonctionnalité du message de trace.

[in] Name : Ce paramètre est un texte libre qui est affiché en en-tête avant l'affichage du contenu du bloc de mémoire ou de la structure.

[in] Buffer : Ce paramètre est l'adresse du bloc mémoire à afficher.

[in] Size : Ce paramètre est la taille du bloc mémoire à afficher.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogDumpW() et une version ANSI WinLogDumpA(). Il existe aussi une macro WinLogDump qui permet de choisir automatiquement la bonne fonction.

La bibliothèque doit d'abord être initialisée par un appel à la fonction WinLogRegister() pour pouvoir utiliser la fonction WinLog().

4-6 - Les fonctions annexes

WinLogDumpParam( )

La fonction WinLogDumpParam() permet d'afficher la configuration courante de la bibliothèque WinLog.

Syntaxe

WinLogRet_t WinLogDumpParam ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

La bibliothèque doit d'abord être initialisée par un appel à la fonction WinLogRegister() pour pouvoir utiliser la fonction WinLog().

WinLogDecodeError( )

La fonction WinLogDecodeError() permet d'obtenir le texte d'une erreur retournée par la bibliothèque WinLog.

Syntaxe

const wchar_t * WinLogDecodeError ( const WinLogRet_t Error );

Paramètres

[in] Error : Ce paramètre indique le code d'erreur de la bibliothèque dont on recherche le texte.

Valeur retournée

const wchar_t * : Texte du code d'erreur passé en paramètre.

Remarque

Cette fonction existe en deux versions : une version UNICODE WinLogDumpW() et une version ANSI WinLogDumpA(). Il existe aussi une macro WinLogDump qui permet de choisir automatiquement la bonne fonction.

La bibliothèque doit d'abord être initialisée par un appel à la fonction WinLogRegister() pour pouvoir utiliser la fonction WinLog().

WinLogReleaseInfo( )

La fonction WinLogReleaseInfo() permet de libérer les structures du type WinLogCallBack_Info_t. Ces structures sont reçues par les fonctions de callback ou les fonctions de traitement des messages Windows.

Syntaxe

WinLogRet_t WinLogReleaseInfo ( WinLogCallBack_Info_t * CallbackInfo );

Paramètres

[in] CallbackInfo : Le pointeur sur la structure à libérer.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

La libération des structures WinLogCallBack_Info_t ne peut se faire que par le biais de cette fonction. Il doit impérativement être effectué sous peine d'avoir des pertes de mémoire.

WinLogSetUtcTime( )

La fonction WinLogSetUtcTime() force le message d'erreur à afficher la date et l'heure en heure UTC.

Syntaxe

WinLogRet_t WinLogSetUtcTime ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la bibliothèque WinLog affiche les messages en utilisant l'heure UTC.

WinLogSetLocalTime( )

La fonction WinLogSetLocalTime() force le message d'erreur à afficher la date et l'heure en heure locale.

Syntaxe

WinLogRet_t WinLogSetLocalTime ( void );

Paramètres

Aucun.

Valeur retournée

WinLogRet_t : Code de retour de la fonction.

Remarque

Par défaut, la bibliothèque WinLog affiche les messages en utilisant l'heure UTC.

4-7 - Les macros de WinLog

La bibliothèque WinLog définit un certain nombre de macros utilisables par le pré processeur afin de faciliter l'écriture des messages de trace. Ces macros sont :

- WINLOG_LEVEL_<nn> : Les différents niveaux de fonctionnalités possibles. Les valeurs que peut prendre nn vont de 00 à 32 pour spécifier chacun des 33 niveaux de fonctionnalité.

- INFO<n> : Ces macros permettent de générer un message de trace de type WinLog_Info et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().

- USER<n> : Ces macros permettent de générer un message de trace de type WinLog_User et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().

- WARNING<n> : Ces macros permettent de générer un message de trace de type WinLog_Warning et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().

- ERROR<n> : Ces macros permettent de générer un message de trace de type WinLog_Error et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().

- FATAL<n> : Ces macros permettent de générer un message de trace de type WinLog_Fatal et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().

- DUMP2 : Cette macro permet de générer un message de trace de type WinLog_Dump et de niveau de fonctionnalité WINLOG_LEVEL_00. La taille de la structure ou du bloc de mémoire à afficher est calculée automatiquement par l'opérateur sizeof().

- DUMP3 : Cette macro permet de générer un message de trace de type WinLog_Dump et de niveau de fonctionnalité WINLOG_LEVEL_00. À la différence de DUMP2, cette macro ne calcule pas automatiquement la taille de la structure ou du bloc de mémoire. Il doit être fourni par le développeur.

- Les macros WinLog(), WinLogDump(), WinLogSyslogSetRemoteServer(), WinLogFileSetFolderName(), WinLogPipeSetName() sont des macros qui permettent de choisir automatiquement la version UNICODE ou ANSI de la fonction suivant que la macro UNICODE ou _UNICODE est définie ou non. Les mêmes conventions de nommage que Microsoft sont reprises pour ces fonctions (suffixe W pour les versions UNICODE ou A pour les versions ANSI).

4-8 - Les variables d'environnement

Le fonctionnement de la bibliothèque WinLog peut être modifié en utilisant certaines variables d'environnement. Ces variables ajoutent une certaine souplesse d'utilisation en permettant d'activer ou de désactiver facilement et sans recompilation certaines fonctionnalités de la bibliothèque.

Les variables d'environnement gérées par la bibliothèque WinLog sont les suivantes :

- WINLOG_FEATURE_LEVEL : Cette variable d'environnement permet de spécifier les niveaux de fonctionnalité qui seront gérés par la bibliothèque. Par exemple, si la variable d'environnement WINLOG_FEATURE_LEVEL vaut 12, alors les niveaux de fonctionnalités affichés seront WINLOG_LEVEL_00, WINLOG_LEVEL_03 et WINLOG_LEVEL_04. Rappel, le niveau de fonctionnalité WINLOG_LEVEL_00 est toujours affiché.

- WINLOG_FILE_FOLDER : Cette variable d'environnement permet de spécifier le répertoire dans lequel est généré le fichier d'archivage des messages de trace. Si le chemin indiqué n'est pas valide, il est ignoré.

- WINLOG_FILE_SIZEMAX : Cette variable d'environnement permet de spécifier la taille du fichier d'archivage des messages de trace au-delà de laquelle une rotation des fichiers d'archivage est effectuée.

- WINLOG_FILE_HISTORYSIZE : Cette variable d'environnement permet de spécifier le nombre de fichiers d'historique à conserver lorsqu'une rotation des fichiers d'archivage est effectuée.

- WINLOG_FILE_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans un fichier de sortie est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.

- WINLOG_OUTPUT_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans la console standard (flux stdout) est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.

- WINLOG_PIPE_NAME : Cette variable d'environnement permet de spécifier le nom du pipe nommé à utiliser lorsque la fonctionnalité d'envoi des messages de trace dans un pipe nommé est activée. Si le nom de ce pipe n'est pas valide, il est ignoré.

- WINLOG_PIPE_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans un pipe nommé est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.

- WINLOG_SYSLOG_SERVER : Cette variable d'environnement permet de spécifier l'adresse IP du server Syslog vers qui envoyer les messages de trace au format Syslog.

- WINLOG_SYSLOG_PORT : Cette variable d'environnement permet de spécifier le port UDP du server Syslog vers qui envoyer les messages de trace au format Syslog.

- WINLOG_SYSLOG_FACILITY : Cette variable d'environnement permet de spécifier la facilité Syslog (de 0 à 23) à utiliser pour envoyer les messages de trace au format Syslog.

- WINLOG_SYSLOG_ENABLE : Cette variable d'environnement permet de spécifier si la fonctionnalité d'envoi des messages de trace à destination d'un serveur Syslog est activée ou non. Si la valeur de cette variable d'environnement vaut « 0 », la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de « 0 », la fonctionnalité est activée.

4-9 - Fonctionnement par défaut

Le fonctionnement par défaut de la bibliothèque WinLog est le suivant :

4-9-1 - La méthode File

La fonctionnalité d'archivage des messages de trace dans un fichier d'archivage est activée. Cette activation est ensuite modifiée si la variable d'environnement WINLOG_FILE_ENABLED est définie et que sa valeur vaut 0.

Le répertoire de génération des fichiers d'archivage des messages de trace est par défaut c:\. Le répertoire est ensuite modifié si la variable d'environnement WINLOG_FILE_FOLDER est définie et que sa valeur est un répertoire de valide.

La taille maximum avant rotation des fichiers d'archivage des messages de trace est fixée à 10 000 000 (10 Mo). Cette valeur est ensuite modifiée si la variable d'environnement WINLOG_FILE_SIZEMAX est définie et que cette valeur est différente de 0.

Le nombre de fichiers d'archivage conservés lors de la rotation des fichiers d'archivage est fixé à 10. Cette valeur est ensuite modifiée si la variable d'environnement WINLOG_FILE_HISTORYSIZE est définie et que sa valeur est différente de 0.

4-9-2 - La méthode Output

La fonctionnalité d'écriture les messages de trace générés dans la console standard (flux stdout) est activée. Cette activation est ensuite modifiée si la variable d'environnement WINLOG_OUTPUT_ENABLED est définie et que sa valeur vaut 0.

4-9-3 - La méthode Debug

La fonctionnalité d'envoi des messages de trace dans la fenêtre de visualisation des traces du débogueur si un débogueur est présent est désactivée. Cette fonctionnalité ne peut être activée que par programme.

4-9-4 - La méthode Callback

La fonctionnalité de rappel de fonction du processus en lui fournissant en paramètre le message de trace généré est désactivé. Cette fonctionnalité ne peut être activée que par programme.

4-9-5 - La méthode PostSend Message

La fonctionnalité d'envoi de messages Windows (par PostMessage ou SendMessage) à une fenêtre en lui fournissant en paramètre le message de trace est désactivée. Cette fonctionnalité ne peut être activée que par programme.

4-9-6 - La méthode Pipe

La fonctionnalité d'envoi des messages de trace dans un pipe nommé est désactivée. Cette désactivation est ensuite modifiée si la variable d'environnement WINLOG_PIPE_ENABLED est définie et que sa valeur est différente de 0.

Le nom du pipe nommé est fixé par défaut à \\.\pipe\WinLog_pipe. Ce nom est ensuite modifié si la variable d'environnement WINLOG_PIPE_NAME est définie.

4-9-7 - La méthode Syslog

La fonctionnalité d'envoi des messages de trace à destination d'un serveur Syslog est désactivée par défaut. Cette désactivation est ensuite modifiée si la variable d'environnement WINLOG_SYSLOG_ENABLED est définie et que sa valeur est différente de 0.

L'adresse IP du serveur Syslog vers qui envoyer les messages de trace au format Syslog n'est pas définie par défaut. Cette valeur peut être initialisée si la variable d'environnement WINLOG_SYSLOG_SERVER est définie.

La valeur par défaut du numéro de port UDP du serveur Syslog est fixée à 514. Cette valeur est ensuite modifiée si la variable d'environnement WINLOG_SYSLOG_PORT est définie et que sa valeur est différente de 0.

La facilité Syslog utilisée pour les messages de trace est fixée à 23 (facilité local use 7). Cette valeur est ensuite modifiée si la variable d'environnement WINLOG_SYSLOG_FACILITY est définie.

4-9-8 - Le niveau de fonctionnalité

La valeur du niveau de fonctionnalité est fixée par défaut à 0, c'est-à-dire que seuls les messages de trace de niveau WINLOG_LEVEL_00 sont affichés. Cette valeur est ensuite modifiée si la variable d'environnement WINLOG_FEATURE_LEVEL est définie et que sa valeur est différente de 0.

5 - Exemple d'utilisation

// TestWinLog.cpp : programme de test de la bibliothèque WinLog

#include "WinLog.h"

// fonction de callback
void Callback(WinLogCallBack_Info_t * CallbackInfo)
{
// ce message ne sera jamais affiché, car il serait réentrant
// on est déjà dans le traitement d'un message
INFO1(L"Message réentrant !!");

// liberation du bloc
WinLogReleaseInfo(CallbackInfo);
}

int wmain(int argc, wchar_t * argv[])
{
// initialisation du niveau de fonctionnalité affiché
WinLogSetFeatureLevel(WINLOG_LEVEL_07 | WINLOG_LEVEL_11);

// initialisation de la partie WinLogFile
WinLogFileSetFolderName(L"c:\\temp");
WinLogFileSetSizeMax(1000);
WinLogFileSetHistorySize(10);
WinLogFileEnable();

// initialisation de la partie WinLogOutput
WinLogOutputEnable();

// initialisation de la partie WinLogDebug
// uniquement en mode debug
#ifdef _DEBUG
WinLogDebugEnable();
#else
WinLogDebugDisable();
#endif

// initialisation de la partie WinLogCallback
WinLogPostSendMessageClear();
WinLogPostSendMessageDisable();

// initialisation de la partie WinLogPostSendMessage
WinLogCallbackSet(Callback);
WinLogCallbackEnable();

// initialisation de la partie WinLogPipe
WinLogPipeSetName(L"\\\\.\\pipe\\WinLog_pipe_TestUnit");
WinLogPipeEnable();

// initialisation de la partie Syslog
WinLogSyslogSetRemoteServer(L"192.168.1.254");
WinLogSyslogSetRemotePort(514);
WinLogSyslogSetFacility(20);
WinLogSyslogEnable();

// initialisation de la bibliothèque
WinLogRegister(L"TestUnit");

// affichage des paramètres de fonctionnement
WinLogDumpParam();

// quelques messages
INFO1(L"Hello World !!");
WARNING1(L"Message de test");

// quelques messages utilisant le niveau de fonctionnalité

// level 0, toujours affiché
WinLogW(WinLog_Info, WINLOG_LEVEL_00, L"%s %d", L"Message de niveau", WINLOG_LEVEL_00);

// level 5 pas affiché (par configuration)
WinLogW(WinLog_Info, WINLOG_LEVEL_05, L"%s %d", L"Message de niveau", WINLOG_LEVEL_05);

// level 7 affiché (par configuration)
WinLogW(WinLog_Info, WINLOG_LEVEL_07, L"%s %d", L"Message de niveau", WINLOG_LEVEL_07);

// level 11 affiché (par configuration)
WinLogW(WinLog_Info, WINLOG_LEVEL_11, L"%s %d", L"Message de niveau", WINLOG_LEVEL_11);

// affichage de blocs de mémoire
char buffer[32];
for(int boucle = 0; boucle != sizeof(buffer); boucle++)
buffer[boucle] = boucle + 16;

// dump d'un buffer avec calcul automatique de sa taille
DUMP2(L"Dump du tableau buffer[]", buffer);

// dump d'un buffer dont la taille est fournie par le développeur
DUMP3(L"Dump de 29 octets du tableau buffer[]", buffer, 29);

// fin d'utilisation de la bibliothèque
WinLogUnregister();

return 0;
}

6 - Conclusion

La bibliothèque WinLog est une petite bibliothèque, facile d'utilisation, qui rend le service que l'on attend d'elle :

- Elle s'intègre très facilement dans un projet (de préférence en début de projet).

- Elle dispose de nombreuses facilités activables ou désactivables par programme ou bien en fonction de variables d'environnement. La modification du comportement de la bibliothèque ne nécessite pas la recompilation du programme utilisateur.

- Elle dispose de plusieurs possibilités de sortie (fichier, console, débogueur, callback, message windows, pipe nommé, syslog), ce qui permet de récupérer et d'analyser facilement les messages de trace générés par le programme utilisateur.

- Elle génère des messages de trace avec un formalisme constant et des informations de débogage utiles.

Maintenant, dès que je démarre un projet un peu conséquent, je ne me pose plus de questions et j'utilise cette bibliothèque.

Je tiens à remercier Dut pour ses conseils avisés lors de la relecture de ce document.