Funzione RtlUnicodeToUTF8N (ntifs.h)

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 punta UTF8StringDestination . 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 a cui punta UTF8StringDestination . Se UTF8StringDestination non è NULL, questo conteggio non supera mai il valore di UTF8StringMaxByteCount. Se UTF8StringDestination è NULL, questo conteggio corrisponde al 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 di 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 valori restituiti di errore possibili 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 UTF8StringActualByteCount sono entrambi NULL.
STATUS_INVALID_PARAMETER_4	Il parametro UnicodeStringSource è NULL.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount non è un multiplo intero di sizeof(WCHAR).

Commenti

La stringa di output UTF-8 è con terminazione 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 tutti i 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 di nuovo RtlUnicodeToUTF8N 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 su *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 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.

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

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

RtlUTF8ToUnicodeN