Fungsi NetServerDiskEnum (lmserver.h)

Artikel
03/14/2023

Fungsi NetServerDiskEnum mengambil daftar drive disk di server. Fungsi mengembalikan array string tiga karakter (huruf kandar, titik dua, dan karakter null yang mengakhiri).

Sintaks

NET_API_STATUS NET_API_FUNCTION NetServerDiskEnum(
  [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

Tingkat informasi yang diperlukan. Nilai nol adalah satu-satunya tingkat yang valid.

[out] bufptr

Penunjuk ke buffer yang menerima data. Data adalah array string tiga karakter (huruf kandar, titik dua, dan karakter null yang mengakhiri). 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 data yang dikembalikan yang disukai, 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.

Catatan Parameter ini saat ini diabaikan.

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

[in, out] resume_handle

Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian disk server yang ada. Handel harus nol pada panggilan pertama dan dibiarkan tidak berubah untuk panggilan berikutnya. Jika parameter resume_handle adalah penunjuk NULL , maka tidak ada handel resume yang disimpan.

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 akses ke informasi yang diminta.
ERROR_INVALID_LEVEL	Nilai yang ditentukan untuk parameter tingkat tidak valid.
ERROR_MORE_DATA	Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika server jarak jauh ditentukan dalam parameter nama server , server jarak jauh hanya mendukung panggilan RPC jarak jauh menggunakan mekanisme Protokol Akses Jarak Jauh warisan, dan permintaan ini tidak didukung.

Keterangan

Hanya anggota grup lokal Administrator atau Operator Server yang berhasil menjalankan fungsi NetServerDiskEnum pada komputer jarak jauh.

Jika Anda memprogram Direktori Aktif, Anda mungkin dapat memanggil metode Antarmuka Layanan Direktori Aktif (ADSI) tertentu untuk mencapai hasil yang sama yang dapat Anda capai dengan memanggil fungsi server manajemen jaringan. Untuk informasi selengkapnya, lihat referensi antarmuka IADsComputer .

Contoh

Sampel kode berikut menunjukkan cara memanggil fungsi NetServerDiskEnum untuk mengambil daftar drive disk di server. Sampel memanggil NetServerDiskEnum, menentukan tingkat informasi 0 (diperlukan). Jika ada entri yang akan dikembalikan, dan pengguna memiliki akses ke informasi, itu mencetak daftar drive, dalam format string tiga karakter: huruf drive, titik dua, dan karakter null yang mengakhiri. Sampel juga mencetak jumlah total entri yang tersedia dan petunjuk tentang jumlah entri yang benar-benar dijumlahkan. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer.

#ifndef UNICODE
#define UNICODE
#endif

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

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

int wmain(int argc, wchar_t *argv[])
{
   const int ENTRY_SIZE = 3; // Drive letter, colon, NULL
   LPTSTR pBuf = NULL;
   DWORD dwLevel = 0; // level must be zero
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;
   LPWSTR 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];
   //
   // Call the NetServerDiskEnum function.
   //
   nStatus = NetServerDiskEnum(pszServerName,
                               dwLevel,
                               (LPBYTE *) &pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               NULL);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPTSTR pTmpBuf;

      if ((pTmpBuf = pBuf) != NULL)
      {
         DWORD i;
         DWORD dwTotalCount = 0;
         //
         // Loop through the entries.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               // On a remote computer, only members of the
               //  Administrators or the Server Operators 
               //  local group can execute NetServerDiskEnum.
               //
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Print drive letter, colon, NULL for each drive;
            //   the number of entries actually enumerated; and
            //   the total number of entries available.
            //
            fwprintf(stdout, L"\tDisk: %S\n", pTmpBuf);

            pTmpBuf += ENTRY_SIZE;
            dwTotalCount++;
         }

         fprintf(stderr, "\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	lmserver.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll