Fonction RtlUTF8ToUnicodeN (ntifs.h)

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

Syntaxe

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Paramètres

[out, optional] UnicodeStringDestination

Pointeur vers une mémoire tampon de destination allouée à l’appelant dans laquelle la routine écrit la chaîne de sortie Unicode. Si ce paramètre a la valeur NULL, la routine écrit la taille requise de la mémoire tampon de sortie dans *UnicodeStringActualByteCount.

[in] UnicodeStringMaxByteCount

Spécifie le nombre maximal d’octets que la routine peut écrire dans la mémoire tampon vers laquelle pointe UnicodeStringDestination . Si UnicodeStringDestination = NULL, définissez UnicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

Pointeur vers un emplacement dans lequel la routine écrit le nombre réel d’octets que la routine a écrits dans la mémoire tampon vers laquelle pointe UnicodeStringDestination . Si UnicodeStringDestination n’a pas la valeur NULL, ce nombre ne dépasse jamais la valeur d’UnicodeStringMaxByteCount. Si UnicodeStringDestination a la valeur NULL, ce nombre correspond au nombre d’octets requis pour contenir la chaîne de sortie entière.

[in] UTF8StringSource

Pointeur vers la chaîne source UTF-8.

[in] UTF8StringByteCount

Spécifie le nombre d’octets dans la chaîne source UTF-8 vers laquelle pointe le paramètre UTF8StringSource .

Valeur retournée

RtlUTF8ToUnicodeN retourne STATUS_SUCCESS si l’appel réussit et que tous les codes de caractères UTF-8 de la chaîne d’entrée ont été convertis en codes de caractères Unicode correspondants dans la chaîne de sortie. Elle retourne STATUS_SOME_NOT_MAPPED si l’appel réussit, mais qu’un ou plusieurs caractères d’entrée n’étaient pas valides et ont été convertis en caractère de remplacement Unicode, U+FFFD. Les valeurs de retour d’erreur possibles incluent les codes d’erreur 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.

La routine retourne STATUS_BUFFER_TOO_SMALL si le paramètre UnicodeStringMaxByteCount spécifie une taille de mémoire tampon trop petite pour contenir la chaîne de sortie entière. Dans ce cas, la routine écrit autant de caractères Unicode que la mémoire tampon, et la valeur *UnicodeStringActualByteCount spécifie le nombre d’octets valides que la routine a écrits dans la mémoire tampon. La chaîne partielle contenue dans la mémoire tampon de sortie peut ne pas inclure de caractère null de fin.

Vous pouvez effectuer un appel initial à RtlUTF8ToUnicodeN pour obtenir la taille de mémoire tampon de sortie requise, puis appeler à nouveau RtlUTF8ToUnicodeN pour obtenir la chaîne de sortie Unicode. Dans l’appel initial, définissez UnicodeStringDestination = NULL et UnicodeStringMaxByteCount = 0, et la routine écrit la taille de mémoire tampon requise dans *UnicodeStringActualByteCount. Ensuite, allouez une mémoire tampon de la taille requise et appelez RtlUTF8ToUnicodeN une deuxième fois pour obtenir la chaîne de sortie Unicode.

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

RtlUTF8ToUnicodeN continue de 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 RtlUnicodeToUTF8N convertit une chaîne Unicode en chaîne UTF-8.

Vous pouvez utiliser les routines RtlUTF8ToUnicode et RtlUnicodeToUTF8N 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

RtlUnicodeToUTF8N