Fungsi NetUserGetLocalGroups (lmaccess.h)
Fungsi NetUserGetLocalGroups mengambil daftar grup lokal tempat pengguna tertentu berada.
Sintaks
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
Parameter
[in] servername
Penunjuk 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] username
Penunjuk ke string konstanta yang menentukan nama pengguna untuk mengembalikan informasi keanggotaan grup lokal. Jika string berbentuk NamaPengguna DomainName\, nama pengguna diharapkan dapat ditemukan di domain tersebut. Jika string berbentuk UserName, nama pengguna diharapkan ditemukan di server yang ditentukan oleh parameter nama server . Untuk informasi lebih lanjut, lihat bagian Keterangan.
[in] level
Tingkat informasi data. Parameter ini bisa menjadi nilai berikut.
| Nilai | Makna |
|---|---|
|
Mengembalikan nama grup lokal tempat pengguna berada. Parameter bufptr menunjuk ke array struktur LOCALGROUP_USERS_INFO_0 . |
[in] flags
Bitmask bendera yang memengaruhi operasi. Saat ini, hanya nilai yang ditentukan yang LG_INCLUDE_INDIRECT. Jika bit ini diatur, fungsi juga mengembalikan nama grup lokal tempat pengguna secara tidak langsung menjadi anggota (yaitu, pengguna memiliki keanggotaan dalam grup global yang merupakan anggota dari satu atau beberapa grup lokal).
[out] bufptr
Penunjuk ke buffer yang menerima data. 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
Panjang maksimum yang disukai, dalam byte, dari data yang dikembalikan. Jika MAX_PREFERRED_LENGTH ditentukan dalam parameter ini, fungsi mengalokasikan jumlah memori yang diperlukan untuk data. Jika nilai lain ditentukan 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
Penunjuk ke nilai yang menerima hitungan elemen yang benar-benar dijumlahkan.
[out] totalentries
Penunjuk ke nilai yang menerima jumlah total entri yang bisa saja dijumlahkan.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan NERR_Success.
Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Pengguna tidak memiliki hak akses ke informasi yang diminta. Kesalahan ini juga dikembalikan jika parameter nama server memiliki kosong di belakangnya. |
|
Tingkat panggilan sistem tidak benar. Kesalahan ini dikembalikan jika parameter tingkat tidak ditentukan sebagai 0. |
|
Parameter salah. Kesalahan ini dikembalikan jika parameter bendera berisi nilai selain LG_INCLUDE_INDIRECT. |
|
Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri. |
|
Memori tidak cukup tersedia untuk menyelesaikan operasi. |
|
Pengendali domain tidak dapat ditemukan. |
|
Pengguna tidak dapat ditemukan. Kesalahan ini dikembalikan jika nama pengguna tidak dapat ditemukan. |
|
Server RPC tidak tersedia. Kesalahan ini dikembalikan jika parameter nama server tidak dapat ditemukan. |
Keterangan
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 pengguna manajemen jaringan. Untuk informasi selengkapnya, lihat IADsUser dan IADsComputer.
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.
Pendeskripsi keamanan objek Domain digunakan untuk melakukan pemeriksaan akses untuk fungsi ini. Pemanggil harus memiliki izin Properti Baca pada objek Domain.
Untuk mengambil daftar grup global tempat pengguna tertentu berada, Anda dapat memanggil fungsi NetUserGetGroups .
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.
Contoh
Sampel kode berikut menunjukkan cara mengambil daftar grup lokal tempat pengguna berada dengan panggilan ke fungsi NetUserGetLocalGroups . Sampel memanggil NetUserGetLocalGroups, menentukan informasi tingkat 0 (LOCALGROUP_USERS_INFO_0). Sampel mengulang entri dan mencetak nama setiap grup lokal tempat pengguna memiliki keanggotaan. Jika semua entri yang tersedia tidak dijumlahkan, entri juga mencetak jumlah entri yang benar-benar dijumlahkan dan jumlah total entri yang tersedia. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer informasi.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->lgrui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
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 |