Funzione RtlAnsiStringToUnicodeString (wdm.h)

Articolo
03/08/2023

RtlAnsiStringToUnicodeString converte la stringa di origine ANSI specificata in una stringa Unicode.

Sintassi

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Parametri

[in, out] DestinationString

Puntatore a una struttura UNICODE_STRING per contenere la stringa Unicode convertita. Se AllocateDestinationString è TRUE, la routine alloca un nuovo buffer per contenere i dati stringa e aggiorna il membro Buffer di DestinationString in modo che punti al nuovo buffer. In caso contrario, la routine usa il buffer attualmente specificato per contenere la stringa.

[in] SourceString

Puntatore alla stringa ANSI da convertire in Unicode.

[in] AllocateDestinationString

Specifica se questa routine deve allocare lo spazio del buffer per la stringa di destinazione. In caso affermativo, il chiamante deve deallocare il buffer chiamando RtlFreeUnicodeString.

Valore restituito

Se la conversione ha esito positivo, RtlAnsiStringToUnicodeString restituisce STATUS_SUCCESS. In caso di errore, la routine non alloca memoria.

Commenti

La traduzione è conforme alle informazioni sulle impostazioni locali di sistema correnti.

Se il chiamante imposta AllocateDestinationString su TRUE, la routine sostituisce il membro Buffer di DestinationString con un puntatore al buffer allocato. Il valore precedente può essere sovrascritto anche quando la routine restituisce un codice di stato di errore.

Questa routine non viene dichiarata in un file di intestazione. Tuttavia, è possibile copiare la dichiarazione seguente nel codice sorgente:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

È possibile utilizzare le routine seguenti per convertire caratteri a byte singolo e a byte doppio in caratteri Unicode:

Per altre informazioni su queste e altre routine di gestione delle stringhe, vedere Routine RTL (Run-Time Library).

RtlAnsiCharToUnicodeChar presenta carenze di sicurezza. È consigliabile usare invece la routine RtlAnsiStringToUnicodeString .

Se, nella voce , *SourceCharacter punta a un buffer a un byte che contiene il primo byte di un codice di caratteri a due byte, RtlAnsiCharToUnicodeChar esegue l'overrun del buffer quando tenta di leggere il secondo byte.

All'avvio del sistema operativo, il sistema operativo determina la lingua dell'utente dalle impostazioni locali e installa la tabella codici ANSI di sistema appropriata. RtlAnsiCharChar usa questa tabella codici per convertire un carattere a byte singolo o a byte doppio nel carattere Unicode corrispondente.

Se la tabella codici ANSI di sistema definisce un set di caratteri a byte singolo ,ovvero il set di caratteri ANSI, RtlAnsiCharToUnicodeChar accelera l'operazione di conversione semplicemente estendendo zero un carattere ANSI nell'intervallo 0x00 a 0x7f per produrre il carattere Unicode corrispondente. La routine converte il valore ANSI 0x5c nel carattere barra rovesciata ("\"), anche se la tabella codici a byte singolo definisce questo carattere come segno yen.

Se alla voce *SourceCharacter punta a un codice carattere non valido, RtlAnsiCharToUnicodeChar restituisce il codice carattere spazio Unicode 0x0020. L'elenco seguente mostra esempi di codici di carattere non validi:

Il primo byte del codice carattere è un valore valido solo come secondo byte di un codice di caratteri a due byte.
Il secondo byte di un codice di caratteri a due byte è un valore valido solo come primo byte.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL