NetUserModalsGet 函式 (lmaccess.h)

發行項
08/24/2023

NetUserModalsGet函式會擷取安全性資料庫中所有使用者和全域群組的全域資訊，也就是安全性帳戶管理員 (SAM) 資料庫，或在網域控制站的情況下，擷取 Active Directory。

語法

NET_API_STATUS NET_API_FUNCTION NetUserModalsGet(
  [in, optional] LPCWSTR servername,
  [in]           DWORD   level,
  [out]          LPBYTE  *bufptr
);

參數

[in, optional] servername

常數位符串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] level

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

值	意義
0	傳回全域密碼參數。 bufptr參數指向USER_MODALS_INFO_0結構。
1	傳回登入伺服器和網域控制站資訊。 bufptr參數指向USER_MODALS_INFO_1結構。
2	傳回功能變數名稱和識別碼。 bufptr參數指向USER_MODALS_INFO_2結構。如需詳細資訊，請參閱接下來的＜備註＞一節。
3	傳回鎖定資訊。 bufptr參數指向USER_MODALS_INFO_3結構。

Null 會話登入可以在資訊層級 0 和 3 匿名呼叫 NetUserModalsGet 。

[out] bufptr

接收資料的緩衝區指標。此資料的格式取決於 level 參數的值。

此資料的緩衝區是由系統所配置，而且應用程式必須呼叫 NetApiBufferFree 函式，以在不再需要傳回的資料時釋放配置的記憶體。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理函式緩衝區長度。

傳回值

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

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

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
ERROR_BAD_NETPATH	找不到網路路徑。如果找不到 servername 參數，則會傳回此錯誤。
ERROR_INVALID_LEVEL	系統呼叫層級不正確。如果 level 參數不是其中一個支援的值，則會傳回此錯誤。
ERROR_INVALID_NAME	檔案名、目錄名稱或磁片區標籤語法不正確。如果 servername 參數語法不正確，則會傳回此錯誤。
ERROR_WRONG_TARGET_NAME	目標帳戶名稱不正確。針對在 Windows Vista 上執行的遠端 servername 參數登入失敗，會傳回此錯誤。
NERR_InvalidComputer	電腦名稱無效。

備註

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫網路管理使用者強制回應函式。如需詳細資訊，請參閱 IADsDomain。

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

Domain 物件的安全性描述項是用來執行此函式的存取檢查。

若要擷取電腦所屬網域 (SID) 的安全性識別碼，請在servername參數中呼叫NetUserModalsGet函式，以指定USER_MODALS_INFO_2結構和Null。如果電腦不是網域的成員，函式會傳回 Null 指標。

範例

下列程式碼範例示範如何使用 對 NetUserModalsGet 函式的呼叫，擷取所有使用者和全域群組的全域資訊。此範例會呼叫 NetUserModalsGet，並指定資訊層級 0 (USER_MODALS_INFO_0) 。如果呼叫成功，範例會列印全域密碼資訊。最後，程式碼範例會釋放配置給資訊緩衝區的記憶體。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

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

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   USER_MODALS_INFO_0 *pBuf = NULL;
   NET_API_STATUS nStatus;
   LPTSTR 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 NetUserModalsGet function; specify level 0.
   //
   nStatus = NetUserModalsGet((LPCWSTR) pszServerName,
                              dwLevel,
                              (LPBYTE *)&pBuf);
   //
   // If the call succeeds, print the global information.
   //
   if (nStatus == NERR_Success)
   {
      if (pBuf != NULL)
      {
         printf("\tMinimum password length:  %d\n", pBuf->usrmod0_min_passwd_len);
         printf("\tMaximum password age (d): %d\n", pBuf->usrmod0_max_passwd_age/86400);
         printf("\tMinimum password age (d): %d\n", pBuf->usrmod0_min_passwd_age/86400);
         printf("\tForced log off time (s):  %d\n", pBuf->usrmod0_force_logoff);
         printf("\tPassword history length:  %d\n", pBuf->usrmod0_password_hist_len);
      }
   }
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

需求


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