Funzione RtlUTF8ToUnicodeN (wdm.h)
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 UnicodeStringDestination punta. Se UnicodeStringDestination = NULL, impostare UnicodeStringMaxByteCount = 0.
[out] UnicodeStringActualByteCount
Puntatore a una posizione in cui la routine scrive il numero effettivo di byte a cui la routine è stata scritta nel buffer a cui UnicodeStringDestination punta. Se UnicodeStringDestination non è 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 stati validi e sono stati convertiti nel carattere di sostituzione Unicode, U+FFFD. I valori restituiti degli errori possibili includono i codici di errore seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Il parametro UnicodeStringMaxByteCount specifica una dimensione del buffer troppo piccola per contenere l'intera stringa di output. |
|
I parametri UnicodeStringDestination e UnicodeStringActualByteCount sono entrambi NULL. |
|
Il parametro UTF8StringSource è NULL. |
Commenti
La stringa di output Unicode viene terminata solo se la stringa di input UTF-8 viene terminata con valore 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 quanti caratteri Unicode si adattano al buffer e il valore *UnicodeStringActualByteCount specifica il numero di byte validi scritti nella routine nel buffer. La stringa parziale contenuta nel buffer di output potrebbe non includere un carattere null terminante.
È 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 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.
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, 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 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 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 | Disponibile in Windows 7 e versioni successive di Windows. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Ntifs.h, Wdm.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |