NetServerDiskEnum 函式 (lmserver.h)

發行項
08/24/2023

NetServerDiskEnum函式會擷取伺服器上的磁片磁碟機清單。函式會傳回三個字元字串的陣列， (磁碟機號、冒號和終止的 null 字元) 。

語法

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
);

參數

[in] servername

字串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

[in] level

所需的資訊層級。值為零是唯一有效的層級。

[out] bufptr

接收資料的緩衝區指標。資料是三個字元字串的陣列， (磁碟機號、冒號和終止 null 字元) 。此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。請注意，即使函式因ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。

[in] prefmaxlen

所傳回資料的慣用最大長度，以位元組為單位。如果您指定MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足以保存所有專案，函式會傳回ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理函式緩衝區長度。

注意此參數目前會被忽略。

[out] entriesread

值指標，可接收實際列舉的專案計數。

[out] totalentries

值的指標，接收可能已從目前繼續位置列舉的專案總數。請注意，應用程式應該只將此值視為提示。

[in, out] resume_handle

值的指標，其中包含用來繼續搜尋現有伺服器磁片的繼續控制碼。第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。如果 resume_handle 參數是 Null 指標，則不會儲存任何繼續控制碼。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
ERROR_INVALID_LEVEL	為 level 參數指定的值無效。
ERROR_MORE_DATA	有更多專案可供使用。指定夠大的緩衝區來接收所有專案。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
ERROR_NOT_SUPPORTED	不支援此要求。如果在 servername 參數中指定遠端伺服器，則傳回此錯誤，遠端伺服器僅支援使用舊版遠端存取通訊協定機制的遠端 RPC 呼叫，而且不支援此要求。

備註

只有 Administrators 或 Server Operators 本機群組的成員可以在遠端電腦上成功執行 NetServerDiskEnum 函式。

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的結果，方法是呼叫網路管理伺服器函式。如需詳細資訊，請參閱 IADsComputer 介面參考。

範例

下列程式碼範例示範如何呼叫 NetServerDiskEnum 函式，以擷取伺服器上的磁片磁碟機清單。此範例會呼叫 NetServerDiskEnum，並指定所需的資訊層級 0 () 。如果有專案可傳回，而且使用者可以存取訊號，則會以三個字元字串的格式列印磁片磁碟機清單：磁碟機號、冒號和終止 Null 字元。此範例也會列印可用的專案總數，以及實際列舉專案數目的相關提示。最後，程式碼範例會釋放為緩衝區配置的記憶體。

#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;
}

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	lmserver.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll