Fonction RtlUnicodeToUTF8N (ntifs.h)

Article
06/01/2023

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 à l’appelant dans laquelle la routine écrit la chaîne de sortie UTF-8. Si ce paramètre a la valeur 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 que la routine peut écrire dans la mémoire tampon vers laquelle pointe UTF8StringDestination . 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 vers laquelle pointe UTF8StringDestination . Si UTF8StringDestination n’a pas la valeur NULL, ce nombre ne dépasse jamais la valeur de UTF8StringMaxByteCount. Si UTF8StringDestination a la valeur 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 UnicodeStringSource .

Valeur retournée

RtlUnicodeToUTF8N retourne STATUS_SUCCESS si l’appel réussit et que tous les codes 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 qu’ils ont été remplacés par le caractère de remplacement Unicode, U+FFFD, avant leur conversion en UTF-8. Les valeurs de retour d’erreur possibles incluent les codes d’erreur suivants :

Code de retour	Description
STATUS_BUFFER_TOO_SMALL	Le paramètre UTF8StringMaxByteCount spécifie une taille de mémoire tampon trop petite pour contenir la chaîne de sortie entière.
STATUS_INVALID_PARAMETER	Les paramètres UTF8StringDestination et UTF8StringActualByteCount sont tous deux NULL.
STATUS_INVALID_PARAMETER_4	Le paramètre UnicodeStringSource est NULL.
STATUS_INVALID_PARAMETER_5	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 cela convient 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 un 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 à nouveau RtlUnicodeToUTF8N pour obtenir 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 sur *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 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 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’à 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 RtlUTF8ToUnicodeN convertit une chaîne UTF-8 en chaîne Unicode.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h, Wdm.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Voir aussi

RtlUTF8ToUnicodeN