Fonction RtlUnicodeStringToUTF8String (ntifs.h)
RtlUnicodeStringToUTF8String convertit la chaîne Unicode spécifiée en chaîne UTF-8.
Syntaxe
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Paramètres
DestinationString
Pointeur vers la mémoire tampon dans laquelle la chaîne UTF-8 de sortie convertie est placée. Le champ DestinationString-MaximumLength> est défini uniquement si AllocateDestinationString a la valeur TRUE.
SourceString
Pointeur vers la chaîne Unicode à convertir en UTF-8.
AllocateDestinationString
Valeur booléenne. Lorsque la valeur est TRUE, RtlUnicodeStringToUTF8String alloue l’espace tampon pour la chaîne de destination. Seul le stockage pour DestinationString-Buffer> est alloué par cette API. Si RtlUnicodeStringToUTF8String effectue l’allocation de mémoire tampon, l’appelant doit libérer la mémoire tampon à l’aide de RtlFreeUTF8String.
Valeur retournée
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 : RtlUnicodeStringToUTF8String 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é remplacés par le caractère de remplacement Unicode, U+FFFD, avant d’être converti en UTF-8. |
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.
RtlUnicodeStringToUTF8String 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 un code de caractère valide et est remplacée par le caractère de remplacement Unicode, U+FFFD.
RtlUnicodeStringToUTF8String 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’à ce qu’elle atteigne la fin de l’espace de mémoire tampon disponible.
La routine RtlUTF8StringToUnicodeString convertit une chaîne UTF-8 en chaîne Unicode.
Vous pouvez utiliser les routines RtlUnicodeStringToUTF8String et RtlUTF8StringToUnicodeString 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 10, version 2004 |
| En-tête | ntifs.h |