| Main |Site Index |Download |Disclaimer |Privacy |

 

 

 

 

WINDOWS USERS & GROUPS: A SUPPLEMENTARY NOTE

 

 

 

 

This supplementary note provides information for functions and structures used in program examples oftheWindow User & Group 1 andWindow User & Group 2 tutorials.  The information compiled for NT 5 (Windows 2000 and above).

 

Page Index:

  1. Functions

  2. NetUserAdd()

  3. NetUserEnum()

  4. NetUserSetInfo()

  5. NetUserChangePassword()

  6. NetLocalGroupAdd()

  7. NetLocalGroupAddMembers()

  8. NetGetDCName()

  9. DsGetDcName()

  10. NetApiBufferFree()

  11. NetApiBufferReallocate()

  12. NetApiBufferSize()

  13. NetApiBufferAllocate()

  14. SetLastError()

  15. GetProcessHeap()

  16. lstrlen()/lstrlenW()

 

Structures

  1. USER_INFO_1

  2. USER_INFO_1008

  3. LOCALGROUP_INFO_1

  4. LOCALGROUP_MEMBERS_INFO_3

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Functions

 

NetUserAdd()

 

Item

Description

Function

NetUserAdd().

Use

To add a user account and assigns a password and privilege level.

Prototype

NET_API_STATUS NetUserAdd( LMSTR servername, DWORD level, LPBYTE buf, LPDWORD parm_err);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute.  If this parameter is NULL, the local computer is used.  This string is Unicode if_WIN32_WINNT or FORCE_UNICODE are defined.  For Windows NT:  This string must begin with \\.

level - [in] Specifies the information level of the data.  This parameter can be one of the following values.

  1. 1 - Specifies information about the user account.  The buf parameter points to aUSER_INFO_1 structure.  When you specify this level, the call initializes certain attributes to their default values.

  2. 2 - Specifies level one information and additional attributes about the user account.  Thebuf parameter points to a USER_INFO_2 structure.

  3. 3 - Specifies level two information and additional attributes about the user account.  This level is valid only on servers.  Thebuf parameter points to a USER_INFO_3 structure.  Note that it is recommended that you useUSER_INFO_4instead.

  4. 4 - Specifies level two information and additional attributes about the user account.  This level is valid only on servers. Thebuf parameter points to a USER_INFO_4 structure.  For Windows 2000/NT:  This level is not supported.

 

buf - [in] Pointer to the buffer that specifies the data.  The format of this data depends on the value of the level parameter.

parm_err - [out] Pointer to a value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER.  If this parameter is NULL, the index is not returned on error.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  2. NERR_InvalidComputer - The computer name is invalid.

  3. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain.

  4. NERR_GroupExists - The group already exists.

  5. NERR_UserExists - The user account already exists.

  6. NERR_PasswordTooShort - The password is shorter than required. (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)

Include file

<lm.h>

Remark

 

 

Table 1

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object.  The default ACL permits only Domain Admins andAccount Operators to call this function.  On a member server or workstation, only Administrators and Power Users can call this function.  For Windows NT:  Only members of the Administrators or Account Operators local group can successfully execute theNetUserAdd() function.  Only members of the Administrators local group can add an Administrators privilege account.

The security descriptor of the user container is used to perform the access check for this function.  The caller must be able to create child objects of the user class. Server users must use a system in which the server creates a WINDOWS NT system account for the new user.  The creation of this account is controlled by several parameters in the server's lanman.ini file. If the newly added user already exists as a system user, the usri1_home_dir member of the USER_INFO_1 structure is ignored. When you call theNetUserAdd() function and specify information level 1, the call initializes the additional members in the USER_INFO_2,USER_INFO_3, andUSER_INFO_4 structures to their default values.  You can change the default values by making subsequent calls to the NetUserSetInfo() function.  The default values supplied are listed in the following Table.  The prefix usriX indicates that the member can begin with multiple prefixes, for example,usri2_ orusri4_.

 

Member

Default Value

usriX_auth_flags

None (0).

usriX_full_name

None (null string).

usriX_usr_comment

None (null string).

usriX_parms

None (null string).

usriX_workstations

All (null string).

usriX_acct_expires

Never (TIMEQ_FOREVER).

usriX_max_storage

Unlimited (USER_MAXSTORAGE_UNLIMITED).

usriX_logon_hours

Logon allowed at any time (each element0xFF; all bits set to 1).

usriX_logon_server

Any domain controller (\\*).

usriX_country_code

0

usriX_code_page

0

 

Table 2.

 

User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetUserEnum()

 

Item

Description

Function

NetUserEnum().

Use

To provide information about all user accounts on a server.  To quickly enumerate user, computer, or global group account information, call theNetQueryDisplayInformation() function.

Prototype

NET_API_STATUS NetUserEnum(

  LPCWSTR servername,

  DWORD level,

  DWORD filter,

  LPBYTE* bufptr,

  DWORD prefmaxlen,

  LPDWORD entriesread,

  LPDWORD totalentries,

  LPDWORD resume_handle);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute.  If this parameter is NULL, the local computer is used.  Windows NT:  This string must begin with \\.

level - [in] Specifies the information level of the data.  This parameter can be one of the following values.

  1. 0 - Return user account names.  The bufptr parameter points to an array ofUSER_INFO_0 structures.

  2. 1 - Return detailed information about user accounts.  Thebufptr parameter points to an array ofUSER_INFO_1 structures.

  3. 2 - Return detailed information about user accounts, including authorization levels and logon information.  The bufptr parameter points to an array ofUSER_INFO_2 structures.

  4. 3 - Return detailed information about user accounts, including authorization levels, logon information, RIDs for the user and the primary group, and profile information.  The bufptr parameter points to an array ofUSER_INFO_3 structures.

  5. 10 - Return user and account names and comments.  The bufptr parameter points to an array ofUSER_INFO_10 structures.

  6. 11 - Return detailed information about user accounts.  Thebufptr parameter points to an array ofUSER_INFO_11 structures.

  7. 20 - Return the user's name and identifier and various account attributes.  Thebufptr parameter points to an array ofUSER_INFO_20 structures. Note that on Windows XP and later, it is recommended that you use USER_INFO_23 instead.

  8. 23 - Return the user's name and identifier and various account attributes.  Thebufptr parameter points to an array ofUSER_INFO_23 structures.  Windows 2000/NT:  This level is not supported.

 

filter - [in] Specifies a value that filters the account types for enumeration.  A value of zero indicates all account types.  This parameter can be one of the following values:

  1. FILTER_TEMP_DUPLICATE_ACCOUNT - Enumerates local user account data on a domain controller.

  2. FILTER_NORMAL_ACCOUNT - Enumerates global user account data on a computer.

  3. FILTER_INTERDOMAIN_TRUST_ACCOUNT - Enumerates domain trust account data on a domain controller.  The data is associated with the accounts of domains trusting the specified domain.

  4. FILTER_WORKSTATION_TRUST_ACCOUNT - Enumerates workstation or member server account data on a domain controller.

  5. FILTER_SERVER_TRUST_ACCOUNT - Enumerates domain controller account data on a domain controller.

 

bufptr - [out] Pointer to the buffer that receives the data.  The format of this data depends on the value of the level parameter.  This buffer is allocated by the system and must be freed using theNetApiBufferFree() function.  Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

prefmaxlen - [in] Specifies the preferred maximum length, in 8-bit bytes of returned data.  If you specifyMAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data.  If you specify another value in this parameter, it can restrict the number of bytes that the function returns.  If the buffer size is insufficient to hold all entries, the function returnsERROR_MORE_DATA.

entriesread - [out] Pointer to a value that receives the count of elements actually enumerated.

totalentries - [out] Pointer to a value that receives the total number of entries that could have been enumerated from the current resume position.  Note that applications should consider this value only as a hint. If your application is communicating with a Windows 2000 or later domain controller, you should consider using the ADSI LDAP Provider to retrieve this type of data more efficiently.  The ADSI LDAP Provider implements a set of ADSI objects that support various ADSI interfaces.

LAN Manager:  If the call is to a computer that is running LAN Manager 2.x, thetotalentries parameter will always reflect the total number of entries in the database no matter where it is in the resume sequence.

resume_handle - [in, out] Pointer to a value that contains a resume handle which is used to continue an existing user search.  The handle should be zero on the first call and left unchanged for subsequent calls.  Ifresume_handle is NULL, then no resume handle is stored.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  2. NERR_InvalidComputer - The computer name is invalid.

  3. ERROR_MORE_DATA - More entries are available. Specify a large enough buffer to receive all entries.

Include file

<lm.h>

Remark

-

 

Table 3.

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the access control list (ACL) for the securable object.  The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information.  If you call this function on a member server or workstation, all authenticated users can view the information.  For Windows NT:  No special group membership is required to successfully execute theNetUserEnum() function. The function only returns information to which the caller has Read access.  The caller must have List Contents access to the Domain object, and Enumerate Entire SAM Domain access on the SAM Server object located in the System container. To retrieve the names and SIDs of domains trusted by aLocal Security Authority (LSA) policy object, call theLsaEnumerateTrustedDomains() function. The NetUserEnum() function does not return all system users.  It returns only those users who have been added with a call to theNetUserAdd() function.  There is no guarantee that the list of users will be returned in sorted order.  If you call NetUserEnum() and specify information level 1, 2, 3, or 4, the password member of each structure is set to NULL to maintain password security. User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetUserSetInfo()

 

Item

Description

Function

NetUserSetInfo().

Use

To set the parameters of a user account.

Prototype

NET_API_STATUS NetUserSetInfo(

  LPCWSTR servername,

  LPCWSTR username,

  DWORD level,

  LPBYTE buf,

  LPDWORD parm_err);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute.  If this parameter is NULL, the local computer is used.  For Windows NT:  This string must begin with\\.

username - [in] Pointer to a constant string that specifies the name of the user account for which to set information.

level - [in] Specifies the information level of the data.  This parameter can be one of the following values:

  1. 0 - Specifies the user account name.  The buf parameter points to aUSER_INFO_0 structure.  Use this structure to specify a new group name.

  2. 1 - Specifies detailed information about the user account.  Thebuf parameter points to a USER_INFO_1 structure.

  3. 2 - Specifies level one information and additional attributes about the user account.  Thebuf parameter points to a USER_INFO_2 structure.

  4. 3 - Specifies level two information and additional attributes about the user account.  This level is valid only on servers. Thebuf parameter points to a USER_INFO_3 structure.  Note that it is recommended that you useUSER_INFO_4 instead.

  5. 4 - Specifies level two information and additional attributes about the user account.  This level is valid only on servers.  Thebuf parameter points to a USER_INFO_4 structure.  For Windows 2000/NT:  This level is not supported.

  6. 21 - Specifies a one-way encrypted LAN Manager 2.x-compatible password.  Thebuf parameter points to a USER_INFO_21 structure.

  7. 22 - Specifies detailed information about the user account.  Thebuf parameter points to a USER_INFO_22 structure.

  8. 1003 - Specifies a user password.  The buf parameter points to a USER_INFO_1003 structure.

  9. 1005 - Specifies a user privilege level.  The buf parameter points to aUSER_INFO_1005 structure.

  10. 1006 - Specifies the path of the home directory for the user.  Thebuf parameter points to a USER_INFO_1006 structure.

  11. 1007 - Specifies a comment to associate with the user account.  Thebuf parameter points to a USER_INFO_1007 structure.

  12. 1008 - Specifies user account attributes.  The buf parameter points to aUSER_INFO_1008 structure.

  13. 1009 - Specifies the path for the user's logon script file.  Thebuf parameter points to a USER_INFO_1009 structure.

  14. 1010 - Specifies the user's operator privileges.  The buf parameter points to aUSER_INFO_1010 structure.

  15. 1011 - Specifies the full name of the user.  The buf parameter points to aUSER_INFO_1011 structure.

  16. 1012 - Specifies a comment to associate with the user.  Thebuf parameter points to a USER_INFO_1012 structure.

  17. 1014 - Specifies the names of workstations from which the user can log on.  Thebuf parameter points to a USER_INFO_1014 structure.

  18. 1017 - Specifies when the user account expires.  The buf parameter points to aUSER_INFO_1017 structure.

  19. 1020 - Specifies the times during which the user can log on.  Thebuf parameter points to a USER_INFO_1020 structure.

  20. 1024 - Specifies the user's country/region code.  Thebuf parameter points to a USER_INFO_1024 structure.

  21. 1051 - Specifies the relative identifier of a global group that represents the enrolled user.  Thebuf parameter points to a USER_INFO_1051 structure.

  22. 1052 - Specifies the path to a network user's profile. The buf parameter points to aUSER_INFO_1052 structure.

  23. 1053 - Specifies the drive letter assigned to the user's home directory.   Thebuf parameter points to a USER_INFO_1053 structure.

 

buf - [in] Pointer to the buffer that specifies the data.  The format of this data depends on the value of the level parameter.

parm_err - [out] Pointer to a value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER.  If this parameter is NULL, the index is not returned on error.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  2. ERROR_INVALID_PARAMETER - One of the function parameters is invalid. For more information, see the following Remarks section.

  3. NERR_InvalidComputer - The computer name is invalid.

  4. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain.

  5. NERR_SpeGroupOp - The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.

  6. NERR_LastAdmin - The operation is not allowed on the last administrative account.

  7. NERR_BadPassword - The share name or password is invalid.

  8. NERR_PasswordTooShort - The password is shorter than required.  The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.

  9. NERR_UserNotFound - The user name could not be found.

Include file

<lm.h>

