Compartir a través de

Llamar a SetupWriteTextLogError

  • Artículo

SetupWriteTextLogError escribe información sobre un error específico de SetupAPI o un error win32 en un registro de texto de 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:

categoría **** de entry_prefix time_stamp sangría con formato de mensaje

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

categoría ** de entry_prefix time_stamp indentation **Error:error-number error-description

Donde:

  • Los campos de 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 llamando 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 monoespacio. Para obtener información sobre cómo cambiar la profundidad de sangría, vea Escribir 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("Start Service: Failed to start service '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 de TXTLOG_VENDOR está habilitada y el nivel de evento TXTLOG_ERROR se establece para el registro de texto, este código creará una entrada en el registro de texto con el siguiente formato:

!!!     :  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.