NetQueryDisplayInformation 函式 (lmaccess.h)

發行項
08/24/2023

NetQueryDisplayInformation 函式會傳回使用者帳戶、電腦或組帳戶資訊。呼叫此函式以快速列舉要顯示在使用者介面中的帳戶資訊。

語法

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

參數

[in] ServerName

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

[in] Level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
1	傳回使用者帳戶資訊。 SortedBuffer參數會指向NET_DISPLAY_USER結構的陣列。
2	傳回個別的電腦資訊。 SortedBuffer參數會指向NET_DISPLAY_MACHINE結構的陣列。
3	傳回群組帳戶資訊。 SortedBuffer參數會指向NET_DISPLAY_GROUP結構的陣列。

[in] Index

指定要擷取資訊之第一個專案的索引。指定零，從第一個顯示資訊專案開始擷取帳戶資訊。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] EntriesRequested

指定要擷取資訊的專案數目上限。在 Windows 2000 和更新版本上，每個 對 NetQueryDisplayInformation 的呼叫都會傳回最多 100 個物件。

[in] PreferredMaximumLength

指定 SortedBuffer 參數中傳回之系統組態緩衝區的慣用大小上限，以位元組為單位。建議您將此參數設定為 MAX_PREFERRED_LENGTH。

[out] ReturnedEntryCount

值指標，這個值會接收 SortedBuffer 參數所傳回之緩衝區中的專案數。如果此參數為零，則沒有任何專案具有與指定之大小相同之索引的專案。當函式的傳回值是NERR_Success或ERROR_MORE_DATA時，可能會傳回專案。

[out] SortedBuffer

緩衝區的指標，接收系統組態之緩衝區的指標，指定所要求資訊的排序清單。此資料的格式取決於 Level 參數的值。由於此緩衝區是由系統所配置，因此必須使用 NetApiBufferFree 函式釋放該緩衝區。請注意，即使函式因ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。如需詳細資訊，請參閱下列傳回值一節，以及網路管理函數緩衝區和網路管理函式緩衝區長度主題。

傳回值

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

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

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
ERROR_INVALID_LEVEL	Level參數會指定不正確值。
ERROR_MORE_DATA	有更多專案可供使用。也就是說， SortedBuffer 參數中傳回的最後一個專案不是最後一個專案可用。若要擷取其他專案，請再次呼叫NetQueryDisplayInformation，並將Index參數設定為SortedBuffer中最後一個專案next_index成員中傳回的值。請注意，除了擷取更多資料與NetQueryDisplayInformation的其他呼叫之外，您不應該針對任何用途使用next_index成員的值。

備註

如果您在執行 Active Directory 的網域控制站上呼叫此函式，則會根據安全性實體物件的存取控制清單 (ACL) ，允許或拒絕存取。預設 ACL 允許「Windows 2000 前相容存取」群組的所有已驗證使用者和成員檢視資訊。如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。如需匿名存取和限制這些平臺上匿名存取的資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取權杖的詳細資訊，請參閱存取控制模型。

NetQueryDisplayInformation 函式只會傳回呼叫端具有讀取權限的資訊。呼叫端必須具有 Domain 物件的清單內容存取權，並在位於系統容器的 SAM Server 物件上列舉整個 SAM 網域存取權。

NetQueryDisplayInformation和NetGetDisplayInformationIndex函式提供有效機制來列舉使用者和群組帳戶。可能的話，請使用這些函式，而不是 NetUserEnum 函式或 NetGroupEnum 函式。

若要列舉信任網域或成員電腦帳戶，請呼叫 NetUserEnum，並指定適當的篩選值以取得您需要的帳戶資訊。若要列舉受信任的網域，請呼叫 LsaEnumerateTrustedDomains 或 LsaEnumerateTrustedDomainsEx 函式。

此函式傳回的專案數目取決於根域物件上的安全性描述項。 API 會根據使用者的存取權，傳回前 100 個專案或網域中的整個專案集。用來控制此行為的 ACE 是「SAM-Enumerate-Entire-Domain」，預設會授與已驗證的使用者。系統管理員可以修改此設定，讓使用者列舉整個網域。

每次呼叫 NetQueryDisplayInformation 時，最多會傳回 100 個物件。呼叫 NetQueryDisplayInformation 函式 來列舉網域帳戶資訊，在效能方面可能昂貴。如果您是針對 Active Directory 進行程式設計，則可以使用 IDirectorySearch 介面上的方法，對網域進行分頁查詢。如需詳細資訊，請參閱 IDirectorySearch：：SetSearchPreference 和 IDirectorySearch：：ExecuteSearch。若要列舉受信任的網域，請呼叫 LsaEnumerateTrustedDomainsEx 函式。

範例

下列程式碼範例示範如何使用 對 NetQueryDisplayInformation 函式的呼叫傳回群組帳戶資訊。如果使用者指定伺服器名稱，範例會先呼叫 MultiByteToWideChar 函式，將名稱轉換為 Unicode。此範例會呼叫 NetQueryDisplayInformation，並指定資訊層級 3 (NET_DISPLAY_GROUP) 來擷取群組帳戶資訊。如果有專案可傳回，範例會傳回資料並列印群組資訊。最後，程式碼範例會釋放配置給資訊緩衝區的記憶體。

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

需求


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