Partager via

Fonction RtlUnicodeStringToUTF8String (ntifs.h)

  • Article

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

Voir aussi

RtlFreeUTF8String

RtlUTF8StringToUnicodeString