Appel de SetupWriteTextLogError

SetupWriteTextLogError écrit des informations sur une erreur spécifique à SetupAPI ou une erreur Win32 dans un journal texte SetupAPI. SetupWriteTextLogError écrit deux entrées consécutives dans un journal texte : la première entrée contient les mêmes informations au même format que celle écrite par SetupWriteTextLog et la deuxième entrée enregistre 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 :

 **** indentation formatted-message

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

** retrait **Erreur :error-number error-description

Where:

• Les champs entry_prefix, horodatage, catégorie, retrait et message formaté sont identiques à ceux décrits dans le format d’un corps de section de journal de texte.

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

• Le champ de description d’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 soit été obtenue par l’appel de SetupGetThreadLogToken, soit correspond à l’une des valeurs de jeton de journal définies par le système qui sont décrites dans Log Tokens.

• La catégorie est définie 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 de texte.

• LogFlags est défini sur TXTLOG_ERROR. Cet exemple n’inclut pas d’horodatage et ne modifie pas la profondeur d’indentation. La profondeur de mise en retrait actuelle a été précédemment définie sur cinq espaces de texte monospace. Pour plus d’informations sur la modification de la profondeur de retrait, consultez Écriture d’entrées de journal mises en retrait. Les niveaux d’événement 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ées par des virgules n’est pas fournie.

Les paramètres LogToken, Category et LogFlags affectent l’opération de SetupWriteTextLogError de la même façon que ces paramètres affectent l’opération 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énement TXTLOG_VENDOR est activée et que le niveau d’événement TXTLOG_ERROR est défini pour le journal de texte, ce code crée une entrée dans le journal de texte 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 « Une instance du service est déjà en cours d’exécution » pour décrire l’erreur Win32 dont la valeur est 1056.