Função RtlUnicodeStringToInteger (wdm.h)

  • Artigo

A rotina RtlUnicodeStringToInteger converte uma representação de cadeia de caracteres Unicode de um número no valor inteiro equivalente.

Sintaxe

NTSYSAPI NTSTATUS RtlUnicodeStringToInteger(
  [in]           PCUNICODE_STRING String,
  [in, optional] ULONG            Base,
  [out]          PULONG           Value
);

Parâmetros

[in] String

Um ponteiro para uma estrutura UNICODE_STRING que contém a representação numérica a ser convertida no valor inteiro equivalente.

[in, optional] Base

Um valor numérico que indica a base (ou radix) do número que a cadeia de caracteres Unicode representa. Esse valor de parâmetro é opcional e pode ser definido como zero.

Se Base for zero, RtlUnicodeStringToInteger verificará o prefixo da cadeia de caracteres Unicode para determinar a base do número:

  • Se o prefixo for "0x", RtlUnicodeStringToInteger interpretará o número na cadeia de caracteres como um inteiro hexadecimal.

  • Se o prefixo for "0o", RtlUnicodeStringToInteger interpretará o número na cadeia de caracteres como um inteiro octal.

  • Se o prefixo for "0b", RtlUnicodeStringToInteger interpretará o número na cadeia de caracteres como um inteiro binário.

Se a cadeia de caracteres Unicode não contiver nenhum desses prefixos, RtlUnicodeStringToInteger tratará a cadeia de caracteres como um inteiro de base 10.

[out] Value

Um ponteiro para uma variável ULONG na qual RtlUnicodeStringToInteger grava o valor inteiro resultante da conversão da cadeia de caracteres Unicode.

Retornar valor

Se a conversão for bem-sucedida, a rotina RtlUnicodeStringToInteger retornará STATUS_SUCCESS e definirá *Value como o valor inteiro representado pelo número na cadeia de caracteres Unicode. Se a cadeia de caracteres não estiver vazia, mas não começar com uma representação de número válida, a rotina retornará STATUS_SUCCESS e definirá *Value como zero. Se a cadeia de caracteres estiver vazia, a rotina falhará e retornará STATUS_INVALID_PARAMETER.

Comentários

Essa rotina ignora qualquer espaço em branco no início da cadeia de caracteres de entrada para localizar o início do número.

Se o primeiro caractere de espaço não branco na cadeia de caracteres for um hífen (-), o valor inteiro gravado em *Value será negativo; caso contrário, se o primeiro caractere for um "+" ou não houver nenhum caractere de sinal, o valor inteiro gravado em *Value será positivo.

Se a cadeia de caracteres não contiver um número válido ou se o primeiro dígito na cadeia de caracteres for precedido por um caractere de espaço não branco diferente de '+' ou '-', a rotina definirá o valor de saída como zero e retornará STATUS_SUCCESS.

Uma subcadeia de caracteres que contém um ou mais dígitos válidos é encerrada por qualquer caractere que não seja um dígito válido. Por exemplo, se Base = 2, os dígitos válidos serão '0' e '1'. Se Base = 8, os dígitos válidos serão '0' a '7'. Se Base = 10, os dígitos válidos serão '0' a '9'. Se Base = 16, os dígitos válidos serão '0' a '9', 'a' a 'f' e 'A' a 'F'.

A tabela a seguir contém exemplos de valores de saída resultantes de várias combinações de cadeias de caracteres de entrada e valores de parâmetro base .

Cadeia de caracteres de entrada Base Valor de saída
"123" 10 123
"-345" 10 -345
"xyz" 10 0
"+678abc" 10 678
"+678abc" 16 6785724
"007" 10 7
"789" 8 7
"FGH" 16 15
" " 10 0

Uma rotina relacionada, RtlIntegerToUnicodeString, converte um valor inteiro na representação de cadeia de caracteres Unicode equivalente.

Requisitos

Requisito Valor
Plataforma de Destino Universal
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
Biblioteca NtosKrnl.lib (modo kernel); Ntdll.lib (modo de usuário)
DLL NtosKrnl.exe (modo kernel); Ntdll.dll (modo de usuário)
IRQL PASSIVE_LEVEL

Confira também

RtlIntegerToUnicodeString

UNICODE_STRING