Função RtlStringCbLengthW (ntstrsafe.h)

Artigo
02/07/2025

As funções RtlStringCbLengthW e RtlStringCbLengthA determinam o comprimento, em bytes, de uma cadeia de caracteres fornecida.

Sintaxe

NTSTRSAFEDDI RtlStringCbLengthW(
  [in] STRSAFE_PCNZWCH psz,
  [in] size_t          cbMax,
       size_t          *pcbLength
);

Parâmetros

[in] psz

Um ponteiro para um buffer que contém uma cadeia de caracteres terminada em nulo, do qual o comprimento será verificado.

[in] cbMax

O número máximo de bytes permitidos no buffer apontado por psz, incluindo o caractere nulo de encerramento.

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

pcbLength

Se o chamador fornecer um ponteiro de endereço NULLnão, a função carregará o endereço com o comprimento, em bytes, da cadeia de caracteres contida no buffer. O comprimento não inclui o caractere nulo de terminação da cadeia de caracteres.

Valor de retorno

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 a cadeia de caracteres em psz não foi NULL e o comprimento da cadeia de caracteres (incluindo o caractere nulo de terminação) é menor ou igual a caracteres cbMax.
STATUS_INVALID_PARAMETER	Esse status de erro significa que o valor em psz é NULL, cbMax é maior que NTSTRSAFE_MAX_CCH * sizeof(TCHAR) ou psz é maior que cbMax.

Observações

rtlStringCbLengthW e rtlStringCbLengthA devem ser usados em vez de strlen. Use essas funções para garantir que uma cadeia de caracteres não seja maior do que um determinado comprimento, em bytes. Se essa condição for atendida, RtlStringCbLengthW e RtlStringCbLengthA retornará o comprimento atual da cadeia de caracteres em bytes, não incluindo os bytes usados para encerrar o caractere nulo.

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

Tipo de dados de cadeia de caracteres	Literal de cadeia de caracteres	Função
WCHAR	L"string"	rtlStringCbLengthW
char	"string"	rtlStringCbLengthA

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
de cliente com suporte mínimo	Disponível no Windows XP com Service Pack 1 (SP1) e versões posteriores do Windows.
da Plataforma de Destino	Área de trabalho
cabeçalho	ntstrsafe.h (inclua Ntstrsafe.h)
biblioteca	Ntstrsafe.lib
IRQL	Se as cadeias de caracteres que estão sendo manipuladas estiverem sempre residentes na memória, caso contrário, PASSIVE_LEVEL

Consulte também

rtlStringCchLength

Partilhar via