Condividi tramite

Chiamata di SetupWriteTextLogError

  • Articolo

SetupWriteTextLogError scrive informazioni su un errore specifico di SetupAPI o un errore Win32 in un log di testo SetupAPI. SetupWriteTextLogError scrive due voci consecutive in un log di testo: la prima voce contiene le stesse informazioni nello stesso formato scritto da SetupWriteTextLog e la seconda voce registra un codice di errore corrispondente e una descrizione descrittiva dell'errore.

Per chiamare SetupWriteTextLogError, un'applicazione fornisce le stesse informazioni fornite per chiamare SetupWriteTextLog e, inoltre, fornisce il valore di un errore specifico di SetupAPI o di un errore Win32.

SetupWriteTextLogError scrive la prima voce di log nel formato seguente:

categoria **** entry_prefix time_stamp rientro formattato-message

SetupWriteTextLogError scrive la seconda voce di log nel formato seguente:

categoria ** entry_prefix time_stamp rientro **Error:error-number error-description

Dove:

  • I campi entry_prefix, timestamp, categoria, rientro e messaggio formattato sono uguali a quelli descritti in Formato di un corpo della sezione Log di testo.

  • Il campo numero di errore contiene il numero di errore.

  • Il campo error-description contiene una descrizione descrittiva dell'errore.

Nell'esempio seguente viene illustrato come un'applicazione potrebbe in genere chiamare SetupWriteTextLogError per registrare informazioni su un errore in un log di testo. L'errore usato nell'esempio è un errore di avvio del sistema. L'applicazione chiama SetupWriteTextLogError, fornendo i valori dei parametri seguenti:

  • LogToken è impostato su un valore del token di log ottenuto chiamando SetupGetThreadLogToken o è uno dei valori del token di log definiti dal sistema descritti in Token di log.

  • La categoria è impostata su TXTLOG_VENDOR, che indica che la voce del log viene effettuata da un'applicazione fornita dal fornitore. Le categorie di eventi sono descritte in Abilitazione delle categorie di eventi per un log di testo.

  • LogFlags è impostato su TXTLOG_ERROR. Questo esempio non include un timestamp o modifica la profondità di rientro. La profondità di rientro corrente è stata impostata in precedenza su cinque spazi di testo monospace. Per informazioni su come modificare la profondità di rientro, vedere Scrittura di voci di log con rientro. I livelli di evento sono descritti in Impostazione del livello di evento per un log di testo.

  • L'errore viene impostato sul valore del codice di errore Win32, ERROR_SERVICE_ALREADY_RUNNING. Il valore decimale di questo codice di errore è 1056.

  • MessageStr è impostato su TEXT("Start Service: Impossibile avviare il servizio 'SomeService'").

  • Non viene fornito un elenco di parametri delimitati da virgole.

I parametri LogToken, Category e LogFlags influiscono sull'operazione di SetupWriteTextLogError nello stesso modo in cui questi parametri influiscono sull'operazione di SetupWriteTextLog.

Il codice seguente chiama SetupWriteTextLogError per scrivere la voce di log per questo esempio:

//The LogToken value was previously returned by call to
//SetupGetThreadLogToken or one of the system-defined log token values
DWORD Category = TXTLOG_VENDOR; 
DWORD Flags = TXTLOG_ERROR ;
DWORD ErrorCode = 1056; // The corresponding Win32 error code

SetupWriteTextLog(LogToken, Category, Flags, ErrorCode, TEXT("Start Service: Failed to start service 'SomeService'"),);

Se la categoria di eventi TXTLOG_VENDOR è abilitata e il livello di evento TXTLOG_ERROR è impostato per il log di testo, questo codice creerebbe una voce nel log di testo che verrà formattata come segue:

!!!     :  Start Service: Failed to start service 'SomeService' 
!!!   :  Error 1056: An instance of the service is already running.

Tenere presente che SetupWriteTextLogError fornisce la stringa "Un'istanza del servizio è già in esecuzione". Per descrivere l'errore Win32 il cui valore è 1056.