Função wsprintfA (winuser.h)

Artigo
02/05/2024

Grava dados formatados no buffer especificado. Todos os argumentos são convertidos e copiados para o buffer de saída de acordo com a especificação de formato correspondente na cadeia de caracteres de formato. A função acrescenta um caractere nulo de terminação aos caracteres que grava, mas o valor retornado não inclui o caractere nulo de terminação em sua contagem de caracteres.

Nota Não use. Considere usar uma das seguintes funções: StringCbPrintf, StringCbPrintfEx, StringCchPrintf ou StringCchPrintfEx. Confira Considerações de segurança.

Sintaxe

int WINAPIV wsprintfA(
  [out] LPSTR  unnamedParam1,
  [in]  LPCSTR unnamedParam2,
        ...    
);

Parâmetros

[out] unnamedParam1

Tipo: LPTSTR

O buffer que deve receber a saída formatada. O tamanho máximo do buffer é de 1.024 bytes.

[in] unnamedParam2

Tipo: LPCTSTR

As especificações de controle de formato. Além dos caracteres ASCII comuns, uma especificação de formato para cada argumento aparece nessa cadeia de caracteres. Para obter mais informações sobre a especificação de formato, consulte a seção Comentários.

...

Um ou mais argumentos opcionais. O número e o tipo de parâmetros de argumento dependem das especificações de controle de formato correspondentes no parâmetro lpFmt .

Retornar valor

Tipo: int

Se a função for bem-sucedida, o valor retornado será o número de caracteres armazenados no buffer de saída, sem contar o caractere nulo de terminação.

Se a função falhar, o valor retornado será menor que o comprimento da saída esperada. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A cadeia de caracteres de controle de formato contém especificações de formato que determinam o formato de saída para os argumentos após o parâmetro lpFmt . As especificações de formato, discutidas abaixo, sempre começam com um sinal de porcentagem (%). Se um sinal de porcentagem for seguido por um caractere que não tem significado como um campo de formato, o caractere não será formatado (por exemplo, %% produzirá um único caractere de sinal de porcentagem).

A cadeia de caracteres de controle de formato é lida da esquerda para a direita. Quando a primeira especificação de formato (se houver) é encontrada, ela faz com que o valor do primeiro argumento após a cadeia de caracteres de controle de formato seja convertido e copiado para o buffer de saída de acordo com a especificação de formato. A segunda especificação de formato faz com que o segundo argumento seja convertido e copiado e assim por diante. Se houver mais argumentos do que especificações de formato, os argumentos extras serão ignorados. Se não houver argumentos suficientes para todas as especificações de formato, os resultados serão indefinidos.

Uma especificação de formato tem a seguinte forma:

