Fonction RtlUTF8ToUnicodeN (wdm.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 écrit 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 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 :
| Code de retour | Description |
|---|---|
|
Le paramètre UnicodeStringMaxByteCount spécifie une taille de mémoire tampon trop petite pour contenir la chaîne de sortie entière. |
|
Les paramètres UnicodeStringDestination et UnicodeStringActualByteCount sont tous deux NULL. |
|
Le paramètre UTF8StringSource a la valeur NULL. |
Remarques
La chaîne de sortie Unicode est terminée par null uniquement si la chaîne d’entrée UTF-8 est terminée par 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 qu’il convient dans 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 un 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 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 en tant que 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’à atteindre la fin de l’espace 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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows 7 et versions ultérieures de Windows. |
| Plateforme cible | Universal |
| En-tête | wdm.h (inclure Ntifs.h, Wdm.h, Ntifs.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |