Compartilhar via

FormatMessage

  • Artigo

Windows Mobile SupportedWindows Embedded CE Supported

9/8/2008

Essa função formata um seqüência de caracteres mensagem.

Syntax

DWORD FormatMessage(
  DWORD dwFlags, 
  LPCVOID lpSource, 
  DWORD dwMessageId, 
  DWORD dwLanguageId, 
  LPTSTR lpBuffer, 
  DWORD nSize, 
  va_list* Arguments
);

Parameters

  • dwFlags
    [no] Especifica aspectos da formatação de processo e como interpretar o lpSource parâmetro. A baixa-byte de ordem dwFlags Especifica como a função Controla quebras de linha na reserva de saída. A baixa-byte ordem também pode especificar a largura máxima de um formatado linha saída.

    Este parâmetro pode ser uma combinação do seguinte sinalizadores bit.

    Valor Descrição

    FORMAT_MESSAGE_ALLOCATE_BUFFER

    Especifica que o lpBuffer parâmetro é um ponteiro para um PVOID ponteiro e que o nTamanho parâmetro especifica o número mínimo de bytes (versão ANSI) ou caracteres (versão Unicode) para alocar para uma reserva mensagem saída. A função aloca uma reserva grande o suficiente para armazenar o formatado mensagem e locais um ponteiro para a reserva alocada no endereço especificado por lpBuffer. O chamador deve usar o LocalFree função para livre a reserva quando ele é necessário no longer.

    FORMAT_MESSAGE_IGNORE_INSERTS

    Especifica que as seqüências de inserção na definição de mensagem devem ser ignorados e passadas por meio para inalterado reserva a saída. Este sinalizador é útil para buscar uma mensagem para formatação posterior. Se este sinalizador estiver definido, o Argumentos parâmetro será ignorado.

    FORMAT_MESSAGE_FROM_STRING

    Especifica que lpSource é um ponteiro para uma definição mensagem NULL-Terminated. A definição mensagem pode conter seqüências de inserção, assim como o texto em um recurso tabela mensagem mensagem pode. Não pode ser usado com FORMAT_MESSAGE_FROM_HMODULE ou FORMAT_MESSAGE_FROM_SYSTEM.

    FORMAT_MESSAGE_FROM_HMODULE

    Especifica que lpSource é um identificador módulo que contém a mensagem-recursos tabela para pesquisa. Se esse lpSource identificador é NULL, o atual aplicativo imagem arquivo do processo será procurado. Não pode ser usado com FORMAT_MESSAGE_FROM_STRING.

    FORMAT_MESSAGE_FROM_SYSTEM

    Especifica que a função deve pesquisa a mensagem sistema-recursos tabela para a mensagem solicitada. Se este sinalizador for especificado com FORMAT_MESSAGE_FROM_HMODULE, a função pesquisa a tabela mensagem sistema se a mensagem não for encontrada no módulo especificado por lpSource. Não pode ser usado com FORMAT_MESSAGE_FROM_STRING.

    Se este sinalizador for especificado, um aplicativo pode transmitir o resultado das GetLastError função para recuperar o texto mensagem para um erro System-defined.

    Nem todos os dispositivos baseado em Windows Embedded CE conterá a mensagem sistema-recursos tabela. Esta é uma parte selecionável de sistema operacional o Windows Embedded CE e geralmente é removida para economizar espaço.

    FORMAT_MESSAGE_ARGUMENT_ARRAY

    Especifica que o Argumentos parâmetro é Não Um va_list estrutura, mas em vez disso, é apenas um ponteiro para uma matriz de 32-bit valores que representam os argumentos.

    A baixa-byte de ordem dwFlags Pode especificar a largura máxima de um formatado linha saída. Use o constante FORMAT_MESSAGE_MAX_WIDTH_MASK e bit a bit Boolean as operações para definir e recuperar esse máximo valor largura.

    A seguinte lista mostra como FormatMessage interpretará o valor de baixo-byte ordem.

    Valor Descrição

    0

    Não existem restrições largura de linha nenhuma saída. A função armazena as quebras de linha que estão em texto definição a mensagem na reserva de saída.

    Um diferente de zero valor Other Than FORMAT_MESSAGE_MAX_WIDTH_MASK

    O diferente de zero valor é o número máximo de caracteres em uma linha saída. A função ignorará regular quebras de linha no texto definição da mensagem. A função nunca divide um seqüência de caracteres delimitados por espaço em branco entre um quebra de linha. A função armazena rígido-codificado quebras de linha no texto da mensagem definição na reserva de saída. Disco rígido-codificado quebras de linha são codificado com o seqüência de escape % n %.

    FORMAT_MESSAGE_MAX_WIDTH_MASK

    A função ignorará regular quebras de linha no texto definição da mensagem. A função armazena rígido-codificado quebras de linha no texto da mensagem definição na reserva de saída. A função gera não novas quebras de linha.

  • lpSource
    [no] Ponteiro para a localidade de definição de mensagem. O tipo deste parâmetro depende das configurações na dwFlags parâmetro.

    Valor Descrição

    FORMAT_MESSAGE_FROM_HMODULE

    O lpSource parâmetro é um hModule do módulo que contém a tabela mensagem para pesquisa.

    FORMAT_MESSAGE_FROM_STRING

    O lpSource parâmetro é um LPTSTR que aponta para não formatado texto mensagem. Ele será digitalizado para inserções e formatado de acordo.

    Se nenhuma desses sinalizadores estiver definida em dwFlags, em seguida, lpSource é ignorado.

  • dwMessageId
    [no] Especifica os 32-bit mensagem identificador para a mensagem solicitada. Este parâmetro é ignorado se dwFlags Inclui FORMAT_MESSAGE_FROM_STRING.
  • dwLanguageId
    [no] Não suportado.
  • lpBuffer
    [out] Ponteiro para uma reserva para o formatado (e terminada por caractere nulo) mensagem. Se dwFlags Inclui FORMAT_MESSAGE_ALLOCATE_BUFFER, a função aloca uma reserva usando o LocalAlloc função e locais de ponteiro para a reserva no endereço especificado no lpBuffer.
  • nTamanho
    [no] Quando o sinalizador FORMAT_MESSAGE_ALLOCATE_BUFFER não é definida, este parâmetro especifica o número máximo de caracteres que podem ser armazenados na reserva de saída. Se FORMAT_MESSAGE_ALLOCATE_BUFFER for definida, este parâmetro especifica o número mínimo de bytes ou caracteres para alocar para uma reserva saída.

  • Argumentos
    [no] Ponteiro para uma matriz de 32-bit valores que são usados à medida que insere os valores no formatado mensagem. %1 No seqüência de caracteres formato indica o primeiro valor na Argumentos matriz; um %2 indica o segundo argumento; e assim por diante.

    A interpretação de cada 32-bit valor depende de como a formatação informações associado com a inserir na definição de mensagem. O usar como padrão é para tratar cada valor como um ponteiro para uma seqüência de caracteres NULL-Terminated.

    Por padrão, o Argumentos parâmetro é do tipo va_list *, que é uma implementação-específicos e language-tipo de dados para descrever uma variável número de argumentos. Se você não tiver um ponteiro de tipo va_list *, em seguida, especificar o sinalizador FORMAT_MESSAGE_ARGUMENT_ARRAY e transmitir um ponteiro para uma matriz de 32-bit valores; Esses valores são entrada para a mensagem formatado como os valores de inserção. Cada inserção deve ter um correspondente elemento na matriz.

