共用方式為


NetQueryDisplayInformation 函式 (lmaccess.h)

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 網域存取權。

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

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

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

每次呼叫 NetQueryDisplayInformation 時,最多會傳回 100 個物件。 呼叫 NetQueryDisplayInformation 函式 來列舉網域帳戶資訊,在效能方面可能昂貴。 如果您是針對 Active Directory 進行程式設計,則可以使用 IDirectorySearch 介面上的方法,對網域進行分頁查詢。 如需詳細資訊,請參閱 IDirectorySearch::SetSearchPreferenceIDirectorySearch::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

另請參閱

取得函式

LsaEnumerateTrustedDomains

LsaEnumerateTrustedDomainsEx

NET_DISPLAY_GROUP

NET_DISPLAY_MACHINE

NET_DISPLAY_USER

NetGetDisplayInformationIndex

NetGroupEnum

NetUserEnum

網路管理功能

網路管理概觀