Fonction LsaLookupNames (ntsecapi.h)

Article
08/25/2023

La fonction LsaLookupNames récupère les identificateurs de sécurité (SID) qui correspondent à un tableau de noms d’utilisateurs, de groupes ou de groupes locaux.

La fonction LsaLookupNames est remplacée par la fonction LsaLookupNames2 . Les applications doivent utiliser la fonction LsaLookupNames2 pour garantir la compatibilité future.

La fonction LsaLookupNames peut également récupérer des comptes d’ordinateur.

Syntaxe

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
);

Paramètres

[in] PolicyHandle

Handle d’un objet Policy . Le handle doit avoir le droit d’accès POLICY_LOOKUP_NAMES. Pour plus d’informations, consultez Ouverture d’un handle d’objet de stratégie.

[in] Count

Spécifie le nombre de noms dans le tableau Names . Il s’agit également du nombre d’entrées retournées dans le tableau Sids . Cette valeur doit être inférieure ou égale à 1000.

[in] Names

Pointeur vers un tableau de structures LSA_UNICODE_STRING contenant les noms à rechercher. Les chaînes de ces structures peuvent être les noms des comptes d’utilisateur, de groupe ou de groupe local, ou les noms de domaines. Les noms de domaine peuvent être des noms de domaine DNS ou des noms de domaine NetBIOS.

Pour plus d’informations sur le format des chaînes de noms, consultez Remarques.

[out] ReferencedDomains

Reçoit un pointeur vers une structure LSA_REFERENCED_DOMAIN_LIST . Le membre Domains de cette structure est un tableau qui contient une entrée pour chaque domaine dans lequel un nom a été trouvé. Le membre DomainIndex de chaque entrée du tableau Sids est l’index de l’entrée du tableau Domains pour le domaine dans lequel le nom a été trouvé.

Une fois que vous avez terminé d’utiliser le pointeur retourné, libérez la mémoire en appelant le
Fonction LsaFreeMemory . Cette mémoire doit être libérée même lorsque la fonction échoue avec l’un des codes d’erreur STATUS_NONE_MAPPED ou STATUS_SOME_NOT_MAPPED

[out] Sids

Reçoit un pointeur vers un tableau de structures LSA_TRANSLATED_SID . Chaque entrée du tableau Sids contient les informations SID pour l’entrée correspondante dans le tableau Noms .

Valeur retournée

Si la fonction réussit, la fonction retourne l’une des valeurs NTSTATUS suivantes.

Valeur	Description
STATUS_SOME_NOT_MAPPED	Certains noms n’ont pas pu être traduits. Il s’agit d’une valeur de retour de niveau informationnel.
STATUS_SUCCESS	Tous les noms ont été trouvés et traduits avec succès.

Si la fonction échoue, la valeur de retour est la valeur NTSTATUS suivante ou l’une des valeurs de retour de la fonction de stratégie LSA.

Valeur	Description
STATUS_NONE_MAPPED	Aucun des noms n’a été traduit.
STATUS_TOO_MANY_NAMES	Le paramètre de tableau Names était trop volumineux.

Utilisez la fonction LsaNtStatusToWinError pour convertir le code NTSTATUS en code d’erreur Windows.

Notes

Avertissement

Utilisez des noms de comptes complets (par exemple, domain_name\user_name) au lieu de noms isolés (par exemple, user_name). Les noms complets sont sans ambiguïté et fournissent de meilleures performances lorsque la recherche est effectuée. Cette fonction prend également en charge les noms DNS complets (par exemple, example.example.com\user_name) et les noms d’utilisateur principaux (UPN) (par exemple, someone@example.com).

Avertissement

Pour plus d’informations sur les limitations des noms isolés, reportez-vous à la documentation LsaLookupNames2 .

La fonction LsaLookupNames utilise l’algorithme suivant pour traduire les noms de compte.

Pour traduire des noms

Si le nom est un nom connu, par exemple Local ou Interactif, la fonction retourne l’identificateur de sécurité (SID) connu correspondant.
Si le nom est le nom du domaine intégré, la fonction retourne le SID de ce domaine.
Si le nom est le nom du domaine du compte, la fonction retourne le SID de ce domaine.
Si le nom est le nom du domaine principal, la fonction retourne le SID de ce domaine.
Si le nom est l’un des noms du domaine approuvé, la fonction retourne le SID de ce domaine.
Si le nom est un compte d’utilisateur, de groupe ou de groupe local dans le domaine intégré, la fonction retourne le SID de ce compte.
Si le nom est un compte d’utilisateur, de groupe ou de groupe local dans le domaine du compte sur le système local, la fonction retourne le SID de ce compte.
Si le nom est trouvé dans le cache, la fonction retourne le SID de ce compte.
Si le nom est un utilisateur, un groupe ou un groupe local dans le domaine principal, la fonction retourne le SID de ce compte.
Après avoir recherché dans le domaine principal, le domaine principal recherche dans chacun de ses domaines approuvés.
Sinon, le nom n’est pas traduit.

En plus de rechercher des comptes locaux, des comptes de domaine locaux et des comptes de domaine approuvés explicitement, LsaLookupNames peut rechercher le nom de n’importe quel compte dans n’importe quel domaine de la forêt Windows.

Exemples

Pour obtenir un exemple qui appelle cette fonction, consultez Traduire entre des noms et des SID.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ntsecapi.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll