Função RtlOemToUnicodeN (ntifs.h)

Artigo
08/07/2023

A rotina RtlOemToUnicodeN converte a cadeia de caracteres de origem especificada em uma cadeia de caracteres Unicode, usando a página de código OEM do sistema atual.

Sintaxe

NTSYSAPI NTSTATUS RtlOemToUnicodeN(
  [out]           PWCH   UnicodeString,
  [in]            ULONG  MaxBytesInUnicodeString,
  [out, optional] PULONG BytesInUnicodeString,
  [in]            PCCH   OemString,
  [in]            ULONG  BytesInOemString
);

Parâmetros

[out] UnicodeString

Ponteiro para um buffer alocado pelo chamador que recebe a cadeia de caracteres traduzida.

[in] MaxBytesInUnicodeString

Número máximo de bytes a serem gravados em UnicodeString. Se esse valor fizer com que a cadeia de caracteres traduzida seja truncada, RtlOemToUnicodeN não retornará um erro status.

[out, optional] BytesInUnicodeString

Ponteiro para uma variável alocada pelo chamador que recebe o comprimento, em bytes, da cadeia de caracteres traduzida. Este parâmetro pode ser NULL.

[in] OemString

Ponteiro para a cadeia de caracteres de origem OEM a ser convertida em Unicode. Se a página de código atual descrever um conjunto de caracteres de byte único, esse ponteiro poderá ser o mesmo endereço que UnicodeString.

[in] BytesInOemString

Comprimento, em bytes, da cadeia de caracteres em OemString.

Retornar valor

RtlOemToUnicodeN retornará STATUS_SUCCESS se a cadeia de caracteres completa em OemString tiver sido convertida com êxito e retornada em UnicodeString. Caso contrário, ele poderá retornar STATUS_BUFFER_OVERFLOW se a cadeia de caracteres de destino precisar ser truncada para se ajustar ao MaxBytesInUnicodeString especificado. STATUS_BUFFER_OVERFLOW é um valor NTSTATUS de aviso.

Comentários

RtlOemToUnicodeN dá suporte apenas a caracteres Unicode pré-compilados mapeados para a página de código OEM do sistema atual instalada no momento da inicialização do sistema.

Se a página de código do sistema atual definir um conjunto de caracteres de byte único, todos os caracteres de byte único no intervalo 0x00 para 0x7f serão simplesmente estendidos zero na cadeia de caracteres Unicode correspondente para acelerar a operação de conversão. O valor do caractere 0x5c em uma página de código desse tipo é traduzido para o caractere de barra invertida, mesmo que a página de código atual defina esse caractere como o sinal de Yen.

Para o valor retornado STATUS_SUCCESS, o valor de BytesInUnicodeString, se houver, indica o comprimento da cadeia de caracteres Unicode retornada, em vez do MaxBytesInUnicodeString fornecido.

Essa rotina não modifica a cadeia de caracteres de origem, a menos que os ponteiros UnicodeString e OemString sejam equivalentes. A cadeia de caracteres Unicode retornada será terminada em nulo se não estiver truncada.

Para obter informações sobre outras rotinas de tratamento de cadeia de caracteres, consulte Rotinas rtl (biblioteca em tempo de execução).