Função RtlStringCbVPrintfW (ntstrsafe.h)

  • Artigo

As funções RtlStringCbVPrintfW e RtlStringCbVPrintfA criam uma cadeia de caracteres de texto contada por bytes, com formatação baseada em informações de formatação fornecidas.

Sintaxe

NTSTRSAFEDDI RtlStringCbVPrintfW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cbDest,
  [in]  NTSTRSAFE_PCWSTR pszFormat,
  [in]  va_list          argList
);

Parâmetros

[out] pszDest

Um ponteiro para um buffer fornecido pelo chamador que recebe uma cadeia de caracteres formatada e terminada em nulo. A função cria essa cadeia de caracteres a partir da cadeia de caracteres de formatação fornecida por pszFormat e dos argumentos fornecidos por argList.

[in] cbDest

O tamanho do buffer de destino, em bytes. O buffer deve ser grande o suficiente para conter a cadeia de caracteres formatada mais o caractere nulo de terminação.

Para cadeias de caracteres Unicode, o número máximo de bytes é NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

Para cadeias de caracteres ANSI, o número máximo de bytes é NTSTRSAFE_MAX_CCH * sizeof(char).

[in] pszFormat

Um ponteiro para uma cadeia de caracteres de texto terminada em nulo que contém diretivas de formatação com estiloprintf.

[in] argList

Uma lista de argumentos com tipo va_list. Os argumentos contidos na lista de argumentos serão interpretados usando a cadeia de caracteres de formatação fornecida pelo pszFormat.

Retornar valor

A função retorna um dos valores NTSTATUS listados na tabela a seguir. Para obter informações sobre como testar valores NTSTATUS, consulte Usando valores NTSTATUS.

Código de retorno Descrição
STATUS_SUCCESS
 Esse êxito status significa que os dados de origem estavam presentes, a cadeia de caracteres de saída foi criada sem truncamento e o buffer de destino resultante foi encerrado em nulo.
STATUS_BUFFER_OVERFLOW
 Esse aviso status significa que a operação não foi concluída devido a espaço insuficiente no buffer de destino. O buffer de destino contém uma versão truncada da cadeia de caracteres criada.
STATUS_INVALID_PARAMETER
 Esse erro status significa que a função recebeu um parâmetro de entrada inválido. Para obter mais informações, consulte o parágrafo a seguir.

A função retorna o valor STATUS_INVALID_PARAMETER quando:

  • O valor em cbDest é maior que o tamanho máximo do buffer.
  • O buffer de destino já estava cheio.
  • Um ponteiro NULL estava presente.
  • O comprimento do buffer de destino era zero, mas uma cadeia de caracteres de origem de comprimento diferente de zero estava presente.

Comentários

RtlStringCbVPrintfW e RtlStringCbVPrintfA devem ser usados em vez das seguintes funções:

  • vsprintf
  • vswprintf
  • _vsnprintf
  • _vsnwprintf
Todas essas funções aceitam uma cadeia de caracteres de formato, juntamente com um conjunto de argumentos em uma lista de argumentos com tipo va_list e retornam uma cadeia de caracteres formatada. O tamanho, em bytes, do buffer de destino é fornecido a RtlStringCbVPrintfW e RtlStringCbVPrintfA para garantir que eles não escrevam após o final do buffer.

Para obter mais informações sobre listas de argumentos com tipo va_list, consulte a documentação do SDK do Microsoft Windows.

Use RtlStringCbVPrintfW para manipular cadeias de caracteres Unicode e RtlStringCbVPrintfA para manipular cadeias de caracteres ANSI. O formulário usado depende de seus dados, conforme mostrado na tabela a seguir.

Tipos de dados de cadeia de caracteres Cadeia de caracteres literal Função
WCHAR L"string" RtlStringCbVPrintfW
char “cadeia de caracteres” RtlStringCbVPrintfA
 

Se pszDest e pszFormat apontarem para cadeias de caracteres sobrepostas ou se alguma cadeia de caracteres de argumento se sobrepor, o comportamento da função será indefinido.

Nem pszFormat nem pszDest devem ser NULL. Se você precisar manipular valores de ponteiro de cadeia de caracteres NULL , use RtlStringCbVPrintfEx.

Para obter mais informações sobre as funções de cadeia de caracteres seguras, consulte Usando funções de cadeia de caracteres seguras.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows XP com Service Pack 1 (SP1).
Plataforma de Destino Área de Trabalho
Cabeçalho ntstrsafe.h (inclua Ntstrsafe.h)
Biblioteca Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Confira também

RtlStringCbPrintf

RtlStringCbVPrintfEx

RtlStringCchVPrintf