Funzione LsaLookupNames (ntsecapi.h)

Articolo
08/25/2023

La funzione LsaLookupNames recupera gli identificatori di sicurezza (SID) corrispondenti a una matrice di nomi di utenti, gruppi o gruppi locali.

La funzione LsaLookupNames viene sostituita dalla funzione LsaLookupNames2. Le applicazioni devono usare la funzione LsaLookupNames2 per garantire la compatibilità futura.

La funzione LsaLookupNames può anche recuperare gli account computer.

Sintassi

NTSTATUS LsaLookupNames(
  [in]  LSA_HANDLE                  PolicyHandle,
  [in]  ULONG                       Count,
  [in]  PLSA_UNICODE_STRING         Names,
  [out] PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  [out] PLSA_TRANSLATED_SID         *Sids
);

Parametri

[in] PolicyHandle

Handle a un oggetto Policy . L'handle deve avere il diritto di accesso POLICY_LOOKUP_NAMES. Per altre informazioni, vedere Apertura di un handle oggetto Criteri.

[in] Count

Specifica il numero di nomi nella matrice Nomi . Si tratta anche del numero di voci restituite nella matrice Sids . Questo valore deve essere minore o uguale a 1000.

[in] Names

Puntatore a una matrice di strutture LSA_UNICODE_STRING che contengono i nomi da cercare. Le stringhe in queste strutture possono essere i nomi degli account utente, del gruppo o del gruppo locale o dei nomi dei domini. I nomi di dominio possono essere nomi di dominio DNS o nomi di dominio NetBIOS.

Per altre informazioni sul formato delle stringhe di nome, vedere Osservazioni.

[out] ReferencedDomains

Riceve un puntatore a una struttura LSA_REFERENCED_DOMAIN_LIST . Il membro Domini di questa struttura è una matrice che contiene una voce per ogni dominio in cui è stato trovato un nome. Il membro DomainIndex di ogni voce della matrice Sids è l'indice della voce della matrice Domini per il dominio in cui è stato trovato il nome.

Al termine dell'uso del puntatore restituito, liberare la memoria chiamando
Funzione LsaFreeMemory . Questa memoria deve essere liberata anche quando la funzione ha esito negativo con i codici di errore STATUS_NONE_MAPPED o STATUS_SOME_NOT_MAPPED

[out] Sids

Riceve un puntatore a una matrice di strutture LSA_TRANSLATED_SID . Ogni voce nella matrice Sids contiene le informazioni SID per la voce corrispondente nella matrice Nomi .

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce uno dei valori NTSTATUS seguenti.

Valore	Descrizione
STATUS_SOME_NOT_MAPPED	Non è stato possibile tradurre alcuni dei nomi. Si tratta di un valore restituito a livello informativo.
STATUS_SUCCESS	Tutti i nomi sono stati trovati e tradotti correttamente.

Se la funzione ha esito negativo, il valore restituito è il valore NTSTATUS seguente o uno dei valori restituiti della funzione Criteri LSA.

Valore	Descrizione
STATUS_NONE_MAPPED	Nessuno dei nomi è stato tradotto.
STATUS_TOO_MANY_NAMES	Il parametro della matrice Names è troppo grande.

Usare la funzione LsaNtStatusToWinError per convertire il codice NTSTATUS in un codice di errore di Windows.

Commenti

Avviso

Usare nomi di account completi (ad esempio, domain_name\user_name) anziché nomi isolati (ad esempio, user_name). I nomi completi non sono ambigui e offrono prestazioni migliori quando viene eseguita la ricerca. Questa funzione supporta anche nomi DNS completi (ad esempio, example.example.com\user_name) e nomi di entità utente (UPN) (ad esempio, someone@example.com).

Avviso

Per altre informazioni sulle limitazioni dei nomi isolati, vedere la documentazione di LsaLookupNames2 .

La funzione LsaLookupNames usa l'algoritmo seguente per tradurre i nomi di account.

Per tradurre i nomi

Se il nome è un nome noto, ad esempio Local o Interactive, la funzione restituisce l'identificatore di sicurezza noto corrispondente .
Se il nome è il nome del dominio predefinito, la funzione restituisce il SID di tale dominio.
Se il nome è il nome del dominio dell'account, la funzione restituisce il SID di tale dominio.
Se il nome è il nome del dominio primario, la funzione restituisce il SID di tale dominio.
Se il nome è uno dei nomi del dominio attendibile, la funzione restituisce il SID di tale dominio.
Se il nome è un utente, un gruppo o un account di gruppo locale nel dominio predefinito, la funzione restituisce il SID di tale account.
Se il nome è un utente, un gruppo o un account di gruppo locale nel dominio dell'account nel sistema locale, la funzione restituisce il SID di tale account.
Se il nome viene trovato nella cache, la funzione restituisce il SID di tale account.
Se il nome è un utente, un gruppo o un gruppo locale nel dominio primario, la funzione restituisce il SID di tale account.
Dopo aver eseguito l'analisi nel dominio primario, il dominio primario cerca in ognuno dei relativi domini attendibili.
In caso contrario, il nome non viene tradotto.

Oltre a cercare account locali, account di dominio locali e account di dominio attendibili in modo esplicito, LsaLookupNames può cercare il nome di qualsiasi account in qualsiasi dominio nella foresta di Windows.

Esempio

Per un esempio che chiama questa funzione, vedere Conversione tra nomi e SID.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ntsecapi.h
Libreria	Advapi32.lib
DLL	Advapi32.dll