NetUserModalsGet-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetUserModalsGet-Funktion ruft globale Informationen für alle Benutzer und globalen Gruppen in der Sicherheitsdatenbank ab. Hierbei handelt es sich um die SAM-Datenbank (Security Accounts Manager) oder im Fall von Domänencontrollern um active Directory.

Syntax

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

Parameter

[in, optional] servername

Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] level

Die Informationsebene der angeforderten Daten. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
0	Gibt globale Kennwortparameter zurück. Der bufptr-Parameter verweist auf eine USER_MODALS_INFO_0 Struktur.
1	Gibt Anmeldeserver- und Domänencontrollerinformationen zurück. Der bufptr-Parameter verweist auf eine USER_MODALS_INFO_1-Struktur .
2	Gibt Domänennamen und Bezeichner zurück. Der bufptr-Parameter verweist auf eine USER_MODALS_INFO_2-Struktur . Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
3	Gibt Sperrinformationen zurück. Der bufptr-Parameter verweist auf eine USER_MODALS_INFO_3-Struktur .

Eine NULL-Sitzungsanmeldung kann NetUserModalsGet anonym auf den Informationsebenen 0 und 3 aufrufen.

[out] bufptr

Ein Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab.

Der Puffer für diese Daten wird vom System zugewiesen, und die Anwendung muss die NetApiBufferFree-Funktion aufrufen, um den zugewiesenen Arbeitsspeicher freizugeben, wenn die zurückgegebenen Daten nicht mehr benötigt werden. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen.
ERROR_BAD_NETPATH	Der Netzwerkpfad wurde nicht gefunden.“ Dieser Fehler wird zurückgegeben, wenn der Parameter servername nicht gefunden wurde.
ERROR_INVALID_LEVEL	Die Ebene des Systemaufrufs ist falsch. Dieser Fehler wird zurückgegeben, wenn der Levelparameter nicht einer der unterstützten Werte ist.
ERROR_INVALID_NAME	Die Syntax des Dateinamens, des Verzeichnisnamens oder der Volumebezeichnung ist falsch. Dieser Fehler wird zurückgegeben, wenn die Syntax des Serversname-Parameters falsch ist.
ERROR_WRONG_TARGET_NAME	Der Name des Zielkontos ist falsch. Dieser Fehler wird für einen Anmeldefehler bei einem Remoteservername-Parameter zurückgegeben, der unter Windows Vista ausgeführt wird.
NERR_InvalidComputer	Der Computername ist ungültig.

Hinweise

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Modalfunktionen des Benutzers für die Netzwerkverwaltung erreichen können. Weitere Informationen finden Sie unter IADsDomain.

Wenn Sie diese Funktion auf einem Domänencontroller aufrufen, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der Zugriffssteuerungsliste (Access Control List, ACL) für das sicherungsfähige Objekt zugelassen oder verweigert. Die Standard-ACL ermöglicht es allen authentifizierten Benutzern und Mitgliedern der Gruppe "Pre-Windows 2000-kompatibler Zugriff", die Informationen anzuzeigen. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Informationen zum anonymen Zugriff und zum Einschränken des anonymen Zugriffs auf diesen Plattformen finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.

Die Sicherheitsbeschreibung des Domain-Objekts wird verwendet, um die Zugriffsprüfung für diese Funktion durchzuführen.

Um den Sicherheitsbezeichner (SID) der Domäne abzurufen, zu der der Computer gehört, rufen Sie die NetUserModalsGet-Funktion auf, indem Sie eine USER_MODALS_INFO_2 Struktur und NULL im Servername-Parameter angeben. Wenn der Computer kein Mitglied einer Domäne ist, gibt die Funktion einen NULL-Zeiger zurück.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie globale Informationen für alle Benutzer und globalen Gruppen mit einem Aufruf der NetUserModalsGet-Funktion abgerufen werden. Im Beispiel wird NetUserModalsGet aufgerufen, wobei die Informationsebene 0 (USER_MODALS_INFO_0) angegeben wird. Wenn der Aufruf erfolgreich ist, werden im Beispiel globale Kennwortinformationen ausgegeben. Schließlich gibt das Codebeispiel den Für den Informationspuffer zugewiesenen Arbeitsspeicher frei.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmaccess.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll