Écriture d’entrées de journal mises en retrait

Comme décrit dans Format d’un corps de section du journal de texte, le format d’une entrée de journal de corps de section dans un journal texte SetupAPI se compose des champs suivants :

entry_prefix time_stamp event_category indentation formatted_message

Vous pouvez utiliser le champ de retrait dans les entrées de journal pour mettre en retrait les champs formatted_message afin de faciliter la lecture et la compréhension des entrées de journal. La quantité de retrait dans un champ de retrait dépend de la profondeur de retrait définie pour la section. La profondeur de retrait est le nombre d’unités de retrait, où une unité de retrait est cinq espaces de texte monospace. Par exemple, une profondeur de mise en retrait de 1 entraîne une mise en retrait de 5 espaces, une profondeur de retrait de 2 entraîne une mise en retrait de 10 espaces, et ainsi de suite. La profondeur de mise en retrait minimale est égale à zéro et la profondeur maximale de retrait est de 16.

Par défaut, la profondeur de mise en retrait d’une section est égale à zéro. Si la profondeur de mise en retrait est égale à zéro, le champ formatted_message ne sera pas mis en retrait. Si une application augmente la profondeur de mise en retrait pour écrire une séquence d’entrées de section en retrait, l’application doit également écrire un ensemble d’entrées de section correspondant pour réinitialiser la profondeur de mise en retrait à zéro avant que l’application puisse ensuite écrire des entrées de section supplémentaires qui ne sont pas mises en retrait.

Pour modifier la profondeur de retrait d’une section, appelez une fonction de journalisation SetupAPI et utilisez un bit OR entre l’une des constantes manifeste définies par le système suivantes et le paramètre flags fourni à la fonction de journalisation SetupAPI.

Constante de manifeste	Modification de la profondeur de mise en retrait
TXTLOG_DEPTH_INCR	La profondeur de retrait est augmentée de 1 pour l’entrée de journal actuelle et toutes les entrées de journal suivantes.
TXTLOG_DEPTH_DECR	La profondeur de retrait est réduite de 1 pour l’entrée de journal actuelle et toutes les entrées de journal suivantes.
TXTLOG_TAB_1	La profondeur de retrait est augmentée de 1 uniquement pour l’entrée de journal actuelle.

Par exemple, la séquence suivante d’appels à SetupWriteTextLog écrit une séquence d’entrées de journal mises en retrait après l’en-tête de section dont le champ section_title est « Exemple de mise en retrait » et dont le champ instance_identifier est « Instance 0 ».

// The LogToken value was previously returned by a call to 
// SetupGetThreadLogToken.
// The LogToken value specifies a section in one of the text logs.

DWORD Category = TXTLOG_VENDOR; 
DWORD Flags = TXTLOG_DETAILS;

SetupWriteTextLog(LogToken, Category, Flags, TEXT("Subsection A"));

// Additional SetupWriteTextLog calls that write entries at Subsection A indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_INCR, TEXT("Subsection A.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_INCR, TEXT("Subsection A.1.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags, TEXT("End of Subsection A.1.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_DECR, TEXT("End of Subsection A.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A indentation level
SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_DECR, TEXT("End of Subsection A"));

Si le niveau d’événement du journal de texte est supérieur ou égal à TXTLOG_DETAILS et que la catégorie d’événement TXTLOG_VENDOR est activée pour le journal de texte, le code précédent écrit les entrées de journal suivantes après l’en-tête de section.

Dans l’exemple suivant, les points de suspension (...) représentent zéro ou plusieurs entrées de journal supplémentaires au même niveau de retrait que l’entrée de journal précédente. L’horodatage serait remplacé par un horodatage réel.

>>>  [Indentation Example - Instance 0]
>>>  2005/02/13 22:06:28.109: Section start
        : Subsection A
...
        :      Subsection A.1
...
        :           Subsection A.1.1
...
        :           End Subsection A.1.1
...
        :      End of Subsection A.1
...
        : End of Subsection A

Pour obtenir un autre exemple d’entrées de section en retrait extraites d’un journal de texte réel, consultez Format d’un corps de section du journal de texte.