Fonction RtlAnsiStringToUnicodeString (wdm.h)

Article
03/08/2023

RtlAnsiStringToUnicodeString convertit la chaîne source ANSI donnée en chaîne Unicode.

Syntaxe

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Paramètres

[in, out] DestinationString

Pointeur vers une structure UNICODE_STRING pour contenir la chaîne Unicode convertie. Si AllocateDestinationString a la valeur TRUE, la routine alloue une nouvelle mémoire tampon pour contenir les données de chaîne et met à jour le membre buffer de DestinationString pour qu’il pointe vers la nouvelle mémoire tampon. Sinon, la routine utilise la mémoire tampon spécifiée pour contenir la chaîne.

[in] SourceString

Pointeur vers la chaîne ANSI à convertir en Unicode.

[in] AllocateDestinationString

Spécifie si cette routine doit allouer l’espace tampon pour la chaîne de destination. Si c’est le cas, l’appelant doit libérer la mémoire tampon en appelant RtlFreeUnicodeString.

Valeur retournée

Si la conversion réussit, RtlAnsiStringToUnicodeString retourne STATUS_SUCCESS. En cas d’échec, la routine n’alloue pas de mémoire.

Remarques

La traduction est conforme aux informations de paramètres régionaux système actuelles.

Si l’appelant définit AllocateDestinationString sur TRUE, la routine remplace le membre Buffer de DestinationString par un pointeur vers la mémoire tampon qu’il alloue. L’ancienne valeur peut être remplacée même lorsque la routine retourne une erreur status code.

Cette routine n’est pas déclarée dans un fichier d’en-tête. Toutefois, vous pouvez copier la déclaration suivante dans votre code source :

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Vous pouvez utiliser les routines suivantes pour convertir des caractères d’un octet et de deux octets en caractères Unicode :

Pour plus d’informations sur ces routines et d’autres routines de gestion de chaînes, consultez Routines de la bibliothèque d’exécution (RTL).

RtlAnsiCharToUnicodeChar présente des problèmes de sécurité. Envisagez plutôt d’utiliser la routine RtlAnsiStringToUnicodeString .

Si, lors de l’entrée, *SourceCharacter pointe vers une mémoire tampon d’un octet qui contient le premier octet d’un code de caractère de deux octets, RtlAnsiCharToUnicodeChar exécute la mémoire tampon lorsqu’elle tente de lire le deuxième octet.

Au démarrage du système, le système d’exploitation détermine la langue de l’utilisateur à partir des paramètres régionaux et installe la page de code ANSI du système appropriée. RtlAnsiCharToUnicodeChar utilise cette page de code pour convertir un caractère d’un octet ou d’un double octet en caractère Unicode correspondant.

Si la page de code ANSI système définit un jeu de caractères sur un seul octet (autrement dit, le jeu de caractères ANSI), RtlAnsiCharToUnicodeChar accélère l’opération de conversion en supprimant simplement un caractère ANSI dans la plage 0x00 à 0x7f pour produire le caractère Unicode correspondant. La routine convertit la valeur ANSI 0x5c en la barre oblique inverse (« \ »), même si la page de code sur un octet définit ce caractère comme signe yen.

Si, lors de l’entrée, *SourceCharacter pointe vers un code de caractère non valide, RtlAnsiCharToUnicodeChar retourne le code de caractère d’espace Unicode, 0x0020. La liste suivante présente des exemples de codes caractères non valides :

Le premier octet du code de caractère est une valeur valide uniquement en tant que deuxième octet d’un code de caractère de deux octets.
Le deuxième octet d’un code de caractère de deux octets est une valeur valide uniquement comme premier octet.