Return Value

O número de caracteres armazenados na reserva de saída, excluindo o caractere nulo de terminação, indica sucesso. Zero indica falha. Para informações de erro estendidas get, chamar GetLastError.

Remarks

Esta função exige uma definição mensagem como entrada. A definição mensagem pode vir de uma reserva passada para a função. Ele pode vir de um recurso tabela mensagem em um módulo já carregado. Ou o chamador pode pedir a função para pesquisa recursos do sistema tabela mensagem de definição de mensagem. FormatMessage Localiza a definição mensagem em um recurso tabela mensagem com base em um identificador mensagem. FormatMessage Copia o formatado texto mensagem para uma reserva saída, processamento qualquer incorporado Inserir seqüências se solicitado.

O FormatMessage função pode ser usada para obter erro mensagem seqüências de caracteres para os códigos de erro sistema retornados por GetLastError, conforme o seguinte exemplo codificar.

LPVOID lpMsgBuf;
FormatMessage( 
    FORMAT_MESSAGE_ALLOCATE_BUFFER | 
    FORMAT_MESSAGE_FROM_SYSTEM | 
    FORMAT_MESSAGE_IGNORE_INSERTS,
    NULL,
    GetLastError(),
    0, // Default language
    (LPTSTR) &lpMsgBuf,
    0,
    NULL 
);
// Process any inserts in lpMsgBuf.
// ...
// Display the string.
MessageBox( NULL, (LPCTSTR)lpMsgBuf, L"Error", MB_OK | MB_ICONINFORMATION );
// Free the buffer.
LocalFree( lpMsgBuf );

Dentro do texto mensagem, várias seqüências de escape são com suporte para dinamicamente formatação a mensagem. Esses escape seqüências e seus significados são mostrados na seguinte lista. Todos os escape iniciar seqüências com o caractere de porcentagem (%).

  • %0
    Encerra uma linha de texto mensagem sem um caractere à direita nova linha. Esta seqüência de escape podem ser usados para compilar backup linhas longas ou para finalizar a mensagem próprio sem um caractere à direita nova linha. Ele é útil para prompt mensagens.

  • % n! formato printf seqüência de caracteres!
    Identifica uma inserção. O valor de n Podem ser o intervalo de 1 a 99. O printf formato seqüência de caracteres (que devem ser bracketed, exclamation Marks) é opcional e padrões para ! s! Se não especificado.

    O printf formato seqüência de caracteres podem conter o * especificador para a precisão ou o componente largura. Se * for especificado para um componente, o FormatMessage função usa % inserirn+ 1; Ele usa %n+ 2 se * for especificado para ambos os componentes.

    Ponto flutuante printf formato especificadores — e, E, f e g — não são com suporte. A solução alternativa é usar o sprintf função para formato de número de ponto flutuante em uma reserva temporária, em seguida, usar que reserva como a seqüência de caracteres de inserção.

Quaisquer outros seguinte caractere não dígito um caractere de porcentagem é formatado na mensagem de saída sem o caractere de porcentagem. Seguem alguns exemplos:

Formato seqüência de caracteres Saída resultante

%%

Um único assinar porcentagem no formatado texto mensagem.

%n

Um quebra de linha de disco rígido quando o seqüência de caracteres formato ocorre no final de uma linha. Seqüência de caracteres esse formato é útil quando FormatMessage está fornecendo regular quebras de linha para que a mensagem caiba em uma determinada largura.

% espaço

Um espaço no formatado texto mensagem. Seqüência de caracteres esse formato podem ser usado para garantir o apropriado número de espaços à direita em uma linha de texto mensagem.

%.

Um único período no formatado texto mensagem. Seqüência de caracteres esse formato podem ser usado para incluir um único período de início de uma linha sem encerrar a definição de texto mensagem.

%!

Um único ponto de exclamação no formatado texto mensagem. Seqüência de caracteres esse formato podem ser usado para incluir um ponto de exclamação imediatamente após uma inserção sem sua sendo mistaken para o início de um printf formato seqüência de caracteres.

Requirements

Header winbase.h
Library Fmtmsg.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

GetLastError
LocalAlloc
LoadString
LocalFree