Funzione GetStringScripts (winnls.h)

Articolo
03/04/2024

Fornisce un elenco di script usati nella stringa Unicode specificata.

Sintassi

int GetStringScripts(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpString,
  [in]            int     cchString,
  [out, optional] LPWSTR  lpScripts,
  [in]            int     cchScripts
);

Parametri

[in] dwFlags

Flag che specificano le opzioni per il recupero dello script.

Valore	Significato
GSS_ALLOW_INHERITED_COMMON	Recuperare le informazioni sullo script "Qaii" (INHERITED) e "Zyyy" (COMMON). Questo flag non influisce sull'elaborazione di caratteri non assegnati. Questi caratteri nella stringa di input causano sempre la visualizzazione di un "Zzzz" (script UNASSIGNED) nella stringa di script.

Nota Per impostazione predefinita, GetStringScripts ignora tutti i caratteri ereditati o comuni nella stringa di input indicata da lpString. Se GSS_ALLOW_INHERITED_COMMON non è impostato, né "Qaii" né "Zyyy" vengono visualizzati nella stringa di script, anche se la stringa di input contiene tali caratteri. Se GSS_ALLOW_INHERITED_COMMON è impostato e se la stringa di input contiene rispettivamente caratteri ereditati e/o comuni, "Qaii" e/o "Zyyy", vengono visualizzati nella stringa di script. Vedere la sezione relativa alle osservazioni.

[in] lpString

Puntatore alla stringa Unicode da analizzare.

[in] cchString

Dimensioni, in caratteri, della stringa Unicode indicata da lpString. L'applicazione imposta questo parametro su -1 se la stringa Unicode è con terminazione Null. Se l'applicazione imposta questo parametro su 0, la funzione recupera una stringa Unicode Null (L"\0") in lpScripts e restituisce 1.

[out, optional] lpScripts

Puntatore a un buffer in cui questa funzione recupera una stringa con terminazione Null che rappresenta un elenco di script, usando la notazione a 4 caratteri utilizzata in ISO 15924. Ogni nome di script è costituito da quattro caratteri latini e i nomi vengono recuperati in ordine alfabetico. Ogni nome, incluso l'ultimo, è seguito da un punto e virgola.

In alternativa, questo parametro contiene NULL se cchScripts è impostato su 0. In questo caso, la funzione restituisce le dimensioni necessarie per il buffer dello script.

[in] cchScripts

Dimensioni, in caratteri, del buffer dello script indicato da lpScripts.

In alternativa, l'applicazione può impostare questo parametro su 0. In questo caso, la funzione recupera NULL in lpScripts e restituisce le dimensioni necessarie per il buffer di script.

Valore restituito

Restituisce il numero di caratteri recuperati nel buffer di output, incluso un carattere Null di terminazione, se l'operazione ha esito positivo e cchScripts è impostata su un valore diverso da zero. La funzione restituisce 1 per indicare che non è stato trovato alcuno script, ad esempio quando la stringa di input contiene solo caratteri COMMON o INHERITED e GSS_ALLOW_INHERITED_COMMON non è impostata. Dato che ogni script trovato aggiunge cinque caratteri (quattro caratteri + delimitatore), una semplice operazione matematica fornisce il numero di script come (return_code - 1) / 5.

Se la funzione ha esito positivo e il valore di cchScripts è 0, la funzione restituisce le dimensioni necessarie, in caratteri che includono un carattere Null di terminazione, per il buffer di script. Il numero di script è come descritto in precedenza.

Questa 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_BADDB. La funzione non è riuscita ad accedere ai dati. Questa situazione non deve normalmente verificarsi e in genere indica un'installazione non valida, un problema del disco o un simile.
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_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Questa funzione è utile come parte di una strategia per attenuare i problemi di sicurezza correlati ai nomi di dominio internazionalizzati (IDN) .

La determinazione dello script si basa sui valori di script pubblicati da Unicode Consortium in http://www.unicode.org/Public/4.1.0/ucd/Scripts.txt, ad eccezione del fatto che i caratteri non assegnati hanno il valore "Zzzz" (UNASSIGNED) anziché "Zyyy" (COMMON).

Ecco alcuni esempi del comportamento di questa funzione:

Stringa di input		dwFlags	lpScripts	Script
Microsoft.com		0	Latn;	Latino
Microsoft.com		GSS_ALLOW_INHERITED_COMMON	Latn; Zyyy;	Alfabeto latino + comune
Niño	004E 0069 0241 006F	GSS_ALLOW_INHERITED_COMMON	Latn;	Latino
Niño	Utilizza LETTERE MINUSCOLE LATINE N CON TILDE	GSS_ALLOW_INHERITED_COMMON	Latn;	Latino
Niño	004E 0069 006E 0303 006F	GSS_ALLOW_INHERITED_COMMON	Latn; Qaii;	Alfabeto latino + ereditato
Niño	Usa LA COMBINAZIONE TILDE	GSS_ALLOW_INHERITED_COMMON	Latn; Qaii;	Alfabeto latino + ereditato
Spооf	0053 0070 043e 043e 0066	0	Latn; Cyrl;	Alfabeto latino + cirillico
Spооf	Utilizza LA LETTERA MINUSCOLA CIRILLICO O	0	Latn; Cyrl;	Alfabeto latino + cirillico
	U+f000	0	Zzzz;	Unassigned (Non assegnato)
	U+f000	GSS_ALLOW_INHERITED_COMMON	Zzzz;	Unassigned (Non assegnato)

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	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

DownlevelGetStringScripts

Gestione dei nomi di dominio internazionalizzati (IDN)

Supporto per la lingua nazionale

Funzioni di supporto per il linguaggio nazionale

VerifyScripts