Funzione RtlUnicodeStringToUTF8String (ntifs.h)

  • Articolo

RtlUnicodeStringToUTF8String converte la stringa Unicode specificata in una stringa UTF-8.

Sintassi

NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
  PUTF8_STRING     DestinationString,
  PCUNICODE_STRING SourceString,
  BOOLEAN          AllocateDestinationString
);

Parametri

DestinationString

Puntatore al buffer in cui viene inserita la stringa UTF-8 di output convertita. Il campo DestinationString-MaximumLength> viene impostato solo se AllocateDestinationString è TRUE.

SourceString

Puntatore alla stringa Unicode da convertire in UTF-8.

AllocateDestinationString

. Quando si imposta TRUE, RtlUnicodeStringToUTF8String alloca lo spazio buffer per la stringa di destinazione. Questa API consente di allocare solo l'archiviazione per DestinationString-Buffer>. Se RtlUnicodeStringToUTF8String esegue l'allocazione del buffer, il chiamante deve deallocare il buffer usando RtlFreeUTF8String.

Valore restituito

Questa funzione restituisce STATUS_SUCCESS quando la conversione ha esito positivo. I codici di avviso o di errore possibili includono:

Codice Descrizione
STATUS_INVALID_PARAMETERX Errore: uno dei valori dei parametri non è valido.
STATUS_NO_MEMORY Errore: RtlUnicodeStringToUTF8String non è riuscito ad allocare spazio buffer.
STATUS_BUFFER_OVERFLOW Avviso: la stringa convertita in DestinationString-Buffer> viene troncata a causa di spazio insufficiente nel buffer di destinazione.
STATUS_SOME_NOT_MAPPED Avviso: la chiamata ha avuto esito positivo, ma uno o più caratteri di input non sono validi e sono stati sostituiti dal carattere di sostituzione Unicode U+FFFD, prima di essere convertito in UTF-8.

Commenti

La stringa di output UTF-8 è con terminazione Null solo se la stringa di input Unicode è con terminazione Null.

RtlUnicodeStringToUTF8String supporta coppie di surrogati Unicode. Tuttavia, un valore di parola iniziale surrogato non seguito da un valore di parola finale o da un valore di parola finale non preceduto da un valore di parola iniziale, non viene riconosciuto come codice carattere valido e viene sostituito dal carattere di sostituzione Unicode, U+FFFD.

RtlUnicodeStringToUTF8String continua a convertire la stringa di input in una stringa di output fino a raggiungere la fine del buffer di origine o la fine del buffer di destinazione, a seconda di quale condizione si verifica per prima. La routine converte tutti i caratteri Null nella stringa di input in caratteri Null nella stringa di output. Se la stringa di input contiene un carattere Null di terminazione, ma il carattere Null non si trova alla fine del buffer di origine, la routine continua oltre il carattere Null di terminazione fino a raggiungere la fine dello spazio del buffer disponibile.

La routine RtlUTF8StringToUnicodeString converte una stringa UTF-8 in una stringa Unicode.

È possibile usare le routine RtlUnicodeStringToUTF8String e RtlUTF8StringToUnicodeString per eseguire una conversione senza perdita di stringhe di testo valide tra i formati Unicode e UTF-8. Tuttavia, le stringhe con valori di dati arbitrari violano le regole Unicode per la codifica delle coppie di surrogati e le informazioni contenute nei valori non validi in una stringa di input vengono perse e non possono essere recuperate dalla stringa di output risultante.

Requisiti

Requisito Valore
Client minimo supportato Windows 10, versione 2004
Intestazione ntifs.h

Vedi anche

RtlFreeUTF8String

RtlUTF8StringToUnicodeString