Llamada a SetupWriteTextLogError

SetupWriteTextLogError escribe información sobre un error específico de SetupAPI o un error win32 en un registro de texto setupAPI. SetupWriteTextLogError escribe dos entradas consecutivas en un registro de texto: la primera entrada contiene la misma información en el mismo formato que la escrita por SetupWriteTextLog y la segunda entrada registra un código de error correspondiente y una descripción fácil de usar del error.

Para llamar a SetupWriteTextLogError, una aplicación proporciona la misma información que proporcionaría para llamar a SetupWriteTextLog y, además, proporciona el valor de un error específico de SetupAPI o un error win32.

SetupWriteTextLogError escribe la primera entrada de registro en el formato siguiente:

entry_prefix time_stamp categoría ****sangría formatted-message

SetupWriteTextLogError escribe la segunda entrada de registro en el formato siguiente:

entry_prefix time_stamp category **indentation **Error:error-number error-description

Where:

• Los campos entry_prefix, marca de tiempo, categoría, sangría y mensaje con formato son los mismos que los descritos en Formato de un cuerpo de sección de registro de texto.

• El campo número de error contiene el número de error.

• El campo error-description contiene una descripción fácil de usar del error.

En el ejemplo siguiente se muestra cómo una aplicación normalmente podría llamar a SetupWriteTextLogError para registrar información sobre un error en un registro de texto. El error usado en el ejemplo es un error de inicio del sistema. La aplicación llama a SetupWriteTextLogError, proporcionando los siguientes valores de parámetro:

• LogToken se establece en un valor de token de registro que se obtuvo mediante una llamada a SetupGetThreadLogToken o es uno de los valores de token de registro definidos por el sistema que se describen en Tokens de registro.

• La categoría se establece en TXTLOG_VENDOR, lo que indica que una aplicación proporcionada por el proveedor realiza la entrada de registro. Las categorías de eventos se describen en Habilitación de categorías de eventos para un registro de texto.

• LogFlags se establece en TXTLOG_ERROR. En este ejemplo no se incluye una marca de tiempo ni se cambia la profundidad de sangría. La profundidad de sangría actual se estableció anteriormente en cinco espacios de texto monoespaciales. Para obtener información sobre cómo cambiar la profundidad de sangría, consulte Escritura de entradas de registro con sangría. Los niveles de eventos se describen en Establecer el nivel de evento para un registro de texto.

• El error se establece en el valor del código de error win32, ERROR_SERVICE_ALREADY_RUNNING. El valor decimal de este código de error es 1056.

• MessageStr se establece en TEXT("Iniciar servicio: No se pudo iniciar el servicio 'SomeService'").

• No se proporciona una lista de parámetros separados por comas.

Los parámetros LogToken, Category y LogFlags afectan al funcionamiento de SetupWriteTextLogError de la misma manera que estos parámetros afectan al funcionamiento de SetupWriteTextLog.

El código siguiente llama a SetupWriteTextLogError para escribir la entrada de registro para este ejemplo:

//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 categoría de eventos TXTLOG_VENDOR está habilitada y el nivel de evento TXTLOG_ERROR se establece para el registro de texto, este código crearía una entrada en el registro de texto con el formato siguiente:

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

Tenga en cuenta que SetupWriteTextLogError proporciona la cadena "Ya se está ejecutando una instancia del servicio" para describir el error Win32 cuyo valor es 1056.