RtlUnicodeToUTF8N, fonction (ntifs.h)
La routine RtlUnicodeToUTF8N convertit une chaîne Unicode en chaîne UTF-8.
Syntaxe
NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
[out] PCHAR UTF8StringDestination,
[in] ULONG UTF8StringMaxByteCount,
[out] PULONG UTF8StringActualByteCount,
[in] PCWCH UnicodeStringSource,
[in] ULONG UnicodeStringByteCount
);
Paramètres
[out] UTF8StringDestination
Pointeur vers une mémoire tampon de destination allouée par l’appelant dans laquelle la routine écrit la chaîne de sortie UTF-8. Si ce paramètre est NULL, la routine écrit la taille requise de la mémoire tampon de sortie dans *UTF8StringActualByteCount.
[in] UTF8StringMaxByteCount
Spécifie le nombre maximal d’octets auxquels la routine peut écrire dans la mémoire tampon qui UTF8StringDestination pointe vers. Si UTF8StringDestination = NULL, définissez UTF8StringMaxByteCount = 0.
[out] UTF8StringActualByteCount
Pointeur vers un emplacement dans lequel la routine écrit le nombre réel d’octets qu’elle a écrits dans la mémoire tampon qui UTF8StringDestination pointe vers. Si UTF8StringDestination n’est pasNULL, ce nombre ne dépasse jamais la valeur de UTF8StringMaxByteCount. Si UTF8StringDestination est NULL, ce nombre correspond au nombre d’octets requis pour contenir la chaîne de sortie entière.
[in] UnicodeStringSource
Pointeur vers la chaîne source Unicode.
[in] UnicodeStringByteCount
Spécifie le nombre d’octets dans la chaîne source Unicode vers laquelle pointe le paramètre UnicodeString Source.
Valeur de retour
RtlUnicodeToUTF8N retourne STATUS_SUCCESS si l’appel réussit et que tous les codes de caractères Unicode de la chaîne d’entrée ont été convertis en codes de caractères UTF-8 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é remplacés par le caractère de remplacement Unicode, U+FFFD, avant qu’ils ne soient convertis en UTF-8. Les valeurs de retour d’erreur possibles incluent les codes d’erreur suivants :
| Retourner le code | Description |
|---|---|
|
Le paramètre UTF8StringMaxByteCount spécifie une taille de mémoire tampon trop petite pour contenir la chaîne de sortie entière. |
|
Les paramètres UTF8StringDestination et UTF8StringActualByteCount sont tous les deux NULL. |
|
Le paramètre UnicodeStringSource est NULL. |
|
UnicodeStringByteCount n’est pas un multiple entier de sizeof(WCHAR). |
Remarques
La chaîne de sortie UTF-8 est terminée par null uniquement si la chaîne d’entrée Unicode est terminée par null.
La routine retourne STATUS_BUFFER_TOO_SMALL si le paramètre UTF8StringMaxByteCount 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 UTF-8 que prévu dans la mémoire tampon, et la valeur *UTF8StringActualByteCount 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 à RtlUnicodeToUTF8N pour obtenir la taille de mémoire tampon de sortie requise, puis appeler RtlUnicodeToUTF8N pour obtenir à nouveau la chaîne de sortie Unicode. Dans l’appel initial, définissez UTF8StringDestination = NULL et UTF8StringMaxByteCount = 0, et la routine écrit la taille de mémoire tampon requise dans *UTF8StringActualByteCount. Ensuite, allouez une mémoire tampon de la taille requise et appelez RtlUnicodeToUTF8N une deuxième fois pour obtenir la chaîne de sortie UTF-8.
RtlUnicodeToUTF8N 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 code de caractère valide et est remplacée par le caractère de remplacement Unicode, U+FFFD.
RtlUnicodeToUTF8N 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 RtlUTF8ToUnicodeN convertit une chaîne UTF-8 en chaîne Unicode.
Vous pouvez utiliser rtlUnicodeToUTF8N et routines RtlUTF8ToUnicodeN pour effectuer une conversion sans perte de chaînes de texte valides entre les formats Unicode et UTF-8. 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 |