Fungsi NetQueryDisplayInformation (lmaccess.h)

Artikel
03/09/2023

Fungsi NetQueryDisplayInformation mengembalikan informasi akun pengguna, komputer, atau akun grup. Panggil fungsi ini untuk menghitung informasi akun dengan cepat untuk ditampilkan di antarmuka pengguna.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
  [in]  LPCWSTR ServerName,
  [in]  DWORD   Level,
  [in]  DWORD   Index,
  [in]  DWORD   EntriesRequested,
  [in]  DWORD   PreferredMaximumLength,
  [out] LPDWORD ReturnedEntryCount,
  [out] PVOID   *SortedBuffer
);

Parameter

[in] ServerName

Penunjuk ke string konstanta yang menentukan nama DNS atau NetBIOS dari server jarak jauh tempat fungsi akan 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
1	Mengembalikan informasi akun pengguna. Parameter SortedBuffer menunjuk ke array struktur NET_DISPLAY_USER .
2	Mengembalikan informasi komputer individual. Parameter SortedBuffer menunjuk ke array struktur NET_DISPLAY_MACHINE .
3	Mengembalikan informasi akun grup. Parameter SortedBuffer menunjuk ke array struktur NET_DISPLAY_GROUP .

[in] Index

Menentukan indeks entri pertama untuk mengambil informasi. Tentukan nol untuk mengambil informasi akun yang dimulai dengan entri informasi tampilan pertama. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] EntriesRequested

Menentukan jumlah maksimum entri untuk mengambil informasi. Pada Windows 2000 dan yang lebih baru, setiap panggilan ke NetQueryDisplayInformation mengembalikan maksimum 100 objek.

[in] PreferredMaximumLength

Menentukan ukuran maksimum pilihan, dalam byte, dari buffer yang dialokasikan sistem yang dikembalikan dalam parameter SortedBuffer . Disarankan agar Anda mengatur parameter ini ke MAX_PREFERRED_LENGTH.

[out] ReturnedEntryCount

Penunjuk ke nilai yang menerima jumlah entri dalam buffer yang dikembalikan dalam parameter SortedBuffer . Jika parameter ini nol, tidak ada entri dengan indeks sebesar yang ditentukan. Entri dapat dikembalikan ketika nilai pengembalian fungsi NERR_Success atau ERROR_MORE_DATA.

[out] SortedBuffer

Penunjuk ke buffer yang menerima penunjuk ke buffer yang dialokasikan sistem yang menentukan daftar informasi yang diminta yang diurutkan. Format data ini tergantung pada nilai parameter Tingkat . Karena buffer ini dialokasikan oleh sistem, buffer ini harus dibebaskan menggunakan fungsi NetApiBufferFree . Perhatikan bahwa Anda harus membebaskan buffer meskipun fungsi gagal dengan ERROR_MORE_DATA. Untuk informasi selengkapnya, lihat bagian Nilai Pengembalian berikut, dan topik Buffer Fungsi Manajemen Jaringan dan Panjang Buffer Fungsi Manajemen Jaringan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

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

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pengguna tidak memiliki akses ke informasi yang diminta.
ERROR_INVALID_LEVEL	Parameter Level menentukan nilai yang tidak valid.
ERROR_MORE_DATA	Entri lainnya tersedia. Artinya, entri terakhir yang dikembalikan dalam parameter SortedBuffer bukan entri terakhir yang tersedia. Untuk mengambil entri tambahan, panggil NetQueryDisplayInformation lagi dengan parameter Indeks diatur ke nilai yang dikembalikan dalam anggota next_index entri terakhir di SortedBuffer. Perhatikan bahwa Anda tidak boleh menggunakan nilai anggota next_index untuk tujuan apa pun kecuali untuk mengambil lebih banyak data dengan panggilan tambahan ke NetQueryDisplayInformation.

Keterangan

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, ACE, dan token akses, lihat Model Access Control.

Fungsi NetQueryDisplayInformation hanya mengembalikan informasi di mana pemanggil memiliki akses Baca. Pemanggil harus memiliki akses Daftar Konten ke objek Domain, dan Menghitung Seluruh akses Domain SAM pada objek Sam Server yang terletak di kontainer Sistem.

Fungsi NetQueryDisplayInformation dan NetGetDisplayInformationIndex menyediakan mekanisme yang efisien untuk menghitung akun pengguna dan grup. Jika memungkinkan, gunakan fungsi ini alih-alih fungsi NetUserEnum atau fungsi NetGroupEnum .

Untuk menghitung domain tepercaya atau akun komputer anggota, panggil NetUserEnum, tentukan nilai filter yang sesuai untuk mendapatkan informasi akun yang Anda butuhkan. Untuk menghitung domain tepercaya, panggil fungsi LsaEnumerateTrustedDomains atau LsaEnumerateTrustedDomainsEx .

Jumlah entri yang dikembalikan oleh fungsi ini tergantung pada deskriptor keamanan yang terletak pada objek domain akar. API akan mengembalikan 100 entri pertama atau seluruh set entri di domain, tergantung pada hak istimewa akses pengguna. ACE yang digunakan untuk mengontrol perilaku ini adalah "SAM-Enumerate-Entire-Domain", dan diberikan kepada Pengguna Terautentikasi secara default. Administrator dapat mengubah pengaturan ini untuk memungkinkan pengguna menghitung seluruh domain.

Setiap panggilan ke NetQueryDisplayInformation mengembalikan maksimum 100 objek. Memanggil fungsi NetQueryDisplayInformation untuk menghitung informasi akun domain bisa mahal dalam hal performa. Jika Anda memprogram Direktori Aktif, Anda mungkin dapat menggunakan metode pada antarmuka IDirectorySearch untuk membuat kueri halaman terhadap domain. Untuk informasi selengkapnya, lihat IDirectorySearch::SetSearchPreference dan IDirectorySearch::ExecuteSearch. Untuk menghitung domain tepercaya, panggil fungsi LsaEnumerateTrustedDomainsEx .

Contoh

Sampel kode berikut menunjukkan cara mengembalikan informasi akun grup menggunakan panggilan ke fungsi NetQueryDisplayInformation . Jika pengguna menentukan nama server, sampel terlebih dahulu memanggil fungsi MultiByteToWideChar untuk mengonversi nama menjadi Unicode. Sampel memanggil NetQueryDisplayInformation, menentukan informasi tingkat 3 (NET_DISPLAY_GROUP) untuk mengambil informasi akun grup. Jika ada entri yang akan dikembalikan, sampel mengembalikan data dan mencetak informasi grup. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer informasi.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>
#include <lm.h>

#pragma comment(lib, "netapi32.lib")

void main( int argc, char *argv[ ] )
{
   PNET_DISPLAY_GROUP pBuff, p;
   DWORD res, dwRec, i = 0;
   //
   // You can pass a NULL or empty string
   //  to retrieve the local information.
   //
   TCHAR szServer[255]=TEXT(""); 

   if(argc > 1) 
      //
      // Check to see if a server name was passed;
      //  if so, convert it to Unicode.
      //
      MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255); 

   do // begin do
   { 
      //
      // Call the NetQueryDisplayInformation function;
      //   specify information level 3 (group account information).
      //
      res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
      //
      // If the call succeeds,
      //
      if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
      {
         p = pBuff;
         for(;dwRec>0;dwRec--)
         {
            //
            // Print the retrieved group information.
            //
            printf("Name:      %S\n"
                  "Comment:   %S\n"
                  "Group ID:  %u\n"
                  "Attributes: %u\n"
                  "--------------------------------\n",
                  p->grpi3_name,
                  p->grpi3_comment,
                  p->grpi3_group_id,
                  p->grpi3_attributes);
            //
            // If there is more data, set the index.
            //
            i = p->grpi3_next_index;
            p++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pBuff);
      }
      else
         printf("Error: %u\n", res);
   //
   // Continue while there is more data.
   //
   } while (res==ERROR_MORE_DATA); // end do
   return;
}

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