Condividi tramite


Funzione IdnToAscii (winnls.h)

Converte un nome di dominio internazionalizzato (IDN) o un'altra etichetta internazionalizzata in una rappresentazione Unicode (carattere wide) della stringa ASCII che rappresenta il nome nella sintassi di codifica del trasferimento punycode.

Attenzione Questa funzione implementa l'algoritmo standard RFC 3490: Internationalizing Domain Names in Applications (IDNA) per convertire un IDN in Punycode. Lo standard introduce alcuni problemi di sicurezza. Un problema è che i glifi che rappresentano determinati caratteri di script diversi potrebbero apparire simili o persino identici. Ad esempio, in molti tipi di carattere, il minuscolo alfabetico A ("а") è indistinguibile dal alfabeto latino A ("a"). Non c'è modo di dire visivamente che "example.com" e "exа mple.com" sono due nomi di dominio diversi, uno con un alfabeto latino minuscolo A nel nome, l'altro con un alfabeto cirillico minuscolo A. Per altre informazioni sui problemi di sicurezza relativi all'IDN, vedere Gestione dei nomi di dominio internazionalizzati (IDN).For more information about IDN-related security concerns, see Handling Internationalized Domain Names (IDN).

 

Sintassi

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

Parametri

[in] dwFlags

Flag che specificano le opzioni di conversione. Nella tabella seguente sono elencati i valori possibili.

Valore Significato
IDN_ALLOW_UNASSIGNED
Nota Un'applicazione può impostare questo valore se usa solo una stringa di query per la ricerca normale, come in un'operazione di confronto. Tuttavia, l'applicazione non deve impostare questo valore per una stringa archiviata, ovvero una stringa preparata per l'archiviazione.
 
Consente l'inserimento di punti di codice non assegnati nella stringa di input. L'impostazione predefinita non consente punti di codice non assegnati e non riesce con un codice di errore esteso di ERROR_INVALID_NAME.

Questo flag consente alla funzione di elaborare i caratteri attualmente non validi negli IDN, ma potrebbe essere legale nelle versioni successive dello standard IDNA. Se l'applicazione codifica punti di codice non assegnati come Punycode, i nomi di dominio risultanti devono essere illegali. La sicurezza può essere compromessa se una versione successiva di IDNA rende questi nomi validi o se un'applicazione filtra i caratteri non validi per tentare di creare un nome di dominio legale. Per altre informazioni, vedere Gestione dei nomi di dominio internazionalizzati (IDN).

IDN_USE_STD3_ASCII_RULES
Filtrare i caratteri ASCII non consentiti nei nomi STD3. Gli unici caratteri ASCII consentiti nella stringa Unicode di input sono lettere, cifre e trattini meno. La stringa non può iniziare o terminare con il trattino meno. La funzione ha esito negativo se la stringa Unicode di input contiene caratteri ASCII, ad esempio "[", "]" o "/", che non possono verificarsi nei nomi di dominio.
Nota Alcune reti locali possono consentire alcuni di questi caratteri nei nomi dei computer.
 

La funzione ha esito negativo se la stringa Unicode di input contiene caratteri di controllo (da U+0001 a U+0020) o il carattere "delete" (U+007F). In entrambi i casi, questo flag non ha alcun effetto sui caratteri non ASCII consentiti nella stringa Unicode.

IDN_EMAIL_ADDRESS
A partire da Windows 8: abilitare il fallback algoritmico EAI per le parti locali degli indirizzi di posta elettronica (ad esempio <local>@microsoft.com). L'impostazione predefinita è che questa funzione abbia esito negativo quando un indirizzo di posta elettronica ha un indirizzo o una sintassi non valida.

Un'applicazione può impostare questo flag per abilitare Email Address Internationalization (EAI) per restituire un indirizzo di fallback individuabile, se possibile. Per altre informazioni, vedere la Carta IETF Email Address Internationalization (eai).

IDN_RAW_PUNYCODE
A partire da Windows 8: disabilitare la convalida e il mapping di Punycode.

[in] lpUnicodeCharStr

Puntatore a una stringa Unicode che rappresenta un IDN o un'altra etichetta internazionalizzata.

[in] cchUnicodeChar

Numero di caratteri nella stringa Unicode di input indicata da lpUnicodeCharStr.

[out, optional] lpASCIICharStr

Puntatore a un buffer che riceve una stringa Unicode costituita solo da caratteri nel set di caratteri ASCII. Al ritorno da questa funzione, il buffer contiene l'equivalente stringa ASCII della stringa fornita in lpUnicodeCharStr in Punycode. In alternativa, la funzione può recuperare NULL per questo parametro, se cchASCIIChar è impostato su 0. In questo caso, la funzione restituisce le dimensioni necessarie per questo buffer.

[in] cchASCIIChar

Dimensione del buffer indicato da lpASCIICharStr. L'applicazione può impostare il parametro su 0 per recuperare NULL in lpASCIICharStr.

Valore restituito

Restituisce il numero di caratteri recuperati in lpASCIICharStr in caso di esito positivo. La stringa recuperata è con terminazione Null solo se la stringa Unicode di input è con terminazione Null.

Se la funzione ha esito positivo e il valore di cchASCIIChar è 0, la funzione restituisce le dimensioni necessarie, in caratteri che includono un carattere Null di terminazione se fa parte del buffer di input.

La funzione restituisce 0 se non riesce. Per ottenere informazioni estese sull'errore, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

  • ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
  • ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
  • ERROR_INVALID_NAME. Alla funzione è stato fornito un nome non valido. Si noti che questo codice di errore rileva tutti gli errori di sintassi.
  • ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.
  • ERROR_NO_UNICODE_TRANSLATION. È stato trovato Unicode non valido in una stringa.

Commenti

La funzione non termina una stringa di output se la lunghezza della stringa di input viene specificata in modo esplicito senza un carattere Null di terminazione. Per terminare null una stringa di output per questa funzione, l'applicazione deve fornire -1 per il parametro cchUnicodeChar o contare in modo esplicito il carattere null di terminazione per la stringa di input.

Si noti che la funzione ha sempre esito negativo se la stringa di input contiene caratteri di controllo (da U+0001 a U+0020) o il carattere "delete" (U+007F). Poiché il carattere U+0000 può essere visualizzato solo come carattere Null di terminazione, la funzione ha sempre esito negativo se U+0000 viene visualizzato in qualsiasi punto della stringa di input.

Windows XP, Windows Server 2003:

Non più supportata.

Il file di intestazione e la DLL necessari fanno parte delle API di mitigazione IDN (Internationalized Domain Name) Microsoft, che non sono più disponibili per il download.

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione winnls.h (include Windows.h)
Libreria Normaliz.lib
DLL Normaliz.dll
Componente ridistribuibile API di mitigazione IDN (Internationalized Domain Name) microsoft inWindows XP con SP2 e versioni successive, Windows Server 2003 con SP1

Vedi anche

Gestione dei nomi di dominio internazionalizzati (IDN)

IdnToNameprepUnicode

IdnToUnicode

Supporto per la lingua nazionale

Funzioni di supporto per il linguaggio nazionale