RtlUTF8ToUnicodeN, fonction (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 par l’appelant dans laquelle la routine écrit la chaîne de sortie Unicode. Si ce paramètre est 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 auxquels la routine peut écrire dans la mémoire tampon qui UnicodeStringDestination pointe vers. Si UnicodeStringDestination = NULL, définissez UnicodeStringMaxByteCount = 0.
[out] UnicodeStringActualByteCount
Pointeur vers un emplacement dans lequel la routine écrit le nombre réel d’octets dans lequel la routine a écrit dans la mémoire tampon qui UnicodeStringDestination pointe vers. Si UnicodeStringDestination n’est pasNULL, ce nombre ne dépasse jamais la valeur de UnicodeStringMaxByteCount. Si UnicodeStringDestination est 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 de retour
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’ont pas été 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 :
| Retourner le code | 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 les deux NULL. |
|
Le paramètre UTF8StringSource est 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 que prévu 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 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 RtlUTF8ToUnicodeN pour obtenir à nouveau 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 sur *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 un 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’à atteindre la fin de la mémoire tampon source ou la fin de la mémoire tampon de destination, selon ce qui se produit en premier. La routine convertit 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 n’est pas situé à la fin de la mémoire tampon source, la routine passe au-delà du caractère null de fin jusqu’à ce qu’elle atteigne 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 RtlUTF8ToUnicodeN 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 7 |
| plateforme cible | Universel |
| d’en-tête | ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |