Bagikan melalui


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
0
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
ERROR_ACCESS_DENIED
Pengguna tidak memiliki hak akses ke informasi yang diminta. Kesalahan ini juga dikembalikan jika parameter nama server memiliki kosong di belakangnya.
ERROR_INVALID_LEVEL
Tingkat panggilan sistem tidak benar. Kesalahan ini dikembalikan jika parameter tingkat tidak ditentukan sebagai 0.
ERROR_INVALID_PARAMETER
Parameter salah. Kesalahan ini dikembalikan jika parameter bendera berisi nilai selain LG_INCLUDE_INDIRECT.
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_DCNotFound
Pengendali domain tidak dapat ditemukan.
NERR_UserNotFound
Pengguna tidak dapat ditemukan. Kesalahan ini dikembalikan jika nama pengguna tidak dapat ditemukan.
RPC_S_SERVER_UNAVAILABLE
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

Lihat juga

LOCALGROUP_USERS_INFO_0

NetUserGetGroups

Fungsi Manajemen Jaringan

Gambaran Umum Manajemen Jaringan

Fungsi Pengguna