Funzione GetNLSVersionEx (winnls.h)

Articolo
03/13/2024

Recupera informazioni sulla versione corrente di una funzionalità NLS specificata per le impostazioni locali specificate in base al nome.

Nota L'applicazione deve chiamare questa funzione in preferenza per GetNLSVersion se progettata per l'esecuzione solo in Windows Vista e versioni successive.

Sintassi

BOOL GetNLSVersionEx(
  [in]           NLS_FUNCTION       function,
  [in, optional] LPCWSTR            lpLocaleName,
  [in, out]      LPNLSVERSIONINFOEX lpVersionInformation
);

Parametri

[in] function

Funzionalità NLS da eseguire in query. Questo valore deve essere COMPARE_STRING. Vedere l'enumerazione SYSNLS_FUNCTION .

[in, optional] lpLocaleName

Puntatore a un nome delle impostazioni locali o uno dei valori predefiniti seguenti.

[in, out] lpVersionInformation

Puntatore a una struttura NLSVERSIONINFOEX . L'applicazione deve inizializzare il membro dwNLSVersionInfoSize in sizeof(NLSVERSIONINFOEX).

Nota In Windows Vista e versioni successive, la funzione può in alternativa fornire informazioni sulla versione in una struttura NLSVERSIONINFO .

Valore restituito

Restituisce TRUE se e solo se l'applicazione ha fornito valori validi in lpVersionInformation o FALSE in caso contrario. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Una dimensione del buffer fornita non è stata sufficiente oppure è stata impostata in modo errato su NULL.
ERROR_INVALID_FLAGS. I valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Questa funzione consente a un'applicazione come Active Directory di determinare se una modifica NLS influisce sulle impostazioni locali usate per una determinata tabella di indice. In caso contrario, non è necessario ricompilare la tabella. Per altre informazioni, vedere Gestione dell'ordinamento nelle applicazioni. In particolare, per indicare se una versione di ordinamento è stata modificata e è necessario reindex:

Usare GetNLSVersionEx per recuperare una struttura NLSVERSIONINFOEX durante l'indicizzazione originale dei dati.
Archiviare le proprietà seguenti con l'indice per identificare la versione:
- NLSVERSIONINFOEX.dwNLSVersion. In questo modo viene specificata la versione della tabella di ordinamento in uso.
- NLSVERSIONINFOEX.dwEffectiveId. In questo modo vengono specificate le impostazioni locali effettive dell'ordinamento. Le impostazioni locali personalizzate puntano all'ordinamento delle impostazioni locali in box.
- NLSVERSIONINFOEX.guidCustomVersion. Si tratta di un GUID che specifica un ordinamento personalizzato specifico per le impostazioni locali personalizzate che li hanno.
Quando si usa l'indice, usare GetNLSVersionEx per individuare la versione dei dati.
Se una delle tre proprietà è stata modificata, i dati di ordinamento usati potrebbero restituire risultati diversi e qualsiasi indicizzazione potrebbe non riuscire a trovare record.
Se si sa che i dati non contengono punti di codice Unicode non validi, ovvero tutte le stringhe passate una chiamata a IsNLSDefinedString, è possibile considerarle uguali se solo il byte basso di dwNLSVersion è stato modificato (la versione secondaria descritta in precedenza).

Questo argomento è descritto in dettaglio nella voce di blog "Come stabilire se la versione delle regole di confronto è cambiata" (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

Questa funzione supporta impostazioni locali personalizzate. Se lpLocaleName specifica impostazioni locali supplementari, i dati recuperati sono i dati corretti per l'ordine di ordinamento associato a tali impostazioni locali supplementari.

A partire da Windows 8: se l'app passa tag di lingua a questa funzione dallo spazio dei nomi Windows.Globalization, deve prima convertire i tag chiamando ResolveLocaleName.

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 (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll