Funzione RtlUTF8ToUnicodeN (ntifs.h)

Articolo
03/08/2023

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

Sintassi

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Parametri

[out, optional] UnicodeStringDestination

Puntatore a un buffer di destinazione allocato dal chiamante in cui la routine scrive la stringa di output Unicode. Se questo parametro è NULL, la routine scrive le dimensioni necessarie del buffer di output in *UnicodeStringActualByteCount.

[in] UnicodeStringMaxByteCount

Specifica il numero massimo di byte a cui la routine può scrivere nel buffer a cui punta UnicodeStringDestination . Se UnicodeStringDestination = NULL, impostare UnicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

Puntatore a una posizione in cui la routine scrive il numero effettivo di byte scritti dalla routine nel buffer a cui punta UnicodeStringDestination . Se UnicodeStringDestination è diverso da NULL, questo conteggio non supera mai il valore di UnicodeStringMaxByteCount. Se UnicodeStringDestination è NULL, questo conteggio è il numero di byte necessari per contenere l'intera stringa di output.

[in] UTF8StringSource

Puntatore alla stringa di origine UTF-8.

[in] UTF8StringByteCount

Specifica il numero di byte nella stringa di origine UTF-8 a cui punta il parametro UTF8StringSource .

Valore restituito

RtlUTF8ToUnicodeN restituisce STATUS_SUCCESS se la chiamata ha esito positivo e tutti i codici di carattere UTF-8 nella stringa di input sono stati convertiti nei codici di carattere Unicode corrispondenti nella stringa di output. Restituisce STATUS_SOME_NOT_MAPPED se la chiamata ha esito positivo, ma uno o più caratteri di input non sono validi e sono stati convertiti nel carattere di sostituzione Unicode U+FFFD. I valori restituiti di errore possibili includono i codici di errore seguenti:

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Il parametro UnicodeStringMaxByteCount specifica una dimensione del buffer troppo piccola per contenere l'intera stringa di output.
STATUS_INVALID_PARAMETER	I parametri UnicodeStringDestination e UnicodeStringActualByteCount sono entrambi NULL.
STATUS_INVALID_PARAMETER_4	Il parametro UTF8StringSource è NULL.

Commenti

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

La routine restituisce STATUS_BUFFER_TOO_SMALL se il parametro UnicodeStringMaxByteCount specifica una dimensione del buffer troppo piccola per contenere l'intera stringa di output. In questo caso, la routine scrive tutti i caratteri Unicode che verranno inseriti nel buffer e il valore *UnicodeStringActualByteCount specifica il numero di byte validi scritti dalla routine nel buffer. La stringa parziale contenuta nel buffer di output potrebbe non includere un carattere Null di terminazione.

È possibile effettuare una chiamata iniziale a RtlUTF8ToUnicodeN per ottenere le dimensioni del buffer di output necessarie e quindi chiamare di nuovo RtlUTF8ToUnicodeN per ottenere la stringa di output Unicode. Nella chiamata iniziale impostare UnicodeStringDestination = NULL e UnicodeStringMaxByteCount = 0 e la routine scriverà le dimensioni del buffer necessarie in *UnicodeStringActualByteCount. Allocare quindi un buffer delle dimensioni necessarie e chiamare RtlUTF8ToUnicodeN una seconda volta per ottenere la stringa di output Unicode.

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

RtlUTF8ToUnicodeN 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 condizione che si verifichi 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 RtlUnicodeToUTF8N converte una stringa Unicode in una stringa UTF-8.

È possibile usare le routine RtlUTF8ToUnicode e RtlUnicodeToUTF8N 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 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 7
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

RtlUnicodeToUTF8N