Fonction RtlUTF8StringToUnicodeString (ntifs.h)

  • Article

La routine RtlUTF8StringToUnicodeString convertit la chaîne UTF-8 spécifiée en chaîne Unicode.

Syntaxe

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

Paramètres

DestinationString

Pointeur vers la mémoire tampon dans laquelle la chaîne Unicode de sortie convertie est stockée. Le champ DestinationString-MaximumLength> est défini uniquement si AllocateDestinationString a la valeur TRUE.

SourceString

Pointeur vers la chaîne source UTF-8 à convertir en Unicode.

AllocateDestinationString

Valeur booléenne. Lorsque la valeur est TRUE, RtlUTF8StringToUnicodeString alloue l’espace tampon pour la chaîne de destination. Seul le stockage pour DestinationString-Buffer> est alloué par cette API. Si RtlUTF8StringToUnicodeString effectue l’allocation de mémoire tampon, l’appelant doit libérer la mémoire tampon à l’aide de RtlFreeUnicodeString.

Valeur retournée

Cette fonction retourne STATUS_SUCCESS lorsque la conversion réussit. Les codes d’erreur ou d’avertissement possibles sont les suivants :

Code Description
STATUS_INVALID_PARAMETERX Erreur : l’une des valeurs de paramètre n’est pas valide.
STATUS_NO_MEMORY Erreur : RtlUTF8StringToUnicodeString n’a pas pu allouer d’espace tampon.
STATUS_BUFFER_OVERFLOW Avertissement : la chaîne convertie dans DestinationString-Buffer> est tronquée en raison d’un espace insuffisant dans la mémoire tampon de destination.
STATUS_SOME_NOT_MAPPED Avertissement : L’appel a réussi, mais un ou plusieurs caractères d’entrée n’étaient pas valides et ont été convertis par le caractère de remplacement Unicode, U+FFFD, avant d’être convertis en UTF-8.

Remarques

La chaîne de sortie Unicode est terminée par null uniquement si la chaîne d’entrée UTF-8 se termine par un caractère Null.

RtlUTF8StringToUnicodeString prend en charge les paires de substitution Unicode. Toutefois, une valeur de mot de début de substitution qui n’est pas suivie d’une valeur de mot de fin ou d’une valeur de mot de fin qui n’est pas précédée d’une valeur de mot de début n’est pas reconnue comme caractère valide et est remplacée par le caractère de remplacement Unicode, U+FFFD.

RtlUTF8StringToUnicodeString continue à convertir la chaîne d’entrée en chaîne de sortie jusqu’à ce qu’elle atteigne la fin de la mémoire tampon source ou la fin de la mémoire tampon de destination, selon la première éventualité. La routine convertit tous les caractères Null de la chaîne d’entrée en caractères Null dans la chaîne de sortie. Si la chaîne d’entrée contient un caractère null de fin, mais que le caractère Null ne se trouve pas à la fin de la mémoire tampon source, la routine continue au-delà du caractère null de fin jusqu’à ce qu’elle atteigne la fin de l’espace de mémoire tampon disponible.

La routine RtlUnicodeStringToUTF8String convertit une chaîne Unicode en chaîne UTF-8.

Vous pouvez utiliser les routines RtlUTF8StringToUnicodeString et RtlUnicodeStringToUTF8String pour effectuer une conversion sans perte de chaînes de texte valides entre les formats UTF-8 et Unicode. Toutefois, les chaînes qui ont des valeurs de données arbitraires sont susceptibles de violer les règles Unicode pour l’encodage des paires de substitution, et toutes les informations contenues dans les valeurs non valides d’une chaîne d’entrée sont perdues et ne peuvent pas être récupérées à partir de la chaîne de sortie résultante.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 10, version 2004
Plateforme cible Universal
En-tête ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Voir aussi

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String