Scrittura di voci del log con rientro

Come descritto in Formato di un corpo della sezione Log di testo, il formato di una voce del log del corpo della sezione in un log di testo SetupAPI è costituito dai campi seguenti:

entry_prefix time_stamp event_category indentation formatted_message

È possibile usare il campo di rientro nelle voci di log per rientro dei campi formatted_message per semplificare la lettura e la comprensione delle voci di log. La quantità di rientro in un campo di rientro dipende dalla profondità di rientro impostata per la sezione. La profondità di rientro è il numero di unità di rientro, in cui un'unità di rientro è di cinque spazi di testo monospace. Ad esempio, una profondità di rientro di 1 genera un rientro di 5 spazi, una profondità di rientro di 2 genera un rientro di 10 spazi e così via. La profondità minima di rientro è zero e la profondità massima di rientro è 16.

Per impostazione predefinita, la profondità di rientro di una sezione è zero. Se la profondità di rientro è zero, il campo formatted_message non verrà rientro. Se un'applicazione aumenta la profondità di rientro per scrivere una sequenza di voci di sezione con rientro, l'applicazione deve scrivere anche un set corrispondente di voci di sezione per reimpostare la profondità di rientro a zero prima che l'applicazione possa successivamente scrivere voci di sezione aggiuntive che non sono rientro.

Per modificare la profondità di rientro per una sezione, chiamare una funzione di registrazione SetupAPI e usare un or bit per bit tra una delle costanti manifesto definite dal sistema seguenti e il parametro flag forniti alla funzione di registrazione setupAPI.

Costante manifesto	Modifica profondità di rientro
TXTLOG_DEPTH_INCR	La profondità di rientro è aumentata di 1 per la voce di log corrente e tutte le voci di log successive.
TXTLOG_DEPTH_DECR	La profondità di rientro è diminuita di 1 per la voce di log corrente e tutte le voci di log successive.
TXTLOG_TAB_1	La profondità di rientro è aumentata di 1 solo per la voce di log corrente.

Ad esempio, la sequenza seguente di chiamate a SetupWriteTextLog scrive una sequenza di voci di log con rientro dopo l'intestazione della sezione il cui campo section_title è "Esempio di rientro" e il cui campo instance_identifier è "Istanza 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"));

Se il livello di evento per il log di testo è maggiore o uguale a TXTLOG_DETAILS e la categoria di eventi TXTLOG_VENDOR è abilitata per il log di testo, il codice precedente scriverà le voci di log seguenti dopo l'intestazione della sezione.

Nell'esempio seguente i puntini di sospensione (...) rappresentano zero o più voci di log aggiuntive allo stesso livello di rientro della voce di log precedente. Il timestamp verrà sostituito da un timestamp effettivo.

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

Per un altro esempio di voci di sezione con rientro prese da un log di testo effettivo, vedere Formato di un corpo della sezione log di testo.