Fungsi NetUserGetGroups (lmaccess.h)
Fungsi NetUserGetGroups mengambil daftar grup global tempat pengguna tertentu berada.
Sintaks
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[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 yang akan dicari di setiap akun grup. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in] level
Tingkat informasi data yang diminta. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Mengembalikan nama grup global tempat pengguna berada. Parameter bufptr menunjuk ke array struktur GROUP_USERS_INFO_0 . |
|
Mengembalikan nama grup global tempat pengguna berada dengan atribut. Parameter bufptr menunjuk ke array struktur GROUP_USERS_INFO_1 . |
[out] bufptr
Penunjuk ke buffer yang menerima data. 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, 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 jumlah elemen yang benar-benar diambil.
[out] totalentries
Penunjuk ke nilai yang menerima jumlah total entri yang bisa diambil.
Menampilkan 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 |
|---|---|
|
Pengguna tidak memiliki hak akses ke informasi yang diminta. |
|
Jalur jaringan tidak ditemukan. Kesalahan ini dikembalikan jika parameter nama server tidak dapat ditemukan. |
|
Tingkat panggilan sistem tidak benar. Kesalahan ini dikembalikan jika parameter tingkat ditentukan sebagai nilai selain 0 atau 1. |
|
Sintaks nama salah. Kesalahan ini dikembalikan jika parameter nama server memiliki kosong di depan atau di belakang atau berisi karakter ilegal. |
|
Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri. |
|
Memori tidak cukup tersedia untuk menyelesaikan operasi. |
|
Terjadi kesalahan internal. |
|
Pengguna tidak dapat ditemukan. Kesalahan ini dikembalikan jika nama pengguna 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 Pengguna digunakan untuk melakukan pemeriksaan akses untuk fungsi ini.
Untuk mengambil daftar grup lokal tempat pengguna berada, Anda dapat memanggil fungsi NetUserGetLocalGroups . Grup jaringan terpisah dan berbeda dari grup sistem Windows NT.
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 global tempat pengguna berada dengan panggilan ke fungsi NetUserGetGroups . Sampel memanggil NetUserGetGroups, menentukan informasi tingkat 0 ( GROUP_USERS_INFO_0). Kode mengulang entri dan mencetak nama grup global tempat pengguna memiliki keanggotaan. Sampel juga mencetak jumlah total entri yang tersedia dan jumlah entri yang benar-benar dijumlahkan jika tidak cocok. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer.
#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[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
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 NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global 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->grui0_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 buffer.
//
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 |