Fungsi LsaLookupNames (ntsecapi.h)

Artikel
03/08/2023

Fungsi LsaLookupNames mengambil pengidentifikasi keamanan (SID) yang sesuai dengan array nama pengguna, grup, atau grup lokal.

Fungsi LsaLookupNames digantikan oleh fungsi LsaLookupNames2 . Aplikasi harus menggunakan fungsi LsaLookupNames2 untuk memastikan kompatibilitas di masa mendatang.

Fungsi LsaLookupNames juga dapat mengambil akun komputer.

Sintaks

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

Parameter

[in] PolicyHandle

Handel ke objek Policy . Handel harus memiliki hak akses POLICY_LOOKUP_NAMES. Untuk informasi selengkapnya, lihat Membuka Penanganan Objek Kebijakan.

[in] Count

Menentukan jumlah nama dalam array Nama . Ini juga merupakan jumlah entri yang dikembalikan dalam array Sids . Nilai ini harus kurang dari atau sama dengan 1000.

[in] Names

Arahkan ke array struktur LSA_UNICODE_STRING yang berisi nama yang akan dicari. String dalam struktur ini dapat menjadi nama akun pengguna, grup, atau grup lokal, atau nama domain. Nama domain bisa berupa nama domain DNS atau nama domain NetBIOS.

Untuk informasi selengkapnya tentang format string nama, lihat Keterangan.

[out] ReferencedDomains

Menerima penunjuk ke struktur LSA_REFERENCED_DOMAIN_LIST . Anggota Domain dari struktur ini adalah array yang berisi entri untuk setiap domain tempat nama ditemukan. Anggota DomainIndex dari setiap entri dalam array Sids adalah indeks entri array Domain untuk domain tempat nama ditemukan.

Setelah Anda selesai menggunakan pointer yang dikembalikan, kosongkan memori dengan memanggil
Fungsi LsaFreeMemory . Memori ini harus dikosongkan bahkan ketika fungsi gagal dengan salah satu kode kesalahan STATUS_NONE_MAPPED atau STATUS_SOME_NOT_MAPPED

[out] Sids

Menerima penunjuk ke array struktur LSA_TRANSLATED_SID . Setiap entri dalam array Sids berisi informasi SID untuk entri terkait dalam array Nama .

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan salah satu nilai NTSTATUS berikut.

Nilai	Deskripsi
STATUS_SOME_NOT_MAPPED	Beberapa nama tidak dapat diterjemahkan. Ini adalah nilai pengembalian tingkat informasi.
STATUS_SUCCESS	Semua nama ditemukan dan berhasil diterjemahkan.

Jika fungsi gagal, nilai yang dikembalikan adalah nilai NTSTATUS berikut atau salah satu Nilai Pengembalian Fungsi Kebijakan LSA.

Nilai	Deskripsi
STATUS_NONE_MAPPED	Tidak ada nama yang diterjemahkan.
STATUS_TOO_MANY_NAMES	Parameter array Nama terlalu besar.

Gunakan fungsi LsaNtStatusToWinError untuk mengonversi kode NTSTATUS ke kode kesalahan Windows.

Keterangan

Peringatan

Gunakan nama akun yang sepenuhnya memenuhi syarat (misalnya, domain_name\user_name) alih-alih nama yang terisolasi (misalnya, user_name). Nama yang sepenuhnya memenuhi syarat tidak ambigu dan memberikan performa yang lebih baik saat pencarian dilakukan. Fungsi ini juga mendukung nama DNS yang sepenuhnya memenuhi syarat (misalnya, example.example.com\user_name) dan nama prinsipal pengguna (UPN) (misalnya, someone@example.com).

Peringatan

Untuk informasi selengkapnya tentang batasan nama yang terisolasi, silakan lihat dokumentasi LsaLookupNames2 .

Fungsi LsaLookupNames menggunakan algoritma berikut untuk menerjemahkan nama akun.

Untuk menerjemahkan nama

Jika namanya adalah nama terkenal, seperti Lokal atau Interaktif, fungsi mengembalikan pengidentifikasi keamanan (SID) terkenal yang sesuai.
Jika nama adalah nama domain bawaan, fungsi mengembalikan SID domain tersebut.
Jika nama adalah nama domain akun, fungsi mengembalikan SID domain tersebut.
Jika namanya adalah nama domain utama, fungsi mengembalikan SID domain tersebut.
Jika namanya adalah salah satu nama domain tepercaya, fungsi mengembalikan SID domain tersebut.
Jika namanya adalah pengguna, grup, atau akun grup lokal di domain bawaan, fungsi mengembalikan SID akun tersebut.
Jika namanya adalah akun pengguna, grup, atau grup lokal di domain akun pada sistem lokal, fungsi mengembalikan SID akun tersebut.
Jika nama ditemukan di cache, fungsi mengembalikan SID akun tersebut.
Jika namanya adalah pengguna, grup, atau grup lokal di domain utama, fungsi mengembalikan SID akun tersebut.
Setelah melihat domain utama, domain utama terlihat di setiap domain tepercayanya.
Jika tidak, nama tidak diterjemahkan.

Selain mencari akun lokal, akun domain lokal, dan akun domain tepercaya secara eksplisit, LsaLookupNames dapat mencari nama akun apa pun di domain apa pun di forest Windows.

Contoh

Untuk contoh yang memanggil fungsi ini, lihat Menerjemahkan Antara Nama dan SID.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	ntsecapi.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll