Funzione RtlUnicodeToUTF8N

Articolo
06/13/2023

Converte la stringa Unicode specificata in una nuova stringa di caratteri usando la tabella codici UTF-8 (Unicode Transformation Format) a 8 bit.

Sintassi

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

Parametri

UTF8StringDestination [out]: Puntatore a un buffer allocato dal chiamante per ricevere la stringa tradotta.
UTF8StringMaxByteCount [in]: Numero massimo di byte da scrivere in UTF8StringDestination. Se questo valore causa il troncamento della stringa tradotta, RtlUnicodeToUTF8N restituisce uno stato di errore.
UTF8StringActualByteCount [out, facoltativo]: Puntatore a una variabile allocata dal chiamante che riceve la lunghezza, in byte, della stringa tradotta. Questo parametro è facoltativo e può essere NULL. Se la stringa viene troncata, il numero restituito conta il conteggio effettivo delle stringhe troncate.
UnicodeStringSource [in]: Puntatore alla stringa di origine Unicode da tradurre.
*UnicodeStringByteCount * [in]: Specifica il numero di byte nella stringa di origine Unicode a cui punta il parametro UnicodeStringSource .

Valore restituito

RtlUnicodeToUTF8N restituisce uno dei valori NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	La stringa Unicode è stata convertita in UTF-8.
STATUS_SOME_NOT_MAPPED	È stato rilevato e sostituito un carattere di input non valido. Questo stato viene considerato uno stato di esito positivo.
STATUS_INVALID_PARAMETER	Entrambi i puntatori a UTF8StringDestination e UTF8StringActualByteCount erano NULL.
STATUS_INVALID_PARAMETER_4	UnicodeStringSource era NULL.
STATUS_BUFFER_TOO_SMALL	UTF8StringDestination è stato troncato.

Commenti

Anche se UTF8StringActualByteCount è facoltativo e può essere NULL, i chiamanti devono fornire l'archiviazione per esso, perché la lunghezza ricevuta può essere usata per determinare se la conversione è riuscita. Questa routine non modifica la stringa di origine. Restituisce una stringa UTF-8 con terminazione Null se l'oggetto UnicodeStringSource specificato includeva un terminatore NULL e se l'oggetto UTF8StringMaxByteCount specificato non causava il troncamento.

Se l'output viene troncato e viene rilevato un carattere di input non valido, la funzione restituisce STATUS_BUFFER_TOO_SMALL errore.

Se la funzione UTF8StringDestination è impostata su NULL , restituirà il numero di byte necessario per ospitare la stringa tradotta senza troncamento in UTF8StringActualByteCount.

I chiamanti di RtlUnicodeToUTF8N devono essere in esecuzione in IRQL < DISPATCH_LEVEL.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Intestazione	Wdm.h
DLL	Ntdll.dll

Vedi anche

RtlUTF8ToUnicodeN

Condividi tramite