Remark

 

 

Table 4.

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object.  The default ACL permits only Domain Admins andAccount Operators to call this function.  On a member server or workstation, only Administrators and Power Users can call this function. Windows NT:  Only members of the Administrators or Account Operators local group can successfully execute theNetUserSetInfo() function on a remote server or on a computer that has local security enabled.  A user can call NetUserSetInfo() to set certain information on his or her own account.  The security descriptor of the User object is used to perform the access check for this function.

Only users or applications having administrative privileges can call the NetUserSetInfo() function to change a user's password.  When an administrator callsNetUserSetInfo(), the only restriction applied is that the new password length must be consistent with system modals.  A user or application that knows a user's current password can call the NetUserChangePassword() function to change the password. Members of the Administrators local group can set any modifiable user account elements.  All users can set theusri2_country_code member of the USER_INFO_2 structure (and the usri1024_country_code member of the USER_INFO_1024 structure) for their own accounts. A member of the Account Operator's local group cannot set details for an Administrators class account, give an existing account Administrator privilege, or change the operator privilege of any account.  If you attempt to change the privilege level or disable the last account with Administrator privilege in the security database, (the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory), the NetUserSetInfo() function fails and returns NERR_LastAdmin.

To set the following user account control flags, the following privileges and control access rights are required.

 

Account control flag

Privilege or right required

UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION

SeEnableDelegationPrivilege privilege, which is granted to Administrators by default.

UF_TRUSTED_FOR_DELEGATION

SeEnableDelegationPrivilege.

UF_PASSWD_NOTREQD

"Update password not required" control access right on the Domain object, which is granted to authenticated users by default.

UF_DONT_EXPIRE_PASSWD

"Unexpire password" control access right on the Domain object, which is granted to authenticated users by default.

UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED

"Enable per user reversibly encrypted password" control access right on the Domain object, which is granted to authenticated users by default.

UF_SERVER_TRUST_ACCOUNT

"Add/remove replica in domain" control access right on the Domain object, which is granted to Administrators by default.

 

Table 5.

 

The correct way to specify the new name for an account is to call NetUserSetInfo() with USER_INFO_0 and to specify the new value using theusri0_name member.  If you call NetUserSetInfo() with other information levels and specify a value using ausriX_name member, the value is ignored.

Note that calls toNetUserSetInfo() can change the home directory only for user accounts that the network server creates.  If the NetUserSetInfo() function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the user information structure that is invalid.  A user information structure begins withUSER_INFO_ and its format is specified by the level parameter.  The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error.  The prefixusri*_ indicates that the member can begin with multiple prefixes, for example,usri10_ orusri1003_.

 

Value

Member

USER_NAME_PARMNUM

usri*_name

USER_PASSWORD_PARMNUM

usri*_password

USER_PASSWORD_AGE_PARMNUM

usri*_password_age

USER_PRIV_PARMNUM

usri*_priv

USER_HOME_DIR_PARMNUM

usri*_home_dir

USER_COMMENT_PARMNUM

usri*_comment

USER_FLAGS_PARMNUM

usri*_flags

USER_SCRIPT_PATH_PARMNUM

usri*_script_path

USER_AUTH_FLAGS_PARMNUM

usri*_auth_flags

USER_FULL_NAME_PARMNUM

usri*_full_name

USER_USR_COMMENT_PARMNUM

usri*_usr_comment

USER_PARMS_PARMNUM

usri*_parms

USER_WORKSTATIONS_PARMNUM

usri*_workstations

USER_LAST_LOGON_PARMNUM

usri*_last_logon

USER_LAST_LOGOFF_PARMNUM

usri*_last_logoff

USER_ACCT_EXPIRES_PARMNUM

usri*_acct_expires

USER_MAX_STORAGE_PARMNUM

usri*_max_storage

USER_UNITS_PER_WEEK_PARMNUM

usri*_units_per_week

USER_LOGON_HOURS_PARMNUM

usri*_logon_hours

USER_PAD_PW_COUNT_PARMNUM

usri*_bad_pw_count

USER_NUM_LOGONS_PARMNUM

usri*_num_logons

USER_LOGON_SERVER_PARMNUM

usri*_logon_server

USER_COUNTRY_CODE_PARMNUM

usri*_country_code

USER_CODE_PAGE_PARMNUM

usri*_code_page

USER_PRIMARY_GROUP_PARMNUM

usri*_primary_group_id

USER_PROFILE_PARMNUM

usri*_profile

USER_HOME_DIR_DRIVE_PARMNUM

usri*_home_dir_drive

 

Table 6.

 

User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetUserChangePassword()

 

Item

Description

Function

NetUserChangePassword().

Use

To change a user's password for a specified network server or domain.

Prototype

NET_API_STATUS NetUserChangePassword(

  LPCWSTR domainname,

  LPCWSTR username,

  LPCWSTR oldpassword,

  LPCWSTR newpassword);

Parameters

domainname - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of a remote server or domain on which the function is to execute.  If this parameter is NULL, the logon domain of the caller is used.  For Windows NT:  This string must begin with\\.

username - [in] Pointer to a constant string that specifies a user name.  TheNetUserChangePassword() function changes the password for the specified user.  If this parameter is NULL, the logon name of the caller is used.

oldpassword - [in] Pointer to a constant string that specifies the user's old password.

newpassword - [in] Pointer to a constant string that specifies the user's new password.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  2. ERROR_INVALID_PASSWORD - The user has entered an invalid password.

  3. NERR_InvalidComputer - The computer name is invalid.

  4. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain.

  5. NERR_UserNotFound - The user name could not be found.

  6. NERR_PasswordTooShort - The password is shorter than required.  The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.

Include file

<lm.h>

Remark

 

 

Table 7.

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object.  The default ACL permits only Domain Admins andAccount Operators to call this function.  On a member server or workstation, only Administrators and Power Users can call this function. A user can change his or her own password.

Windows NT:  A server or domain can be configured to require a user to log on before changing the password on a user account.  In that case, only members of the Administrators or Account Operators local group or the user can change the password for a user account.  If logon is not required, a user can change the password for any user account, as long as the user knows the current password. The security descriptor of the User object is used to perform the access check for this function.  In addition, the caller must have the "Change password" control access right on the User object.

This right is granted to Anonymous Logon and Everyone by default. Note that for the function to succeed, the oldpassword parameter must match the password as it currently exists. In some cases, the process that calls theNetUserChangePassword() function must also have theSE_CHANGE_NOTIFY_NAME privilege enabled; otherwise,NetUserChangePassword() fails and GetLastError() returns ERROR_ACCESS_DENIED.  This privilege is not required for theLocalSystem account or for accounts that are members of the administrators group.  By default,SE_CHANGE_NOTIFY_NAME is enabled for all users, but some administrators may disable the privilege for everyone. User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetLocalGroupAdd()

 

Item

Description

Function

NetLocalGroupAdd().

Use

To create a local group in the security database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

Prototype

NET_API_STATUS NetLocalGroupAdd(

  LPCWSTR servername,

  DWORD level,

  LPBYTE buf,

  LPDWORD parm_err);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used.  Windows NT:  This string must begin with\\.

level - [in] Specifies the information level of the data.  This parameter can be one of the following values:

  1. 0 - Specifies a local group name.  The buf parameter points to a LOCALGROUP_INFO_0 structure.

  2. 1 - Specifies a local group name and a comment to associate with the group.  Thebuf parameter points to a LOCALGROUP_INFO_1 structure.

 

buf - [in] Pointer to a buffer that contains the local group information structure.  The format of this data depends on the value of thelevel parameter.

parm_err - [out] Pointer to a value that receives the index of the first member of the local group information structure to cause the ERROR_INVALID_PARAMETER error.  If this parameter is NULL, the index is not returned on error.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  2. NERR_InvalidComputer - The computer name is invalid.

  3. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain.

  4. NERR_GroupExists - The local group already exists.

  5. ERROR_ALIAS_EXISTS - The local group already exists.

Include file

<lm.h>

Remark

 

 

Table 8.

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object.  The default ACL permits only Domain Admins andAccount Operators to call this function.  On a member server or workstation, only Administrators and Power Users can call this function. Windows NT:  Only members of the Administrators or Account Operators local group can successfully execute theNetLocalGroupAdd() function. The security descriptor of the user container is used to perform the access check for this function.  The caller must be able to create child objects of the group class. User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetLocalGroupAddMembers()

 

Item

Description

Function

NetLocalGroupAddMembers().

Use

To add membership of one or more existing user accounts or global group accounts to an existing local group.  The function does not change the membership status of users or global groups that are currently members of the local group.

Prototype

NET_API_STATUS NetLocalGroupAddMembers(

  LPCWSTR servername,

  LPCWSTR groupname,

  DWORD level,

  LPBYTE buf,

  DWORD totalentries);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute.  If this parameter is NULL, the local computer is used.  Windows NT:  This string must begin with\\.

groupname - [in] Pointer to a constant string that specifies the name of the local group to which the specified users or global groups will be added.

level - [in] Specifies the information level of the data.  This parameter can be one of the following values:

  1. 0 - Specifies the security identifier (SID) of the new local group member.  The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.

  2. 3 - Specifies the domain and name of the new local group member.  The buf parameter points to an array ofLOCALGROUP_MEMBERS_INFO_3 structures.

 

buf - [in] Pointer to a buffer that contains the data for the new local group members.  The format of this data depends on the value of thelevel parameter.

totalentries - [in] Specifies the number of entries in the buffer pointed to by thebuf parameter.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value can be one of the following error codes.

  1. NERR_GroupNotFound - The local group specified by thegroupname parameter does not exist.

  2. ERROR_ACCESS_DENIED - The user does not have access to the requested information.

  3. ERROR_NO_SUCH_MEMBER - One or more of the members specified do not exist.  Therefore, no new members were added.

  4. ERROR_MEMBER_IN_ALIAS - One or more of the members specified were already members of the local group.  No new members were added.

  5. ERROR_INVALID_MEMBER - One or more of the members cannot be added because their account type is invalid.  No new members were added.

Include file

<lm.h>

Remark

-

 

Table 9.

 

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object.  The default ACL permits only Domain Admins andAccount Operators to call this function.  On a member server or workstation, only Administrators and Power Users can call this function. Windows NT:  Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupAddMembers function on a remote server. The security descriptor of the LocalGroup object is used to perform the access check for this function. User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ", /, \, [, ], :, |, <, >, +, =, ;, ?, *.  Names also cannot include characters in the range 1-31, which are nonprintable.  For Windows NT 4.0:  Calls to this function fail if an account name does not meet the criteria outlined previously.

 

NetGetDCName()

 

Item

Description

Function

NetGetDCName().

Use

To return the name of the primary domain controller (PDC).  It does not return the name of the backup domain controller (BDC) for the specified domain.  Also, you cannot remote this function to a non-PDC server.

Applications that support DNS-style names should call the DsGetDcName() function.  Domain controllers in this type of environment have a multi-master directory replication relationship.  Therefore, it may be advantageous for your application to use a DC that is not the PDC. You can call theDsGetDcName() function to locate any DC in the domain;NetGetDCName() returns only the name of the PDC.

Prototype

NET_API_STATUS NetGetDCName( LPCWSTR servername, LPCWSTR domainname, LPBYTE* bufptr);

Parameters

servername - [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute.  If this parameter is NULL, the local computer is used.  For Windows NT:  This string must begin with\\.

domainname - [in] Pointer to a constant string that specifies the name of the domain.  The domain name must be a NetBIOS domain name (for example,microsoft). NetGetDCName() does not support DNS-style names (for example, microsoft.com).  If this parameter is NULL, the function returns the name of the domain controller for the primary domain.

bufptr - [out] Pointer to an allocated buffer that receives a string that specifies the server name of the PDC of the domain.  The server name is prefixed by\\.  This buffer is allocated by the system and must be freed using theNetApiBufferFree() function.

Return value

If the function succeeds, the return value isNERR_Success.  If the function fails, the return value can be one of the following error codes.

  1. NERR_DCNotFound - Could not find the domain controller for the domain.

  2. ERROR_INVALID_NAME - The name could not be found.

Include file

<lm.h>

Remark

No special group membership is required to successfully execute theNetGetDCName() function.

 

Table 10.

 

DsGetDcName()

 

Some provocation :o).  For Domain based object you can use directory service functions (the function name prefixed with dc…DsGetDcName() function provided here just for informational.  In MSDN documentation it is in Active Directory category.

 

Item

Description

Function

DsGetDcName().

Use

To return the name of a domain controller in a specified domain.  This function accepts additional domain controller selection criteria to indicate preference for a domain controller with particular characteristics.

Prototype

DWORD DsGetDcName(

  LPCTSTR ComputerName,

  LPCTSTR DomainName,

  GUID* DomainGuid,

  LPCTSTR SiteName,

  ULONG Flags,

  PDOMAIN_CONTROLLER_INFO* DomainControllerInfo);

Parameters

See below.

Return value

If the function returns domain controller data, the return value isERROR_SUCCESS.  If the function fails, the return value can be one of the following error codes:

  1. ERROR_INVALID_DOMAINNAME - The format of the specifiedDomainName is invalid.

  2. ERROR_INVALID_FLAGS - The Flags parameter contains conflicting or superfluous flags.

  3. ERROR_NOT_ENOUGH_MEMORY - A memory allocation failure occurred.

  4. ERROR_NO_SUCH_DOMAIN - No domain controller is available for the specified domain or the domain does not exist.

Include file

<dsgetdc.h>

Remark

Implemented as Unicode and ANSI on all other platforms.

 

Table 11.

 

ComputerName - [in] Pointer to a null-terminated string that specifies the name of the server to process this function. Typically, this parameter is NULL, which indicates the local computer is used.  Windows NT 4.0 server does not support remote calling of this function, so this computer name cannot be a Windows NT 4.0 server unless it is the local computer.

DomainName - [in] Pointer to a null-terminated string that specifies the name of the domain or application partition to query.  This name can either be a DNS style name, for example, fabrikam.com, or a flat-style name, for example, Fabrikam.  If a DNS style name is specified, the name may be specified with or without a trailing period.  If theFlags parameter contains the DS_GC_SERVER_REQUIRED flag, DomainName must be the name of the forest. In this case,DsGetDcName() fails if DomainName specifies a name that is not the forest root.  If theFlags parameter contains the DS_GC_SERVER_REQUIRED flag and DomainName is NULL, DsGetDcName() attempts to find a global catalog in the forest of the computer identified byComputerName, which is the local computer if ComputerName is NULL.  If DomainName is NULL and the Flags parameter contains the DS_GC_SERVER_REQUIRED flag, ComputerName is set to the default domain name of the primary domain of the computer identified by ComputerName.

DomainGuid - [in] Pointer to a GUID structure that specifies the GUID of the domain queried.  IfDomainGuid is not NULL and the domain specified byDomainName orComputerName cannot be found, DsGetDcName() attempts to locate a domain controller in the domain having the GUID specified by DomainGuid.

SiteName - [in] Pointer to a null-terminated string that specifies the name of the site where the returned domain controller should physically exist.  If this parameter is NULL,DsGetDcName() attempts to return a domain controller in the site closest to the site of the computer specified by ComputerName.  This parameter should be NULL, by default.

Flags - [in] Contains a set of flags that provide additional data used to process the request.  This parameter can be a combination of the following values:

 

Value

Meaning

DS_AVOID_SELF

When called from a domain controller, specifies that the returned domain controller name should not be the current computer.  If the current computer is not a domain controller, this flag is ignored.  This flag can be used to obtain the name of another domain controller in the domain.

DS_BACKGROUND_ONLY

If theDS_FORCE_REDISCOVERY flag is not specified, this function uses cached domain controller data.  If the cached data is more than 15 minutes old, the cache is refreshed by pinging the domain controller.  If this flag is specified, this refresh is avoided even if the cached data is expired.  This flag should be used if theDsGetDcName() function is called periodically.

DS_DIRECTORY_SERVICE_PREFERRED

DsGetDcName() attempts to find a domain controller that supports directory service functions (Microsoft® Windows® 2000 and later). If a domain controller that supports directory services is not available,DsGetDcName() returns the name of a non-directory service domain controller.  However, DsGetDcName() only returns a non-directory service domain controller after the attempt to find a directory service domain controller times out.

DS_DIRECTORY_SERVICE_REQUIRED

Requires that the returned domain controller support Windows 2000 and later.

DS_FORCE_REDISCOVERY

Forces cached domain controller data to be ignored.  This flag is used when an additional domain controller becomes available or where a domain controller has previously been detected to be unavailable.  When this flag is not specified,DsGetDcName() may return cached domain controller data. Do not use this flag unlessDsGetDcName() has been recently called without this flag and has successfully returned a domain controller.  This flag is normally not used and should only be used if a previous call toDsGetDcName() without this flag has failed.

DS_GC_SERVER_REQUIRED

Requires that the returned domain controller be a global catalog server for the forest of domains with this domain as the root.  If this flag is set and theDomainName parameter is not NULL,DomainName must specify a forest name. This flag cannot be combined with theDS_PDC_REQUIRED or DS_KDC_REQUIRED flags.

DS_GOOD_TIMESERV_PREFERRED

DsGetDcName attempts to find a domain controller that is a reliable time server.  The Windows Time Service can be configured to declare one or more domain controllers as a reliable time server.  This flag is intended to be used only by the Windows Time Service.

DS_IP_REQUIRED

DsGetDcName() will place the Internet protocol address of the domain controller in the DomainControllerAddress member of DomainControllerInfo.

DS_IS_DNS_NAME

Specifies that theDomainName parameter is a DNS name. This flag cannot be combined with theDS_IS_FLAT_NAME flag.

Specify eitherDS_IS_DNS_NAME or DS_IS_FLAT_NAME.  If neither flag is specified,DsGetDcName() may take longer to find a domain controller because it may have to search for both the DNS-style and flat name.

DS_IS_FLAT_NAME

Specifies that theDomainName parameter is a flat name. This flag cannot be combined with theDS_IS_DNS_NAME flag.

DS_KDC_REQUIRED

Requires that the returned domain controller be currently running the Kerberos Key Distribution Center service.  This flag cannot be combined with theDS_PDC_REQUIRED or DS_GC_SERVER_REQUIRED flags.

DS_ONLY_LDAP_NEEDED

Specifies that the server returned is an LDAP server.  The server returned is not necessarily a domain controller.  No other services are implied to be present at the server.  The server returned does not necessarily have a writable config container nor a writable schema container.  The server returned may not necessarily be used to create or modify security principles.  This flag may be used with theDS_GC_SERVER_REQUIRED flag to return an LDAP server that also hosts a global catalog server.  The returned global catalog server is not necessarily a domain controller. No other services are implied to be present at the server.  If this flag is specified, theDS_PDC_REQUIRED,DS_TIMESERV_REQUIRED,DS_GOOD_TIMESERV_PREFERRED,DS_DIRECTORY_SERVICES_PREFERED,DS_DIRECTORY_SERVICES_REQUIRED, and DS_KDC_REQUIRED flags are ignored.

DS_PDC_REQUIRED

Requires that the returned domain controller be the primary domain controller for the domain.  This flag cannot be combined with theDS_KDC_REQUIRED or DS_GC_SERVER_REQUIRED flags.

DS_RETURN_DNS_NAME

Specifies that the names returned in theDomainControllerName and DomainName members of DomainControllerInfo should be DNS names.  If a DNS name is not available, an error is returned.  This flag cannot be specified with theDS_RETURN_FLAT_NAME flag.  This flag implies theDS_IP_REQUIRED flag.

DS_RETURN_FLAT_NAME

Specifies that the names returned in theDomainControllerName and DomainName members of DomainControllerInfo should be flat names.  If a flat name is not available, an error is returned.  This flag cannot be specified with theDS_RETURN_DNS_NAME flag.

DS_TIMESERV_REQUIRED

Requires that the returned domain controller be currently running the Windows Time Service.

DS_WRITABLE_REQUIRED

Requires that the returned domain controller be writable; that is, host a writable copy of the directory service, for Windows 2000 and later DCs, or of SAM (for DCs in operating systems prior to Windows 2000).  A DC in an operating system prior to Windows 2000 is writable only if it is a primary domain controller.  All Windows 2000 domain controllers are writable.

 

Table 12.

 

DomainControllerInfo - [out] Pointer to aPDOMAIN_CONTROLLER_INFO value that receives a pointer to aDOMAIN_CONTROLLER_INFO structure that contains data about the domain controller selected.  This structure is allocated by DsGetDcName().  The caller must free the structure using theNetApiBufferFree() function when it is no longer required.

The DsGetDcName() function is sent to the Netlogon service on the remote computer specified by ComputerName.  If ComputerName is NULL, the function is processed on the local computer. DsGetDcName() does not verify that the domain controller name returned is the name of an actual domain controller or global catalog.  If mutual authentication is required, the caller must perform the authentication.

DsGetDcName() does not require any particular access to the specified domain.  By default, this function does not ensure that the returned domain controller is currently available.  Instead, the caller should attempt to use the returned domain controller.  If the domain controller is not available, the caller should call the DsGetDcName() function again, specifying theDS_FORCE_REDISCOVERY flag.  With the DSClient for Windows 95/98, the DsGetDcName() function is exported from logonsrv.dll and there is no corresponding library file.  Be aware that this differs from Windows 2000, whereDsGetDcName() is exported by netapi32.dll and the library file is netapi32.lib.

 

ApiBuffer Functions

 

The network management ApiBuffer functions are used to manage memory allocation.  However, in general, you should use the memory management functions category such asGlobalAlloc(),LocalAlloc() andZeroMemory() instead.  Please refer to MSDN documentation for more information.  The ApiBuffer functions are listed following.

 

Function

Description

NetApiBufferAllocate()

Allocates memory from the heap. Call this function when you require compatibility with theNetApiBufferFree() function.

NetApiBufferFree()

Frees memory allocated by theNetApiBufferAllocate() function and other network management functions.

NetApiBufferReallocate()

Changes the size of a buffer allocated by a call to the NetApiBufferAllocate() function.

NetApiBufferSize()

Returns the size, in bytes, of a buffer allocated by a call to theNetApiBufferAllocate() function.

 

Table 13.

 

For remotable functions that return information to the caller, the RPC run-time library allocates the buffer containing the return information.  When the caller has finished processing the information, it must call the NetApiBufferFree() function to free the allocated buffer.

 

NetApiBufferFree()

 

Item

Description

Function

NetApiBufferFree().

Use

To free the memory that theNetApiBufferAllocate() function allocates.  CallNetApiBufferFree() to free the memory that other network management functions return.

Prototype

NET_API_STATUS NetApiBufferFree(LPVOID Buffer);

Parameters

Buffer - [in] Pointer to a buffer returned previously by another network management function.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value is a system error code.

Include file

<lm.h>

Remark

No special group membership is required to successfully execute the ApiBuffer functions.

 

Table 14

 

NetApiBufferReallocate()

 

Item

Description

Function

NetApiBufferAllocate().

Use

To change the size of a buffer allocated by a previous call to theNetApiBufferAllocate() function.

Prototype

NET_API_STATUS NetApiBufferReallocate( LPVOID OldBuffer, DWORD NewByteCount, LPVOID* NewBuffer);

Parameters

OldBuffer - [in] Pointer to the buffer returned by a call to the NetApiBufferAllocate() function.

NewByteCount - [in] Specifies the new size of the buffer, in bytes.

NewBuffer - [out] Receives the pointer to the reallocated buffer.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value is a system error code.

Include file

<lm.h>

Remark

No special group membership is required to successfully execute the ApiBuffer functions.

 

Table 15

 

NetApiBufferSize()

 

Item

Description

Function

NetApiBufferSize().

Use

To return the size, in bytes, of a buffer allocated by a call to theNetApiBufferAllocate() function.

Prototype

NET_API_STATUS NetApiBufferSize( LPVOID Buffer, LPDWORD ByteCount);

Parameters

Buffer - [in] Pointer to a buffer returned by theNetApiBufferAllocate() function.

ByteCount - [out] Receives the size of the buffer, in bytes.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value is a system error code.

Include file

<lm.h>

Remark

No special group membership is required to successfully execute the ApiBuffer functions.

 

Table 16

 

NetApiBufferAllocate()

 

Item

Description

Function

NetApiBufferAllocate().

Use

To allocate memory from the heap.  Use this function only when compatibility with theNetApiBufferFree() function is required.  Otherwise, use the memory management functions.

Prototype

NET_API_STATUS NetApiBufferAllocate( DWORD ByteCount, LPVOID* Buffer);

Parameters

ByteCount - [in] Number of bytes to be allocated.

Buffer - [out] Receives a pointer to the allocated buffer.

Return value

If the function succeeds, the return value is NERR_Success.  If the function fails, the return value is a system error code.

Include file

<lm.h>

Remark

No special group membership is required to successfully execute the ApiBuffer functions.

 

Table 17

 

 

The following code sample demonstrates how to use the network management ApiBuffer functions.  The sample first calls theNetApiBufferAllocate() function to allocate memory and then theNetApiBufferSize() function to retrieve the size of the allocated memory.  Following this, the sample calls NetApiBufferReallocate() to change the size of the memory allocation.  Finally, the sample callsNetApiBufferFree() to free the memory.  In each case, the sample prints a message indicating success or failure.

 

// Similar to standard malloc(), realloc() and free()

// functions...

#define UNICODE

#include <windows.h>

#include <lm.h>

#include <stdio.h>

 

// Prototype for printing error function

void PrintError(LPSTR lpszApi, DWORD res);

 

int main()

{

   PUSER_INFO_10 p;

   DWORD res, dwSize;

   // Call the NetApiBufferAllocate() function to allocate the memory. If successful, print a message.

   res = NetApiBufferAllocate(1024, (LPVOID *)&p);

   if(res == NERR_Success)

   {

      printf("NetApiBufferAllocate(): Allocated 1024 bytes.\n");

     // Call the NetApiBufferSize() function to retrieve the size of the allocated buffer. If successful, print the size.

      res = NetApiBufferSize(p, &dwSize);

     if(res == NERR_Success)

      {

         printf("NetApiBufferSize(): Buffer has %u bytes.\n", dwSize);

        // Call the NetApiBufferReallocate() function to change the size of the allocated memory. If successful, print the new size of the buffer.

         res = NetApiBufferReallocate(p, dwSize * 2, (LPVOID *)&p);

        if(res == NERR_Success)

            printf("NetApiBufferReallocate(): Re-Allocated %u bytes.\n", dwSize * 2);

        else

            PrintError("NetApiBufferReallocate()", res);

        // Call the NetApiBufferFree() function to free the allocated memory. If successful, print a message.

         res = NetApiBufferFree(p);

        if(res == NERR_Success)

              printf("NetApiBufferFree(): Freed Buffer.\n");

        else

            PrintError("NetApiBufferFree()", res);

      }

     else

         PrintError("NetApiBufferSize()", res);

   }

   else

      PrintError("NetApiBufferAllocate()", res);

   return 0;

}

 

void PrintError(LPSTR lpszApi, DWORD res)

{

   printf("%s: Error %u\n", lpszApi, res);

   return;

}

NetApiBufferAllocate(): Allocated 1024 bytes.

NetApiBufferSize(): Buffer has 1024 bytes.

NetApiBufferReallocate(): Re-Allocated 2048 bytes.

NetApiBufferFree(): Freed Buffer.

Press any key to continue

 

SetLastError()

 

Item

Description

Function

SetLastError().

Use

To set the last-error code for the calling thread.

Prototype

void SetLastError(DWORD dwErrCode);

Parameters

dwErrCode - [in] Last-error code for the thread.

Return value

This function does not return a value.

Include file

<windows.h>

Remark

-

 

Table 18

 

Error codes are 32-bit values (bit 31 is the most significant bit).  Bit 29 is reserved for application-defined error codes; no system error code has this bit set.  If you are defining an error code for your application, set this bit to indicate that the error code has been defined by your application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLL).  Calling this function after an error occurs lets the DLL notify the calling application.

