Fungsi NetUserEnum (lmaccess.h)

Artikel
03/09/2023

Fungsi NetUserEnum mengambil informasi tentang semua akun pengguna di server.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetUserEnum(
  [in]      LPCWSTR servername,
  [in]      DWORD   level,
  [in]      DWORD   filter,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] PDWORD  resume_handle
);

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] level

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

Nilai	Makna
0	Mengembalikan nama akun pengguna. Parameter bufptr menunjuk ke array struktur USER_INFO_0 .
1	Mengembalikan informasi terperinci tentang akun pengguna. Parameter bufptr menunjuk ke array struktur USER_INFO_1 .
2	Mengembalikan informasi terperinci tentang akun pengguna, termasuk tingkat otorisasi dan informasi masuk. Parameter bufptr menunjuk ke array struktur USER_INFO_2 .
3	Mengembalikan informasi terperinci tentang akun pengguna, termasuk tingkat otorisasi, informasi masuk, RID untuk pengguna dan grup utama, dan informasi profil. Parameter bufptr menunjuk ke array struktur USER_INFO_3 .
10	Mengembalikan nama dan komentar pengguna dan akun. Parameter bufptr menunjuk ke array struktur USER_INFO_10 .
11	Mengembalikan informasi terperinci tentang akun pengguna. Parameter bufptr menunjuk ke array struktur USER_INFO_11 .
20	Mengembalikan nama dan pengidentifikasi pengguna serta berbagai atribut akun. Parameter bufptr menunjuk ke array struktur USER_INFO_20 . Perhatikan bahwa pada Windows XP dan yang lebih baru, disarankan agar Anda menggunakan USER_INFO_23 sebagai gantinya.

[in] filter

Nilai yang menentukan jenis akun pengguna yang akan disertakan dalam enumerasi. Nilai nol menunjukkan bahwa semua data pengguna normal, data kepercayaan, dan akun komputer harus disertakan.

Parameter ini juga bisa menjadi kombinasi dari nilai berikut.

Nilai	Makna
FILTER_TEMP_DUPLICATE_ACCOUNT	Menghitung data akun untuk pengguna yang akun utamanya berada di domain lain. Tipe akun ini menyediakan akses pengguna ke domain ini, tetapi tidak ke domain apa pun yang mempercayai domain ini. Manajer Pengguna mengacu pada jenis akun ini sebagai akun pengguna lokal.
FILTER_NORMAL_ACCOUNT	Menghitung data akun pengguna normal. Jenis akun ini dikaitkan dengan pengguna biasa.
FILTER_INTERDOMAIN_TRUST_ACCOUNT	Menghitung data akun kepercayaan antardomain. Tipe akun ini dikaitkan dengan akun kepercayaan untuk domain yang mempercayai domain lain.
FILTER_WORKSTATION_TRUST_ACCOUNT	Menghitung data akun kepercayaan server stasiun kerja atau anggota. Tipe akun ini dikaitkan dengan akun komputer untuk komputer yang merupakan anggota domain.
FILTER_SERVER_TRUST_ACCOUNT	Menghitung data akun komputer server anggota. Tipe akun ini dikaitkan dengan akun komputer untuk pengendali domain cadangan yang merupakan anggota domain.

[out] bufptr

Penunjuk ke buffer yang menerima data. Format data ini tergantung pada nilai parameter tingkat .

Buffer untuk data ini dialokasikan oleh sistem dan aplikasi harus memanggil fungsi NetApiBufferFree untuk membebaskan memori yang dialokasikan ketika data yang dikembalikan tidak lagi diperlukan. Perhatikan bahwa Anda harus membebaskan buffer meskipun fungsi NetUserEnum gagal dengan ERROR_MORE_DATA.

[in] prefmaxlen

Panjang maksimum yang disukai, dalam byte, dari data yang dikembalikan. Jika Anda menentukan MAX_PREFERRED_LENGTH, fungsi NetUserEnum 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 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 dijumlahkan dari posisi resume saat ini. Perhatikan bahwa aplikasi harus mempertimbangkan nilai ini hanya sebagai petunjuk. Jika aplikasi Anda berkomunikasi dengan pengontrol domain Windows 2000 atau yang lebih baru, Anda harus mempertimbangkan untuk menggunakan Penyedia ADSI LDAP 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.

Manajer LAN: Jika panggilan adalah ke komputer yang menjalankan LAN Manager 2. x, parameter totalentries akan selalu mencerminkan jumlah total entri dalam database di mana pun berada dalam urutan resume.

[in, out] resume_handle

Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian pengguna 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.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

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

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pengguna tidak memiliki akses ke informasi yang diminta.
ERROR_INVALID_LEVEL	Tingkat panggilan sistem tidak benar. Kesalahan ini dikembalikan jika parameter tingkat diatur ke nilai yang tidak didukung.
NERR_BufTooSmall	Buffer terlalu kecil untuk memuat entri. Tidak ada informasi yang ditulis ke buffer.
NERR_InvalidComputer	Nama komputer tidak valid.
ERROR_MORE_DATA	Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri.

Keterangan

Fungsi NetUserEnum mengambil informasi tentang semua akun pengguna di server jarak jauh tertentu atau komputer lokal.

Fungsi NetQueryDisplayInformation dapat digunakan untuk menghitung informasi akun pengguna, komputer, atau grup global dengan cepat untuk ditampilkan di antarmuka pengguna .

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 NetUserEnum 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 NetUserEnum 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.

Fungsi LsaEnumerateTrustedDomains atau LsaEnumerateTrustedDomainsEx dapat digunakan untuk mengambil nama dan SID domain yang dipercaya oleh objek kebijakan Otoritas Keamanan Lokal (LSA).

Fungsi NetUserEnum tidak mengembalikan semua pengguna sistem. Ini hanya mengembalikan pengguna yang telah ditambahkan dengan panggilan ke fungsi NetUserAdd . Tidak ada jaminan bahwa daftar pengguna akan dikembalikan dalam urutan yang diurutkan.

Jika Anda memanggil fungsi NetUserEnum dan menentukan informasi tingkat 1, 2, atau 3, untuk parameter tingkat , anggota kata sandi dari setiap struktur yang diambil diatur ke NULL untuk menjaga keamanan kata sandi.

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.

Fungsi NetUserEnum tidak mendukung parameter tingkat 4 dan struktur USER_INFO_4 . Fungsi NetUserGetInfo mendukung parameter tingkat 4 dan struktur USER_INFO_4 .

Contoh

Sampel kode berikut menunjukkan cara mengambil informasi tentang akun pengguna di server dengan panggilan ke fungsi NetUserEnum . Sampel memanggil NetUserEnum, menentukan informasi tingkat 0 (USER_INFO_0) untuk menghitung hanya akun pengguna global. Jika panggilan berhasil, kode akan mengulang entri dan mencetak nama setiap akun pengguna. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer informasi dan mencetak total pengguna yang dijumlahkan.

#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[])
{
   LPUSER_INFO_0 pBuf = NULL;
   LPUSER_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName =  (LPTSTR) argv[1];
   wprintf(L"\nUser account on %s: \n", pszServerName);
   //
   // Call the NetUserEnum function, specifying level 0; 
   //   enumerate global user account types only.
   //
   do // begin do
   {
      nStatus = NetUserEnum((LPCWSTR) pszServerName,
                            dwLevel,
                            FILTER_NORMAL_ACCOUNT, // global users
                            (LPBYTE*)&pBuf,
                            dwPrefMaxLen,
                            &dwEntriesRead,
                            &dwTotalEntries,
                            &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               //  Print the name of the user account.
               //
               wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, print the system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated buffer.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   // Continue to call NetUserEnum while 
   //  there are more entries. 
   // 
   while (nStatus == ERROR_MORE_DATA); // end do
   //
   // Check again for allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of users enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Persyaratan

Persyaratan	Nilai
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