função StringCchVPrintf_lA (strsafe.h)

Artigo
11/20/2024

Grava dados formatados na cadeia de caracteres especificada usando um ponteiro para uma lista de argumentos. O tamanho do buffer de destino é fornecido à função para garantir que ele não escreva após o final desse buffer.

StringCchVPrintf_l é semelhante a StringCchVPrintf, mas inclui um parâmetro para informações de localidade.

Sintaxe

STRSAFEAPI StringCchVPrintf_lA(
  [out] STRSAFE_LPSTR                                  pszDest,
  [in]  size_t                                         cchDest,
  [in]  _Printf_format_string_params_(2)STRSAFE_LPCSTR pszFormat,
  [in]  _locale_t                                      locale,
  [in]  va_list                                        argList
);

Parâmetros

[out] pszDest

O buffer de destino, que recebe a cadeia de caracteres formatada e terminada em nulo criada a partir de pszFormat e argList.

[in] cchDest

O tamanho do buffer de destino, em caracteres. Esse valor deve ser suficientemente grande para acomodar a cadeia de caracteres formatada final mais 1 para considerar o caractere nulo de terminação. O número máximo de caracteres permitido é STRSAFE_MAX_CCH.

[in] pszFormat

A cadeia de caracteres de formato. Essa cadeia de caracteres deve ser terminada em nulo. Para obter mais informações, consulte de Sintaxe de Especificação de Formato.

[in] locale

O objeto de localidade. Para obter mais informações, consulte _create_locale.

[in] argList

Os argumentos a serem inseridos na cadeia de caracteres pszFormat .

Valor de retorno

Essa função pode retornar um dos valores a seguir. É altamente recomendável que você use o bem-sucedido e macros de COM FALHA para testar o valor retornado dessa função.

Código de retorno	Descrição
S_OK	Havia espaço suficiente para que o resultado fosse copiado para pszDest sem truncamento e o buffer foi encerrado em nulo.
STRSAFE_E_INVALID_PARAMETER	O valor em cchDest é 0 ou maior que STRSAFE_MAX_CCH.
STRSAFE_E_INSUFFICIENT_BUFFER	A operação de cópia falhou devido ao espaço em buffer insuficiente. O buffer de destino contém uma versão truncada e terminada em nulo do resultado pretendido. Em situações em que o truncamento é aceitável, isso pode não ser necessariamente visto como uma condição de falha.

Observações

Para obter mais informações sobre va_lists, consulte as convenções definidas em Stdarg.h.

O comportamento será indefinido se as cadeias de caracteres apontadas por pszDest, pszFormatou quaisquer cadeias de caracteres de argumento se sobrepõem.

Nem pszFormat nem pszDest devem ser NULL. Consulte StringCchVPrintf_lEx se você precisar lidar com valores nulos de ponteiro de cadeia de caracteres.

Para usar essa função, você deve definir a macro a seguir no arquivo de cabeçalho, antes de incluir StrSafe.h.

#define STRSAFE_LOCALE_FUNCTIONS

Nota

O cabeçalho strsafe.h define StringCchVPrintf_l como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	strsafe.h

Compartilhar via