%[-][#][0][width][.precision]type

Cada campo é um único caractere ou um número que significa uma opção de formato específico. Os caracteres de tipo que aparecem após o último campo de formato opcional determinam se o argumento associado é interpretado como um caractere, uma cadeia de caracteres ou um número. A especificação de formato mais simples contém apenas o sinal de porcentagem e um caractere de tipo (por exemplo, %s). Os campos opcionais controlam outros aspectos da formatação. A seguir estão os campos opcionais e obrigatórios e seus significados.

Campo	Significado
-	Preencha a saída com espaços em branco ou zeros à direita para preencher a largura do campo, justificando a saída para a esquerda. Se esse campo for omitido, a saída será preenchida à esquerda, justificando-a à direita.
#	Prefixe valores hexadecimais com 0x (minúsculas) ou 0X (maiúsculas).
0	Preencha o valor de saída com zeros para preencher a largura do campo. Se esse campo for omitido, o valor de saída será preenchido com espaços em branco.
width	Copie o número mínimo de caracteres especificado para o buffer de saída. O campo de largura é um inteiro não negativo. A especificação de largura nunca faz com que um valor seja truncado; se o número de caracteres no valor de saída for maior que a largura especificada ou se o campo de largura não estiver presente, todos os caracteres do valor serão impressos, sujeitos à especificação de precisão.
. Precisão	Para números, copie o número mínimo de dígitos especificado para o buffer de saída. Se o número de dígitos no argumento for menor que a precisão especificada, o valor de saída será preenchido à esquerda com zeros. O valor não é truncado quando o número de dígitos excede a precisão especificada. Se a precisão especificada for 0 ou omitida inteiramente ou se o período (.) aparecer sem um número após ele, a precisão será definida como 1. Para cadeias de caracteres, copie o número máximo de caracteres especificado para o buffer de saída.
tipo	Gere o argumento correspondente como um caractere, uma cadeia de caracteres ou um número. Esse campo pode ser qualquer um dos valores a seguir. `c` Caractere único. Esse valor é interpretado como o tipo CHAR por wsprintfA e o tipo WCHAR por wsprintfW. Observe que wsprintf é uma macro definida como wsprintfA (Unicode não definido) ou wsprintfW (Unicode definido). `C` Caractere único. Esse valor é interpretado como o tipo WCHAR por wsprintfA e o tipo CHAR por wsprintfW. Observe que wsprintf é uma macro definida como wsprintfA (Unicode não definido) ou wsprintfW (Unicode definido). `d` Inteiro decimal assinado. Esse valor é equivalente a `i`. `hc`, `hC` Caractere único. Se o caractere tiver um valor numérico igual a zero, ele será ignorado. Esse valor é sempre interpretado como o tipo CHAR, mesmo quando o aplicativo de chamada define Unicode. `hd` Argumento inteiro curto com sinal. `hs`, `hS` Cadeia de caracteres. Esse valor é sempre interpretado como o tipo LPSTR, mesmo quando o aplicativo de chamada define Unicode. `hu` Inteiro curto sem sinal. `i` Inteiro decimal assinado. Esse valor é equivalente a `d`. `Ix`, `IX` Inteiro hexadecimal sem sinal de 64 bits em letras minúsculas ou maiúsculas em plataformas de 64 bits, inteiro hexadecimal sem sinal de 32 bits em letras minúsculas ou maiúsculas em plataformas de 32 bits. `lc`, `lC` Caractere único. Se o caractere tiver um valor numérico igual a zero, ele será ignorado. Esse valor é sempre interpretado como o tipo WCHAR, mesmo quando o aplicativo de chamada define Unicode. `ld` Inteiro com sinal longo. Esse valor é equivalente a `li`. `li` Inteiro com sinal longo. Esse valor é equivalente a `ld`. `ls`, `lS` Cadeia de caracteres. Esse valor é sempre interpretado como o tipo LPWSTR, mesmo quando o aplicativo de chamada não define Unicode. Esse valor é equivalente a `ws`. `lu` Inteiro sem sinal longo. `lx`, `lX` Inteiro hexadecimal longo sem sinal em letras minúsculas ou maiúsculas. `p` Ponteiro. O endereço é impresso usando hexadecimal. `s` Cadeia de caracteres. Esse valor é interpretado como o tipo LPSTR por wsprintfA e o tipo LPWSTR por wsprintfW. Observe que wsprintf é uma macro definida como wsprintfA (Unicode não definido) ou wsprintfW (Unicode definido). `S` Cadeia de caracteres. Esse valor é interpretado como o tipo LPWSTR por wsprintfA e o tipo LPSTR por wsprintfW. Observe que wsprintf é uma macro definida como wsprintfA (Unicode não definido) ou wsprintfW (Unicode definido). `u` Argumento inteiro sem sinal. `x`, `X` Inteiro hexadecimal sem sinal em letras minúsculas ou maiúsculas.

Nota É importante observar que o wsprintf usa a convenção de chamada C (_cdecl), em vez da convenção de chamada padrão (_stdcall). Como resultado, é responsabilidade do processo de chamada tirar argumentos da pilha e os argumentos são enviados por push na pilha da direita para a esquerda. Em módulos de linguagem C, o compilador C executa essa tarefa.

Para usar buffers maiores que 1024 bytes, use _snwprintf. Para obter mais informações, consulte a documentação da biblioteca em tempo de execução C.

Observação

O cabeçalho winuser.h define wsprintf como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll