Fonction RtlUTF8StringToUnicodeString (ntifs.h)
La routine RtlUTF8StringToUnicodeString convertit la chaîne UTF-8 spécifiée en chaîne Unicode.
Syntaxe
NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
PUNICODE_STRING DestinationString,
PUTF8_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Paramètres
DestinationString
Pointeur vers la mémoire tampon dans laquelle la chaîne Unicode de sortie convertie est stockée. Le champ DestinationString->MaximumLength est défini uniquement si AllocateDestinationString a la valeur TRUE.
SourceString
Pointeur vers la chaîne source UTF-8 à convertir en Unicode.
AllocateDestinationString
Valeur booléenne. Lorsque vous définissez TRUE, RtlUTF8StringToUnicodeString alloue l’espace tampon pour la chaîne de destination. Seul le stockage pour DestinationString->Tampon est alloué par cette API. Si RtlUTF8StringToUnicodeString effectue l’allocation de mémoire tampon, l’appelant doit libérer la mémoire tampon à l’aide de RtlFreeUnicodeString.
Valeur de retour
Cette fonction retourne STATUS_SUCCESS lorsque la conversion réussit. Les codes d’erreur ou d’avertissement possibles sont les suivants :
| Code | Description |
|---|---|
| STATUS_INVALID_PARAMETERX | Erreur : l’une des valeurs de paramètre n’est pas valide. |
| STATUS_NO_MEMORY | Erreur : RtlUTF8StringToUnicodeString n’a pas pu allouer d’espace tampon. |
| STATUS_BUFFER_OVERFLOW | Avertissement : la chaîne convertie dans DestinationString->Buffer est tronquée en raison d’un espace insuffisant dans la mémoire tampon de destination. |
| STATUS_SOME_NOT_MAPPED | Avertissement : l’appel a réussi, mais un ou plusieurs caractères d’entrée n’étaient pas valides et ont été convertis par le caractère de remplacement Unicode, U+FFFD, avant d’être converti en UTF-8. |
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.
RtlUTF8StringToUnicodeString 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.
RtlUTF8StringToUnicodeString 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 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 RtlUnicodeStringToUTF8String convertit une chaîne Unicode en chaîne UTF-8.
Vous pouvez utiliser les routines RtlUTF8StringToUnicodeString et RtlUnicodeStringToUTF8String 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 10, version 2004 |
| 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 |