Funzione NetUserModalsSet (lmaccess.h)

Articolo
03/09/2023

La funzione NetUserModalsSet imposta informazioni globali per tutti gli utenti e i gruppi globali nel database di sicurezza, ovvero il database di gestione degli account di sicurezza (SAM) o, nel caso dei controller di dominio, Active Directory.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetUserModalsSet(
  [in]  LPCWSTR servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

Parametri

[in] servername

Puntatore a una stringa costante che specifica il nome DNS o NetBIOS del server remoto in cui deve essere eseguita la funzione. Se questo parametro è NULL, viene utilizzato il computer locale.

[in] level

Specifica il livello di informazioni dei dati. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
0	Specifica i parametri globali della password. Il parametro buf punta a una struttura USER_MODALS_INFO_0 .
1	Specifica le informazioni sul server di accesso e sul controller di dominio. Il parametro buf punta a una struttura USER_MODALS_INFO_1 .
2	Specifica il nome di dominio e l'identificatore. Il parametro buf punta a una struttura USER_MODALS_INFO_2 .
3	Specifica le informazioni sul blocco. Il parametro buf punta a una struttura USER_MODALS_INFO_3 .
1001	Specifica la lunghezza minima consentita della password. Il parametro buf punta a una struttura USER_MODALS_INFO_1001 .
1002	Specifica la validità massima consentita della password. Il parametro buf punta a una struttura USER_MODALS_INFO_1002 .
1003	Specifica la validità minima consentita della password. Il parametro buf punta a una struttura USER_MODALS_INFO_1003 .
1004	Specifica le informazioni sulla disconnessione forzata. Il parametro buf punta a una struttura USER_MODALS_INFO_1004 .
1005	Specifica la lunghezza della cronologia delle password. Il parametro buf punta a una struttura USER_MODALS_INFO_1005 .
1006	Specifica il ruolo del server di accesso. Il parametro buf punta a una struttura USER_MODALS_INFO_1006 .
1007	Specifica le informazioni sul controller di dominio. Il parametro buf punta a una struttura USER_MODALS_INFO_1007 .

[in] buf

Puntatore al buffer che specifica i dati. Il formato di questi dati dipende dal valore del parametro level . Per altre informazioni, vedere Buffer delle funzioni di gestione di rete.

[out] parm_err

Puntatore a un valore che riceve l'indice del primo membro della struttura delle informazioni che causa ERROR_INVALID_PARAMETER. Se questo parametro è NULL, l'indice non viene restituito in caso di errore. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	L'utente non ha accesso alle informazioni richieste.
ERROR_INVALID_PARAMETER	Il parametro specificato non è valido. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
NERR_InvalidComputer	Il nome del computer non è valido.
NERR_UserNotFound	Impossibile trovare il nome utente.

Commenti

Se si esegue la programmazione per Active Directory, è possibile chiamare determinati metodi ADSI (Active Directory Service Interface) per ottenere la stessa funzionalità che è possibile ottenere chiamando le funzioni modali dell'utente di gestione di rete. Per altre informazioni, vedere IADsDomain.

Se si chiama questa funzione in un controller di dominio che esegue Active Directory, l'accesso viene consentito o negato in base all'elenco di controllo di accesso (ACL) per l'oggetto a protezione diretta. L'elenco di controllo di accesso predefinito consente solo agli amministratori di dominio e agli operatori account di chiamare questa funzione. In un server membro o in una workstation, solo gli amministratori e Power Users possono chiamare questa funzione. Per altre informazioni, vedere Requisiti di sicurezza per le funzioni di gestione di rete. Per altre informazioni su ACL, ACL e token di accesso, vedere Controllo di accesso Model.

Il descrittore di sicurezza dell'oggetto Domain viene utilizzato per eseguire il controllo di accesso per questa funzione. In genere, i chiamanti devono avere accesso in scrittura all'intero oggetto per consentire l'esito positivo delle chiamate a questa funzione.

Se la funzione NetUserModalsSet restituisce ERROR_INVALID_PARAMETER, è possibile usare il parametro parm_err per indicare il primo membro della struttura delle informazioni non valida. La struttura delle informazioni inizia con USER_MODALS_INFO_ e il relativo formato viene specificato dal parametro level . Nella tabella seguente sono elencati i valori che è possibile restituire nel parametro parm_err e nel membro della struttura corrispondente in errore. Il prefisso usrmod*_ indica che il membro può iniziare con più prefissi, ad esempio usrmod2_ o usrmod1002_.

Valore	Membro
MODALS_MIN_PASSWD_LEN_PARMNUM	usrmod*_min_passwd_len
MODALS_MAX_PASSWD_AGE_PARMNUM	usrmod*_max_passwd_age
MODALS_MIN_PASSWD_AGE_PARMNUM	usrmod*_min_passwd_age
MODALS_FORCE_LOGOFF_PARMNUM	usrmod*_force_logoff
MODALS_PASSWD_HIST_LEN_PARMNUM	usrmod*_password_hist_len
MODALS_ROLE_PARMNUM	usrmod*_role
MODALS_PRIMARY_PARMNUM	usrmod*_primary
MODALS_DOMAIN_NAME_PARMNUM	usrmod*_domain_name
MODALS_DOMAIN_ID_PARMNUM	usrmod*_domain_id
MODALS_LOCKOUT_DURATION_PARMNUM	usrmod*_lockout_duration
MODALS_LOCKOUT_OBSERVATION_WINDOW_PARMNUM	usrmod*_lockout_observation_window
MODALS_LOCKOUT_THRESHOLD_PARMNUM	usrmod*_lockout_threshold

Esempio

L'esempio di codice seguente illustra come impostare le informazioni globali per tutti gli utenti e i gruppi globali con una chiamata alla funzione NetUserModalsSet . L'esempio compila i membri della struttura USER_MODALS_INFO_0 e chiama NetUserModalsSet, specificando il livello di informazioni 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 ui;
   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];
   //
   // Fill in the USER_MODALS_INFO_0 structure.
   //
   ui.usrmod0_min_passwd_len = 0;
   ui.usrmod0_max_passwd_age = (86400 * 30);
   ui.usrmod0_min_passwd_age = 0;
   ui.usrmod0_force_logoff = TIMEQ_FOREVER; // never force logoff
   ui.usrmod0_password_hist_len = 0;
   //
   // Call the NetUserModalsSet function; specify level 0.
   //
   nStatus = NetUserModalsSet((LPCWSTR) pszServerName,
                              dwLevel,
                              (LPBYTE)&ui,
                              NULL);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Modals information set successfully on %s\n", argv[1]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmaccess.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll