Partager via

Appel de SetupWriteTextLogError

  • Article

SetupWriteTextLogError écrit des informations sur une erreur spécifique à SetupAPI ou une erreur Win32 dans un journal de texte SetupAPI. SetupWriteTextLogError écrit deux entrées consécutives dans un journal texte : la première entrée contient les mêmes informations dans le même format que celle écrite par SetupWriteTextLog et la deuxième entrée consigne un code d’erreur correspondant et une description conviviale de l’erreur.

Pour appeler SetupWriteTextLogError, une application fournit les mêmes informations qu’elle fournirait pour appeler SetupWriteTextLog et, en outre, fournit la valeur d’une erreur spécifique à SetupAPI ou d’une erreur Win32.

SetupWriteTextLogError écrit la première entrée de journal au format suivant :

entry_prefix time_stamp catégorie ****mise en retrait mise en forme-message

SetupWriteTextLogError écrit la deuxième entrée de journal au format suivant :

entry_prefix time_stamp catégorie **retrait **Error:error:error-number error-description

Où :

  • Les champs entry_prefix, horodatage, catégorie, mise en retrait et message mis en forme sont les mêmes que ceux décrits dans Format d’un corps de section de journal de texte.

  • Le champ numéro d’erreur contient le numéro d’erreur.

  • Le champ description de l’erreur contient une description conviviale de l’erreur.

L’exemple suivant montre comment une application peut généralement appeler SetupWriteTextLogError pour consigner des informations sur une erreur dans un journal texte. L’erreur utilisée dans l’exemple est une erreur de démarrage du système. L’application appelle SetupWriteTextLogError, en fournissant les valeurs de paramètre suivantes :

  • LogToken est défini sur une valeur de jeton de journal qui a été obtenue en appelant SetupGetThreadLogToken ou est l’une des valeurs de jeton de journal définies par le système qui sont décrites dans Jetons de journal.

  • Category est défini sur TXTLOG_VENDOR, ce qui indique que l’entrée du journal est effectuée par une application fournie par le fournisseur. Les catégories d’événements sont décrites dans Activation des catégories d’événements pour un journal texte.

  • LogFlags est défini sur TXTLOG_ERROR. Cet exemple n’inclut pas d’horodatage ni de modification de la profondeur de retrait. La profondeur de mise en retrait actuelle était précédemment définie sur cinq espaces de texte monospaces. Pour plus d’informations sur la modification de la profondeur de mise en retrait, consultez Écriture d’entrées de journal mises en retrait. Les niveaux d’événements sont décrits dans Définition du niveau d’événement pour un journal de texte.

  • L’erreur est définie sur la valeur du code d’erreur Win32, ERROR_SERVICE_ALREADY_RUNNING. La valeur décimale de ce code d’erreur est 1056.

  • MessageStr est défini sur TEXT(« Démarrer le service : échec du démarrage du service 'SomeService' »).

  • Une liste de paramètres séparés par des virgules n’est pas fournie.

Les paramètres LogToken, Category et LogFlags affectent l’opération de SetupWriteTextLogError de la même manière que ces paramètres affectent le fonctionnement de SetupWriteTextLog.

Le code suivant appelle SetupWriteTextLogError pour écrire l’entrée de journal pour cet exemple :

//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'"),);

Si la catégorie d’événements TXTLOG_VENDOR est activée et que le niveau d’événement TXTLOG_ERROR est défini pour le journal texte, ce code crée une entrée dans le journal texte qui sera mise en forme comme suit :

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

N’oubliez pas que SetupWriteTextLogError fournit la chaîne « Un instance du service est déjà en cours d’exécution » pour décrire l’erreur Win32 dont la valeur est 1056.