Fungsi NetShareEnum (lmshare.h)

Artikel
03/14/2023

Mengambil informasi tentang setiap sumber daya bersama di server.

Anda juga dapat menggunakan fungsi WNetEnumResource untuk mengambil informasi sumber daya. Namun, WNetEnumResource tidak menghitung berbagi tersembunyi atau pengguna yang terhubung ke berbagi.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetShareEnum(
  [in]      LMSTR   servername,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

Parameter

[in] servername

Penunjuk ke string 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 berbagi. Parameter bufptr menunjuk ke array struktur SHARE_INFO_0 .
1	Mengembalikan informasi tentang sumber daya bersama, termasuk nama dan jenis sumber daya, dan komentar yang terkait dengan sumber daya. Parameter bufptr menunjuk ke array struktur SHARE_INFO_1 .
2	Mengembalikan informasi tentang sumber daya bersama, termasuk nama sumber daya, jenis dan izin, kata sandi, dan jumlah koneksi. Parameter bufptr menunjuk ke array struktur SHARE_INFO_2 .
502	Mengembalikan informasi tentang sumber daya bersama, termasuk nama sumber daya, jenis dan izin, jumlah koneksi, dan informasi terkait lainnya. Parameter bufptr menunjuk ke array struktur SHARE_INFO_502 . Berbagi dari cakupan yang berbeda tidak dikembalikan. Untuk informasi selengkapnya tentang cakupan, lihat bagian Keterangan dari dokumentasi untuk fungsi NetServerTransportAddEx .
503	Mengembalikan informasi tentang sumber daya bersama, termasuk nama sumber daya, jenis dan izin, jumlah koneksi, dan informasi terkait lainnya. Parameter bufptr menunjuk ke array struktur SHARE_INFO_503 . Berbagi dari semua cakupan dikembalikan. Jika anggota shi503_servername struktur ini adalah "", tidak ada nama server yang dikonfigurasi dan fungsi NetShareEnum* menghitung berbagi untuk semua nama yang tidak terlingkup. Windows Server 2003 dan Windows XP: Tingkat informasi ini tidak didukung.

[out] bufptr

Arahkan 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

Menentukan panjang maksimum data yang dikembalikan, dalam byte. Jika Anda menentukan MAX_PREFERRED_LENGTH, fungsi 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 akan mengembalikan ERROR_MORE_DATA. Untuk informasi selengkapnya, lihat Buffer Fungsi Manajemen Jaringan dan Panjang Buffer Fungsi Manajemen Jaringan.

[out] entriesread

Pointer ke nilai yang menerima hitungan elemen yang benar-benar dijumlahkan.

[out] totalentries

Penunjuk ke nilai yang menerima jumlah total entri yang bisa saja dijumlahkan. Perhatikan bahwa aplikasi harus mempertimbangkan nilai ini hanya sebagai petunjuk.

[in, out] resume_handle

Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian berbagi yang sudah ada. Handel harus nol pada panggilan pertama dan dibiarkan tidak berubah untuk panggilan berikutnya. Jika resume_handleNULL, maka tidak ada handel lanjutan yang disimpan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem. Untuk daftar kode kesalahan, lihat Kode Kesalahan Sistem.

Keterangan

Fungsi ini hanya berlaku untuk berbagi Blok Pesan Server (SMB). Untuk jenis berbagi lainnya, seperti berbagi Distributed File System (DFS) atau WebDAV, gunakan fungsi Windows Networking (WNet), yang mendukung semua jenis berbagi.

Untuk pengguna interaktif (pengguna yang masuk secara lokal ke komputer), tidak ada keanggotaan grup khusus yang diperlukan untuk menjalankan fungsi NetShareEnum . Untuk pengguna non-interaktif, Administrator, Pengguna Daya, Operator Cetak, atau keanggotaan grup Operator Server diperlukan untuk berhasil menjalankan fungsi NetShareEnum pada tingkat 2, 502, dan 503. Tidak diperlukan keanggotaan grup khusus untuk panggilan tingkat 0 atau tingkat 1.

Windows Server 2022: Untuk pengguna non-interaktif, Administrator, Access Control Operator Bantuan, atau keanggotaan grup Operator Server diperlukan untuk berhasil menjalankan fungsi NetShareEnum pada tingkat 2, 502, dan 503.

Windows Server 2003 dan Windows XP: Untuk semua pengguna, Administrator, Pengguna Daya, Operator Cetak, atau keanggotaan grup Operator Server diperlukan untuk berhasil menjalankan fungsi NetShareEnum pada tingkat 2 dan 502.

Untuk mengambil nilai yang menunjukkan apakah berbagi adalah volume akar dalam struktur pohon DFS, Anda harus memanggil fungsi NetShareGetInfo dan menentukan tingkat informasi 1005.

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 berbagi manajemen jaringan. Untuk informasi selengkapnya, lihat IADsFileShare.

Contoh

Sampel kode berikut menunjukkan cara mengambil informasi tentang setiap sumber daya bersama di server menggunakan panggilan ke fungsi NetShareEnum . Sampel memanggil NetShareEnum, menentukan tingkat informasi 502 (SHARE_INFO_502). Jika panggilan berhasil, kode akan mengulang entri dan mencetak informasi tentang setiap berbagi. Sampel juga memanggil fungsi IsValidSecurityDescriptor untuk memvalidasi anggota shi502_security_descriptor . 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")
#pragma comment(lib, "Advapi32.lib")

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr,p;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL;
   DWORD er=0,tr=0,resume=0, i;

   switch(argc)
   {
   case 2:
      lpszServer = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareEnum <servername>\n");
      return;
   }
   //
   // Print a report header.
   //
   printf("Share:              Local Path:                   Uses:   Descriptor:\n");
   printf("---------------------------------------------------------------------\n");
   //
   // Call the NetShareEnum function; specify level 502.
   //
   do // begin do
   {
      res = NetShareEnum (lpszServer, 502, (LPBYTE *) &BufPtr, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If the call succeeds,
      //
      if(res == ERROR_SUCCESS || res == ERROR_MORE_DATA)
      {
         p=BufPtr;
         //
         // Loop through the entries;
         //  print retrieved data.
         //
         for(i=1;i<=er;i++)
         {
            printf("%-20S%-30S%-8u",p->shi502_netname, p->shi502_path, p->shi502_current_uses);
            //
            // Validate the value of the 
            //  shi502_security_descriptor member.
            //
            if (IsValidSecurityDescriptor(p->shi502_security_descriptor))
               printf("Yes\n");
            else
               printf("No\n");
            p++;
         }
         //
         // Free the allocated buffer.
         //
         NetApiBufferFree(BufPtr);
      }
      else 
         printf("Error: %ld\n",res);
   }
   // Continue to call NetShareEnum while 
   //  there are more entries. 
   // 
   while (res==ERROR_MORE_DATA); // end do
   return;
}

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	lmshare.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll