Fonction RtlUTF8StringToUnicodeString (ntifs.h)

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 :

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

Voir aussi

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String