função StringCchPrintf_lW (strsafe.h)

Artigo
11/20/2024

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

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

Sintaxe

STRSAFEAPI StringCchPrintf_lW(
  [out] STRSAFE_LPWSTR                                  pszDest,
  [in]  size_t                                          cchDest,
  [in]  _Printf_format_string_params_(2)STRSAFE_LPCWSTR pszFormat,
  [in]  _locale_t                                       locale,
        ...                                             
);

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 seus argumentos.

[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.

...

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

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 StringCchPrintf_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 StringCchPrintf_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