Funzione RtlUnicodeToUTF8N (ntifs.h)

Articolo
11/08/2024

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

Sintassi

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

Parametri

[out] UTF8StringDestination

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

[in] UTF8StringMaxByteCount

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

[out] UTF8StringActualByteCount

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

[in] UnicodeStringSource

Puntatore alla stringa di origine Unicode.

[in] UnicodeStringByteCount

Specifica il numero di byte nella stringa di origine Unicode a cui punta il parametro UnicodeStringSource.

Valore restituito

RtlUnicodeToUTF8N restituisce STATUS_SUCCESS se la chiamata ha esito positivo e tutti i codici carattere Unicode nella stringa di input sono stati convertiti nei codici di carattere UTF-8 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 sostituiti dal carattere di sostituzione Unicode U+FFFD, prima che siano stati convertiti in UTF-8. I possibili valori restituiti dall'errore includono i codici di errore seguenti:

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Il parametro UTF8StringMaxByteCount specifica una dimensione del buffer troppo piccola per contenere l'intera stringa di output.
STATUS_INVALID_PARAMETER	I parametri UTF8StringDestination e UTF8StringActualByte Count sono entrambi NULL.
STATUS_INVALID_PARAMETER_4	Il parametro UnicodeStringSource è NULL.
STATUS_INVALID_PARAMETER_5	unicodeStringByteCount non è un multiplo intero di sizeof(WCHAR).

Osservazioni

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

La routine restituisce STATUS_BUFFER_TOO_SMALL se il parametro UTF8StringMaxByteCount specifica una dimensione del buffer troppo piccola per contenere l'intera stringa di output. In questo caso, la routine scrive il numero di caratteri UTF-8 che verranno inseriti nel buffer e il valore *UTF8StringActualByteCount 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 RtlUnicodeToUTF8N per ottenere le dimensioni del buffer di output necessarie e quindi chiamare RtlUnicodeToUTF8N di nuovo per ottenere la stringa di output Unicode. Nella chiamata iniziale impostare UTF8StringDestination = NULL e UTF8StringMaxByteCount = 0 e la routine scriverà le dimensioni del buffer necessarie in *UTF8StringActualByteCount. Allocare quindi un buffer delle dimensioni necessarie e chiamare RtlUnicodeToUTF8N una seconda volta per ottenere la stringa di output UTF-8.

RtlUnicodeToUTF8N supporta coppie di surrogati Unicode. Tuttavia, un valore di parola iniziale surrogato che 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 codice carattere valido e viene sostituito dal carattere di sostituzione Unicode, U+FFFD.

RtlUnicodeToUTF8N continua a convertire la stringa di input in una stringa di output finché non raggiunge 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 RtlUTF8ToUnicodeN converte una stringa UTF-8 in una stringa Unicode.

È possibile usare routine RtlUnicodeToUTF8N e RtlUTF8ToUnicodeN 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 tutte le informazioni contenute nei valori non validi in una stringa di input vengono perse e non possono essere recuperate dalla stringa di output risultante.

Fabbisogno

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

Vedere anche

RtlUTF8ToUnicodeN

Condividi tramite