Fonction RtlUnicodeToUTF8N

Article
06/13/2023

Convertit la chaîne Unicode spécifiée en nouvelle chaîne de caractères, à l’aide de la page de codes UTF-8 (Unicode Transformation Format) 8 bits.

Syntaxe

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

Paramètres

UTF8StringDestination [out]: Pointeur vers une mémoire tampon allouée à l’appelant pour recevoir la chaîne traduite.
UTF8StringMaxByteCount [in]: Nombre maximal d’octets à écrire dans UTF8StringDestination. Si cette valeur entraîne la troncation de la chaîne traduite, RtlUnicodeToUTF8N renvoie une erreur status.
UTF8StringActualByteCount [out, facultatif]: Pointeur vers une variable allouée par l’appelant qui reçoit la longueur, en octets, de la chaîne traduite. Ce paramètre est facultatif et peut être NULL. Si la chaîne est tronquée, le nombre retourné compte le nombre réel de chaînes tronquées.
UnicodeStringSource [in]: Pointeur vers la chaîne source Unicode à traduire.
*UnicodeStringByteCount * [in]: Spécifie le nombre d’octets dans la chaîne source Unicode vers laquelle pointe le paramètre UnicodeStringSource .

Valeur retournée

RtlUnicodeToUTF8N retourne l’une des valeurs NTSTATUS suivantes :

Code de retour	Description
STATUS_SUCCESS	La chaîne Unicode a été convertie en UTF-8.
STATUS_SOME_NOT_MAPPED	Un caractère d’entrée non valide a été rencontré et remplacé. Cette status est considérée comme un succès status.
STATUS_INVALID_PARAMETER	Les deux pointeurs vers UTF8StringDestination et UTF8StringActualByteCount étaient NULL.
STATUS_INVALID_PARAMETER_4	UnicodeStringSource a la valeur NULL.
STATUS_BUFFER_TOO_SMALL	UTF8StringDestination a été tronqué.

Notes

Bien que UTF8StringActualByteCount soit facultatif et puisse avoir la valeur NULL, les appelants doivent fournir un stockage pour celui-ci, car la longueur reçue peut être utilisée pour déterminer si la conversion a réussi. Cette routine ne modifie pas la chaîne source. Elle retourne une chaîne UTF-8 terminée par une valeur Null si la chaîne UnicodeStringSource donnée incluait un terminateur NULL et si la chaîne UTF8StringMaxByteCount donnée n’a pas causé de troncation.

Si la sortie est tronquée et qu’un caractère d’entrée non valide est rencontré, la fonction retourne STATUS_BUFFER_TOO_SMALL erreur.

Si UTF8StringDestination est défini sur NULL , la fonction retourne le nombre d’octets requis pour héberger la chaîne traduite sans troncation dans UTF8StringActualByteCount.

Les appelants de RtlUnicodeToUTF8N doivent être en cours d’exécution au DISPATCH_LEVEL IRQL < .

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
En-tête	Wdm.h
DLL	Ntdll.dll

Voir aussi

RtlUTF8ToUnicodeN

Partager via