Funzione RtlUTF8StringToUnicodeString (ntifs.h)

  • Articolo

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

Sintassi

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

Parametri

DestinationString

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

SourceString

Puntatore alla stringa di origine UTF-8 da convertire in Unicode.

AllocateDestinationString

. Quando si imposta TRUE, RtlUTF8StringToUnicodeString alloca lo spazio del buffer per la stringa di destinazione. Solo l'archiviazione per DestinationString-Buffer> viene allocata da questa API. Se RtlUTF8StringToUnicodeString esegue l'allocazione del buffer, il chiamante deve deallocare il buffer usando RtlFreeUnicodeString.

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: RtlUTF8StringToUnicodeString non è stato in grado di allocare spazio del 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 convertiti dal carattere di sostituzione Unicode, U+FFFD, prima di essere convertito in UTF-8.

Commenti

La stringa di output Unicode viene terminata solo se la stringa di input UTF-8 viene terminata con valore Null.

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

RtlUTF8StringToUnicodeString 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, che si verifica 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 terminante, ma il carattere Null non si trova alla fine del buffer di origine, la routine continua oltre il carattere Null terminante fino a raggiungere la fine dello spazio del buffer disponibile.

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

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

Requisiti

Requisito Valore
Client minimo supportato Windows 10, versione 2004
Piattaforma di destinazione Universale
Intestazione ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h)
Libreria NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Vedi anche

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String