Most functions callSetLastError() when they fail.  Function failure is typically indicated by a return value error code such as zero, NULL, or –1.  Some functions callSetLastError() under conditions of success; those cases are noted in each function's reference topic. Applications can retrieve the value saved by this function by using the GetLastError() function. The use of GetLastError() is optional; an application can call it to find out the specific reason for a function failure.  The last-error code is kept in thread local storage so that multiple threads do not overwrite each other's values.

 

GetProcessHeap()

 

Item

Description

Function

GetProcessHeap().

Use

To obtain a handle to the heap of the calling process.  This handle can then be used in subsequent calls to the heap functions.

Prototype

HANDLE GetProcessHeap(void);

Parameters

This function has no parameters.

Return value

If the function succeeds, the return value is a handle to the calling process's heap.  If the function fails, the return value is NULL.  To get extended error information, call GetLastError().

Include file

<windows.h>

Remark

TheGetProcessHeap() function allows you to allocate memory from the process heap without having to first create a heap with theHeapCreate() function, as shown in this example:

HeapAlloc(GetProcessHeap(), 0, dwBytes);

By default, the process heap is a standard heap.  To use the low-fragmentation heap, call theHeapSetInformation() function.

 

Table 19

 

lstrlen()/lstrlenW()

 

Item

Description

Function

lstrlen()/lstrlenW().

Use

To return the length in bytes (ANSI version) orWCHAR values (Unicode version) of the specified string (not including the terminating null character).

Prototype

int lstrlen(LPCTSTR lpString);

Parameters

lpString - [in] Pointer to a null-terminated string.

Return value

The return value specifies the length of the string, in TCHAR values.  This refers to bytes forANSI versions of the function orWCHAR values for Unicode versions.

Include file

<windows.h>

Remark

Implemented as Unicode (lstrlenW()) and ANSI versions on Windows NT, Windows 2000, and Windows XP.

 

Table 20

 

Security Alert: Using this function incorrectly can compromise the security of your application.  lstrlen() assumes thatlpString is a NULL-terminated string.  If it is not, this could lead to a buffer overrun or a denial of service attack against your application.  Consider using one of the following alternatives: StringCbLength() or StringCchLength().

 

Structure

 

USER_INFO_1

 

Item

Description

Structure

USER_INFO_1.

Info

Contains information about a user account, including account name, password data, privilege level, and the path to the user's home directory.

Definition

typedef struct _USER_INFO_1 {

  LPWSTR usri1_name;

  LPWSTR usri1_password;

  DWORD usri1_password_age;

  DWORD usri1_priv;

  LPWSTR usri1_home_dir;

  LPWSTR usri1_comment;

  DWORD usri1_flags;

  LPWSTR usri1_script_path;

} USER_INFO_1, *PUSER_INFO_1, *LPUSER_INFO_1;

Members

See below.

Header file

<lm.h>

Remark

User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters:",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.

 

Table 21

 

usri1_name - Pointer to a Unicode string that specifies the name of the user account.  For theNetUserSetInfo() function, this member is ignored.

usri1_password - Pointer to a Unicode string that specifies the password of the user indicated by theusri1_name member. The length cannot exceed PWLEN bytes.  The NetUserEnum() and NetUserGetInfo() functions return a NULL pointer to maintain password security.  By convention, the length of passwords is limited to LM20_PWLEN characters.  This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, and Windows Me/98/95, clients to access a Windows server using the account.

usri1_password_age - Specifies aDWORD value that indicates the number of seconds that have elapsed since theusri1_password member was last changed.  TheNetUserAdd() andNetUserSetInfo() functions ignore this member.

usri1_priv - Specifies aDWORD value that indicates the level of privilege assigned to theusri1_name member. When you call the NetUserAdd() function, this member must beUSER_PRIV_USER. When you call the NetUserSetInfo() function, this member must be the value returned by theNetUserGetInfo() function or theNetUserEnum() function.  This member can be one of the following values.

 

Value

Meaning

USER_PRIV_GUEST

Guest.

USER_PRIV_USER

User.

USER_PRIV_ADMIN

Administrator.

 

Table 22

 

usri1_home_dir - Pointer to a Unicode string specifying the path of the home directory for the user specified in the usri1_name member.  The string can be null.

usri1_comment - Pointer to a Unicode string that contains a comment to associate with the user account.  This string can be a null string, or it can have any number of characters before the terminating null character.

usri1_flags - Specifies aDWORD value that determines several features.  This member can be one or more of the following values.  Note that setting user account control flags may require certain privileges and control access rights.

 

Value

Meaning

UF_SCRIPT

The logon script executed.  This value must be set.

UF_ACCOUNTDISABLE

The user's account is disabled.

UF_HOMEDIR_REQUIRED

The home directory is required. This value is ignored.

UF_PASSWD_NOTREQD

No password is required.

UF_PASSWD_CANT_CHANGE

The user cannot change the password.

UF_LOCKOUT

The account is currently locked out. You can call the NetUserSetInfo() function and clear this value to unlock a previously locked account.  You cannot use this value to lock a previously unlocked account.

UF_DONT_EXPIRE_PASSWD

The password should never expire on the account.

UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED

The user's password is stored under reversible encryption in the Active Directory.

UF_NOT_DELEGATED

Marks the account as "sensitive"; other users cannot act as delegates of this user account.

UF_SMARTCARD_REQUIRED

Requires the user to log on to the user account with a smart card.

UF_USE_DES_KEY_ONLY

Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.

UF_DONT_REQUIRE_PREAUTH

This account does not require Kerberos pre-authentication for logon.

UF_TRUSTED_FOR_DELEGATION

The account is enabled for delegation.  This is a security-sensitive setting; accounts with this option enabled should be tightly controlled.  This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.

UF_PASSWORD_EXPIRED

