Fungsi NetLocalGroupEnum (lmaccess.h)

Artikel
03/09/2023

Fungsi NetLocalGroupEnum mengembalikan informasi tentang setiap akun grup lokal di server yang ditentukan.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetLocalGroupEnum(
  [in]      LPCWSTR    servername,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resumehandle
);

Parameter

[in] servername

Arahkan ke string konstanta yang menentukan nama DNS atau NetBIOS dari server jarak jauh tempat fungsi dijalankan. Jika parameter ini NULL, komputer lokal akan digunakan.

[in] level

Menentukan tingkat informasi data. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
0	Mengembalikan nama grup lokal. Parameter bufptr menunjuk ke array struktur LOCALGROUP_INFO_0 .
1	Mengembalikan nama grup lokal dan komentar yang terkait dengan setiap grup. Parameter bufptr menunjuk ke array struktur LOCALGROUP_INFO_1 .

[out] bufptr

Arahkan ke alamat buffer yang menerima struktur informasi. Format data ini tergantung pada nilai parameter tingkat . Buffer ini dialokasikan oleh sistem dan harus dikosongkan menggunakan fungsi NetApiBufferFree . Perhatikan bahwa Anda harus membebaskan buffer meskipun fungsi gagal dengan ERROR_MORE_DATA.

[in] prefmaxlen

Menentukan panjang maksimum data yang dikembalikan, dalam byte. Jika Anda menentukan MAX_PREFERRED_LENGTH, fungsi mengalokasikan jumlah memori yang diperlukan untuk data. Jika Anda menentukan nilai lain dalam parameter ini, nilai tersebut dapat membatasi jumlah byte yang dikembalikan fungsi. Jika ukuran buffer tidak cukup untuk menahan semua entri, fungsi akan mengembalikan ERROR_MORE_DATA. Untuk informasi selengkapnya, lihat Buffer Fungsi Manajemen Jaringan dan Panjang Buffer Fungsi Manajemen Jaringan.

[out] entriesread

Pointer ke nilai yang menerima hitungan elemen yang benar-benar dijumlahkan.

[out] totalentries

Penunjuk ke nilai yang menerima perkiraan jumlah total entri yang dapat dijumlahkan dari posisi resume saat ini. Jumlah total entri hanyalah petunjuk. Untuk informasi selengkapnya tentang menentukan jumlah entri yang tepat, lihat bagian Keterangan berikut ini.

[in, out] resumehandle

Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian grup lokal yang sudah ada. Handel harus nol pada panggilan pertama dan dibiarkan tidak berubah untuk panggilan berikutnya. Jika parameter ini NULL, maka tidak ada handel resume yang disimpan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pengguna tidak memiliki akses ke informasi yang diminta.
ERROR_MORE_DATA	Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri.
NERR_InvalidComputer	Nama komputer tidak valid.
NERR_BufTooSmall	Buffer pengembalian terlalu kecil.

Keterangan

Jika Anda memanggil fungsi ini pada pengendali domain yang menjalankan Direktori Aktif, akses diizinkan atau ditolak berdasarkan daftar kontrol akses (ACL) untuk objek yang dapat diamankan. ACL default mengizinkan semua pengguna terautentikasi dan anggota grup "Akses pra-windows 2000 kompatibel" untuk melihat informasi. Jika Anda memanggil fungsi ini di server anggota atau stasiun kerja, semua pengguna yang diautentikasi dapat melihat informasi. Untuk informasi tentang akses anonim dan membatasi akses anonim pada platform ini, lihat Persyaratan Keamanan untuk Fungsi Manajemen Jaringan. Untuk informasi selengkapnya tentang ACL, ACL, dan token akses, lihat Model Access Control.

Fungsi ini hanya mengembalikan informasi di mana pemanggil memiliki akses Baca. Pemanggil harus memiliki akses Konten Daftar ke objek Domain, dan Menghitung Seluruh akses Domain SAM pada objek SAM Server yang terletak di kontainer Sistem.

Untuk menentukan jumlah total grup lokal yang tepat, Anda harus menghitung seluruh pohon, yang dapat menjadi operasi yang mahal. Untuk menghitung seluruh pohon, gunakan parameter resumehandle untuk melanjutkan enumerasi untuk panggilan berturut-turut, dan gunakan parameter entriesread untuk mengakumulasi jumlah total grup lokal. Jika aplikasi Anda berkomunikasi dengan pengendali domain, Anda harus mempertimbangkan untuk menggunakan Penyedia LDAP ADSI untuk mengambil jenis data ini dengan lebih efisien. Penyedia ADSI LDAP mengimplementasikan sekumpulan objek ADSI yang mendukung berbagai antarmuka ADSI. Untuk informasi selengkapnya, lihat Penyedia Layanan ADSI.

Nama akun pengguna dibatasi hingga 20 karakter dan nama grup dibatasi hingga 256 karakter. Selain itu, nama akun tidak dapat dihentikan oleh titik dan tidak dapat menyertakan koma atau salah satu karakter yang dapat dicetak berikut: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Nama juga tidak dapat menyertakan karakter dalam rentang 1-31, yang tidak dapat dicetak.

Jika Anda memprogram Direktori Aktif, Anda mungkin dapat memanggil metode Antarmuka Layanan Direktori Aktif (ADSI) tertentu untuk mencapai fungsionalitas yang sama yang dapat Anda capai dengan memanggil fungsi grup lokal manajemen jaringan. Untuk informasi selengkapnya, lihat IADsGroup.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	lmaccess.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll