Función FormatMessageA (winbase.h)

Da formato a una cadena de mensaje. La función requiere una definición de mensaje como entrada. La definición del mensaje puede proceder de un búfer pasado a la función. Puede proceder de un recurso de tabla de mensajes en un módulo ya cargado. O bien, el autor de la llamada puede pedir a la función que busque los recursos de la tabla de mensajes del sistema para la definición del mensaje. La función busca la definición de mensaje en un recurso de tabla de mensajes en función de un identificador de mensaje y un identificador de idioma. La función copia el texto del mensaje con formato en un búfer de salida, procesando las secuencias de inserción insertadas si se solicitan.

Sintaxis

DWORD FormatMessageA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCVOID lpSource,
  [in]           DWORD   dwMessageId,
  [in]           DWORD   dwLanguageId,
  [out]          LPSTR   lpBuffer,
  [in]           DWORD   nSize,
  [in, optional] va_list *Arguments
);

Parámetros

[in] dwFlags

Las opciones de formato y cómo interpretar el parámetro lpSource. El byte de orden bajo de dwFlags especifica cómo controla la función los saltos de línea en el búfer de salida. El byte de orden bajo también puede especificar el ancho máximo de una línea de salida con formato.

Este parámetro puede ser uno o varios de los siguientes valores.

El byte de orden bajo de dwFlags puede especificar el ancho máximo de una línea de salida con formato. A continuación se muestran los valores posibles del byte de orden bajo.

Si el byte de orden bajo es un valor distinto de FORMAT_MESSAGE_MAX_WIDTH_MASK, especifica el número máximo de caracteres en una línea de salida. La función omite los saltos de línea normales en el texto de la definición del mensaje. La función nunca divide una cadena delimitada por espacios en blanco en un salto de línea. La función almacena saltos de línea codificados de forma rígida en el texto de definición de mensaje en el búfer de salida. Los saltos de línea codificados de forma rígida se codifican con la secuencia de escape %n.

[in, optional] lpSource

Ubicación de la definición del mensaje. El tipo de este parámetro depende de la configuración del parámetro dwFlags.

Si ninguna de estas marcas se establece en dwFlags, se omite lpSource.

[in] dwMessageId

Identificador de mensaje del mensaje solicitado. Este parámetro se omite si dwFlags incluye FORMAT_MESSAGE_FROM_STRING.

[in] dwLanguageId

El identificador de idioma para el mensaje solicitado. Este parámetro se omite si dwFlags incluye FORMAT_MESSAGE_FROM_STRING.

Si pasa un LANGID específico de en este parámetro, formatMessage devolverá un mensaje solo para ese LANGID. Si la función no encuentra un mensaje para ese LANGID, establece Last-Error en ERROR_RESOURCE_LANG_NOT_FOUND. Si pasa cero, FormatMessage busca un mensaje para LANGID en el orden siguiente:

1. Idioma neutro
2. Subproceso LANGID, en función del valor de configuración regional del subproceso
3. El valor predeterminado del usuario LANGID, en función del valor de configuración regional predeterminado del usuario
4. El valor predeterminado del sistema LANGID, en función del valor de configuración regional predeterminado del sistema
5. Inglés de EE. UU.

[out] lpBuffer

Puntero a un búfer que recibe la cadena terminada en NULL que especifica el mensaje con formato. Si dwFlags incluye FORMAT_MESSAGE_ALLOCATE_BUFFER, la función asigna un búfer mediante la función localAlloc y coloca el puntero al búfer en la dirección especificada en lpBuffer.

Este búfer no puede ser mayor que 64 000 bytes.

[in] nSize

Si no se establece la marca FORMAT_MESSAGE_ALLOCATE_BUFFER, este parámetro especifica el tamaño del búfer de salida, en TCHAR. Si se establece FORMAT_MESSAGE_ALLOCATE_BUFFER, este parámetro especifica el número mínimo de TCHAR asignar para un búfer de salida.

El búfer de salida no puede tener más de 64 000 bytes.

[in, optional] Arguments

Matriz de valores que se usan como valores de inserción en el mensaje con formato. Un %1 en la cadena de formato indica el primer valor de la matriz de Argumentos; un %2 indica el segundo argumento; y así sucesivamente.

La interpretación de cada valor depende de la información de formato asociada a la inserción en la definición del mensaje. El valor predeterminado es tratar cada valor como puntero a una cadena terminada en null.

De forma predeterminada, el parámetro Arguments es de tipo va_list*, que es un tipo de datos específico del lenguaje y la implementación para describir un número variable de argumentos. El estado del argumento va_list no está definido tras la devolución de la función. Para volver a usar el va_list, destruya el puntero de lista de argumentos de variable mediante va_end y vuelva a inicializarlo con va_start.

Si no tiene un puntero de tipo va_list*, especifique la marca FORMAT_MESSAGE_ARGUMENT_ARRAY y pase un puntero a una matriz de valores DWORD_PTR; esos valores se introducen en el mensaje con formato como valores de inserción. Cada inserción debe tener un elemento correspondiente en la matriz.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el número de TCHAR almacenados en el búfer de salida, excepto el carácter nulo de terminación.

Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Observaciones

Dentro del texto del mensaje, se admiten varias secuencias de escape para dar formato dinámico al mensaje. Estas secuencias de escape y sus significados se muestran en las tablas siguientes. Todas las secuencias de escape comienzan con el carácter de porcentaje (%).

Cualquier otro carácter nondigit después de un carácter de porcentaje tiene el formato en el mensaje de salida sin el carácter de porcentaje. A continuación se muestran algunos ejemplos.

Comentarios de seguridad de

Ejemplos

La función FormatMessage de se puede usar para obtener cadenas de mensaje de error para los códigos de error del sistema devueltos por GetLastError. Para obtener un ejemplo, vea Recuperar el código de Last-Error.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>

void main(void)
{
    LPWSTR pMessage = L"%1!*.*s! %4 %5!*s!";
    DWORD_PTR pArgs[] = { (DWORD_PTR)4, (DWORD_PTR)2, (DWORD_PTR)L"Bill",  // %1!*.*s! refers back to the first insertion string in pMessage
         (DWORD_PTR)L"Bob",                                                // %4 refers back to the second insertion string in pMessage
         (DWORD_PTR)6, (DWORD_PTR)L"Bill" };                               // %5!*s! refers back to the third insertion string in pMessage
    const DWORD size = 100+1;
    WCHAR buffer[size];


    if (!FormatMessage(FORMAT_MESSAGE_FROM_STRING | FORMAT_MESSAGE_ARGUMENT_ARRAY,
                       pMessage, 
                       0,
                       0,
                       buffer, 
                       size, 
                       (va_list*)pArgs))
    {
        wprintf(L"Format message failed with 0x%x\n", GetLastError());
        return;
    }

    // Buffer contains "  Bi Bob   Bill".
    wprintf(L"Formatted message: %s\n", buffer);
}

En el ejemplo siguiente se muestra cómo implementar el ejemplo anterior mediante va_list.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>

LPWSTR GetFormattedMessage(LPWSTR pMessage, ...);

void main(void)
{
    LPWSTR pBuffer = NULL;
    LPWSTR pMessage = L"%1!*.*s! %3 %4!*s!";

    // The variable length arguments correspond directly to the format
    // strings in pMessage.
    pBuffer = GetFormattedMessage(pMessage, 4, 2, L"Bill", L"Bob", 6, L"Bill");
    if (pBuffer)
    {
        // Buffer contains "  Bi Bob   Bill".
        wprintf(L"Formatted message: %s\n", pBuffer);
        LocalFree(pBuffer);
    }
    else
    {
        wprintf(L"Format message failed with 0x%x\n", GetLastError());
    }
}

// Formats a message string using the specified message and variable
// list of arguments.
LPWSTR GetFormattedMessage(LPWSTR pMessage, ...)
{
    LPWSTR pBuffer = NULL;

    va_list args = NULL;
    va_start(args, pMessage);

    FormatMessage(FORMAT_MESSAGE_FROM_STRING |
                  FORMAT_MESSAGE_ALLOCATE_BUFFER,
                  pMessage, 
                  0,
                  0,
                  (LPWSTR)&pBuffer, 
                  0, 
                  &args);

    va_end(args);

    return pBuffer;
}

Requisitos

Consulte también

funciones de control de errores

del compilador de mensajes de

Tablas de mensajes