The user's password has expired.  Windows 2000/NT:  This value is not supported.

UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION

The account is trusted to authenticate a user outside of the Kerberos security package and delegate that user through constrained delegation.  This is a security-sensitive setting; accounts with this option enabled should be tightly controlled.  This setting allows a service running under the account to assert a client's identity and authenticate as that user to specifically configured services on the network.  Windows XP/2000/NT:  This value is not supported.

 

Table 23

 

The following values describe the account type.  Only one value can be set.  You cannot change the account type using theNetUserSetInfo() function.

 

Value

Meaning

UF_NORMAL_ACCOUNT

This is a default account type that represents a typical user.

UF_TEMP_DUPLICATE_ACCOUNT

This is an account for users whose primary account is in another domain.  This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.

UF_WORKSTATION_TRUST_ACCOUNT

This is a computer account for a computer that is a member of this domain.

UF_SERVER_TRUST_ACCOUNT

This is a computer account for a backup domain controller that is a member of this domain.

UF_INTERDOMAIN_TRUST_ACCOUNT

This is a permit to trust account for a domain that trusts other domains.

 

Table 24

 

usri1_script_path - Pointer to a Unicode string specifying the path for the user's logon script file.  The script file can be a .cmd file, an .exe file, or a .bat file.  The string can also be null.

 

USER_INFO_1008

 

Item

Description

Structure

USER_INFO_1008.

Info

Contains a set of bit flags defining several user network account parameters.  This information level is valid only when you call theNetUserSetInfo() function.

Definition

typedef struct _USER_INFO_1008 {

  DWORD usri1008_flags;

} USER_INFO_1008, *PUSER_INFO_1008, *LPUSER_INFO_1008;

Members

See below.

Header file

<lm.h>

Remark

-

 

Table 25

 

usri1008_flags - Specifies aDWORD value that determines several features to associate with the user account specified in theusername parameter to the NetUserSetInfo() function.  This member can be one or more of the following values.  Note that setting user account control flags may require certain privileges and control access rights.

 

Value

Meaning

UF_SCRIPT

The logon script executed.  This value must be set.

UF_ACCOUNTDISABLE

The user's account is disabled.

UF_HOMEDIR_REQUIRED

The home directory is required.  This value is ignored.

UF_PASSWD_NOTREQD

No password is required.

UF_PASSWD_CANT_CHANGE

The user cannot change the password.

UF_LOCKOUT

The account is currently locked out.  You can call theNetUserSetInfo() function to clear this value and unlock a previously locked account.  You cannot use this value to lock a previously unlocked account.

UF_DONT_EXPIRE_PASSWD

The password should never expire on the account.

UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED

The user's password is stored under reversible encryption in the Active Directory.

UF_NOT_DELEGATED

Marks the account as "sensitive"; other users cannot act as delegates of this user account.

UF_SMARTCARD_REQUIRED

Requires the user to log on to the user account with a smart card.

UF_USE_DES_KEY_ONLY

Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.

UF_DONT_REQUIRE_PREAUTH

This account does not require Kerberos pre-authentication for logon.

UF_TRUSTED_FOR_DELEGATION

The account is enabled for delegation.  This is a security-sensitive setting; accounts with this option enabled should be tightly controlled.  This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.

UF_PASSWORD_EXPIRED

The user's password has expired.  Windows 2000/NT:  This value is not supported.

UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION

The account is trusted to authenticate a user outside of the Kerberos security package and delegate that user through constrained delegation.  This is a security-sensitive setting; accounts with this option enabled should be tightly controlled.  This setting allows a service running under the account to assert a client's identity and authenticate as that user to specifically configured services on the network.  Windows XP/2000/NT:  This value is not supported.

 

Table 26

 

The following values describe the account type.  Only one value can be set.  You cannot change the account type using theNetUserSetInfo() function.

 

Value

Meaning

UF_NORMAL_ACCOUNT

This is a default account type that represents a typical user.

UF_TEMP_DUPLICATE_ACCOUNT

This is an account for users whose primary account is in another domain.  This account provides user access to this domain, but not to any domain that trusts this domain.  The User Manager refers to this account type as a local user account.

UF_WORKSTATION_TRUST_ACCOUNT

This is a computer account for a computer that is a member of this domain.

UF_SERVER_TRUST_ACCOUNT

This is a computer account for a backup domain controller that is a member of this domain.

UF_INTERDOMAIN_TRUST_ACCOUNT

This is a permit to trust account for a domain that trusts other domains.

 

Table 27

 

LOCALGROUP_INFO_1

 

Item

Description

Structure

LOCALGROUP_INFO_1.

Info

Contains a local group name and a comment describing the local group.

Definition

typedef struct _LOCALGROUP_INFO_1 {

  LPWSTR lgrpi1_name;

  LPWSTR lgrpi1_comment;

} LOCALGROUP_INFO_1, *PLOCALGROUP_INFO_1, *LPLOCALGROUP_INFO_1;

Members

lgrpi1_name - Pointer to a Unicode string that specifies a local group name.  This member is ignored when you call theNetLocalGroupSetInfo() function.

lgrpi1_comment - Pointer to a Unicode string that contains a remark associated with the local group.  This member can be a null string.  The comment can have as many asMAXCOMMENTSZ characters.

Header file

<lm.h>

Remark

User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters:",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.

 

Table 28

 

LOCALGROUP_MEMBERS_INFO_3

 

Item

Description

Structure

LOCALGROUP_MEMBERS_INFO_3.

Info

Contains the account name and domain name associated with a local group member.

Definition

typedef struct _LOCALGROUP_MEMBERS_INFO_3 {  LPWSTR lgrmi3_domainandname;

} LOCALGROUP_MEMBERS_INFO_3;

Members

lgrmi3_domainandname

Pointer to a null-terminated Unicode string specifying the account name of the local group member prefixed by the domain name and the "\" separator character.  For example:

<DomainName>\<AccountName>

Header file

<lm.h>

Remark

User account names are limited to 20 characters and group names are limited to 256 characters.  In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters:",/,\,[,],:,|,<,>,+,=,;,?,*.  Names also cannot include characters in the range 1-31, which are nonprintable.

 

Table 29

 

 

------------------------------User Accounts and Groups: Functions and structures--------------------------

 

 

Further reading and digging:

 

  1. Check the best selling C, C++ and Windows books at Amazon.com.

  2. Microsoft Visual C++, on-line MSDN.

  3. MSDN library.

  4. For Multi bytes, Unicode characters and Localization stories please refer toUnicode & Multi-byte 1 andUnicode & Multi byte 2.

  5. Structure, enum, union and typedef story can be foundinstruct, enum, typedef etc.

  6. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussedinC & C++ Notation.

  7. Windows data type information is inWindows Data Types.

 

 

 

 

 

 

 

 

| Main |Site Index |Download |Disclaimer |Privacy |