Fungsi NetUserGetGroups (lmaccess.h)

Artikel
08/24/2023

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
0	Mengembalikan nama grup global tempat pengguna berada. Parameter bufptr menunjuk ke array struktur GROUP_USERS_INFO_0 .
1	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
ERROR_ACCESS_DENIED	Pengguna tidak memiliki hak akses ke informasi yang diminta.
ERROR_BAD_NETPATH	Jalur jaringan tidak ditemukan. Kesalahan ini dikembalikan jika parameter nama server tidak dapat ditemukan.
ERROR_INVALID_LEVEL	Tingkat panggilan sistem tidak benar. Kesalahan ini dikembalikan jika parameter tingkat ditentukan sebagai nilai selain 0 atau 1.
ERROR_INVALID_NAME	Sintaks nama salah. Kesalahan ini dikembalikan jika parameter nama server memiliki kosong di depan atau di belakang atau berisi karakter ilegal.
ERROR_MORE_DATA	Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia untuk menyelesaikan operasi.
NERR_InternalError	Terjadi kesalahan internal.
NERR_UserNotFound	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