- NAME
- SYNOPSIS
- NOTE ON VERSIONS PRIOR TO 0.08
- DESCRIPTION
  - Using References
- DATA STRUCTURES
- Exports
- NET USER FUNCTIONS
  - UserAdd(server, level, hash, error)
  - UserChangePassword(server, user, old, new)
  - UserDel(server, user)
  - UserEnum(server, array[, filter])
  - UserGetGroups(server, user, array)
  - UserGetInfo(server, user, level, hash)
  - UserGetLocalGroups(server, user, array[, flags])
  - UserModalsGet()
  - UserModalsSet()
  - UserSetGroups(server, user, array)
  - UserSetInfo(server, user, level, hash, error)
- NET GROUP FUNCTIONS
  - GroupAdd(server, level, hash, error)
  - GroupAddUser(server, group, user)
  - GroupDel(server, group)
  - GroupDelUser(server, group, user)
  - GroupEnum(server, array)
  - GroupGetInfo(server, group, level, hash)
  - GroupGetUsers(server, group, array)
  - GroupSetInfo(server, group, level, hash, error)
  - GroupSetUsers(server, group, array)
- NET LOCAL GROUP FUNCTIONS
  - LocalGroupAdd(server, level, hash, error)
  - LocalGroupAddMember()
  - LocalGroupAddMembers(server, group, array)
  - LocalGroupDel(server, group)
  - LocalGroupDelMember()
  - LocalGroupDelMembers(server, group, array)
  - LocalGroupEnum(server, array)
  - LocalGroupGetInfo(server, group, level, hash)
  - LocalGroupGetMembers(server, group, hash)
  - LocalGroupSetInfo(server, level, hash, error)
  - LocalGroupSetMembers()
- NET GET FUNCTIONS
  - GetDCName(server, domain, domain-controller)
- USER INFO LEVELS
- USER INFO FIELDS
- USER FLAGS
- USER PRIVILEGE FLAGS
- USER ENUM FILTER
- USER FIELD ERRORS
- GROUP INFO LEVELS
- GROUP INFO FIELDS
- GROUP FIELD ERRORS
- GROUP USERS INFO LEVELS
- GROUP USERS INFO FIELDS
- LOCAL GROUP INFO LEVELS
- LOCAL GROUP INFO FIELDS
- LOCAL GROUP FIELD ERRORS
- EXAMPLES
- AUTHOR
- SEE ALSO
- ACKNOWEDGEMENTS

# NAME

Win32API::Net - Perl interface to the Windows NT LanManager API account management functions.

# SYNOPSIS

use Win32API::Net;

# NOTE ON VERSIONS PRIOR TO 0.08

As of version 0.08 of this module, the behaviour relating to empty strings in input hashes has changed. The old behaviour converted such strings to the NULL pointer. The underlying API uses this value as an indication to not change the value stored for a given field. This meant that you were not able to clear (say) the logonScript field for a user using `UserSetInfo().`

The new behaviour is to leave the string as an empty C string which will allow fields to be cleared. To pass a NULL pointer to the underlying API call (and thus, to leave the field as it was), you need to set the corresponding field to `undef`.

WARNING: THIS IS AN INCOMPATIBLE CHANGE. EXISTING SCRIPTS THAT RELIED ON PRIOR BEHAVIOR MAY NEED TO BE MODIFIED.

# DESCRIPTION

Win32API::Net provides a more complete wrapper for the account management parts of the NT LanManager API than do other similar packages. Most of what you can achieve with the native C++ API is possible with this package - albeit in a more Perl like manner by using references to pass information to and from functions.

For an understanding of the environment in which these functions operate see DATA STRUCTURES.

The following groups of functions are available:

NET USER FUNCTIONS
NET GROUP FUNCTIONS
NET LOCAL GROUP FUNCTIONS
NET GET FUNCTIONS

All functions return 0 on failure and 1 on success. Use the `Win32::GetLastError()` function to find out more information on why a function failed. In addition, some functions that take a hash reference to pass information in (e.g. `UserAdd()`) have a last argument that will allow more detailed information on which key/value pair was not properly specified.

## Using References

References to hashes and arrays are used throughout this package to pass information into and out of functions.

Using Hash References

  Where a hash reference is required you can use anything that evaluates to a hash reference. e.g.

              $href = \%someHash;
              UserAdd(server, 2, $hRef);

  Or more directly:

              UserAdd(server, 2, \%someHash);

Using Array references

  Array references are used in a similar manner to hash references. e.g.

              $aref = \@someArray;
              UserEnum(server, $aref);

  Or more directly:

              UserEnum(server, \@someArray);

Please note: Any `*Get*()` or `*Enum()` operation will first clear the contents of the input hash or array being referenced.

See EXAMPLES and the test.pl script for examples of usage.

# DATA STRUCTURES

Most the the functions in the underlying API allow the programmer to pass specify at runtime the amount of information that is supplied to the function. For example, the `NetUserGetInfo()` call allows the programmer to specify levels of 0, 1, 2, 3 (and others). Having specified this level, the function returns a structure that will contain different fields. For a level `0`, the function returns a structure that has only one field. For a supplied level of 1, the function returns a structure with `8` fields. The programmer needs to know in advance what fields should be provided or will be returned for a given level. This mechanism works very will since it effectively overloads functions without having to use different function prototypes. Perl provides better higher level data structures in the form of arrays and hashes. This package uses hashes as the means to pass these variable size structure into and out of functions.

For any function that takes a reference to a hash as input, the programmer is expected to provide appropriate keys and corresponding values as well as the level parameter. The called function will then takes the values out of the supplied hash and build the approprite structure to pass to the underlying API function.

For any function that takes a reference to a hash to recieve output, the function will first clear any keys an corresponding values in the supplied hash. It will call the underlying API call and will then return in the hash any keys and values that are applicable at the requested level.

Example:

The `UserGetInfo()` can takes a number of levels. If called with level `0` the supplied hash will, on return from the function, contain a single key and value - namely name/requested-users-name. If called with a level of `1` the supplied hash will, on return from the function, contain 8 keys and values. The returned keys are `name, password`, passwordAge, priv, homeDir, comment, flags, scriptPath. See USER INFO FIELDS for more information on what these represent.

# Exports

By default, Win32API::Net exports no symbols into the callers namespace. The following tags can be used to selectively import symbols into the main namespace.

:User

  Exports all symbols needed for the `User*()` functions. See NET USER FUNCTIONS.

:Get

  Exports all symbols needed for the `Get*()` functions. See NET GET FUNCTIONS.

:Group

  Exports all symbols needed for the `Group*()` functions. See NET GROUP FUNCTIONS.

:LocalGroup

  Exports all symbols needed for the `LocalGroup*()` functions. See NET LOCAL GROUP FUNCTIONS.

# NET USER FUNCTIONS

The `User*()` functions operate on NT user accounts.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled. Administrator privileges are required to add an Administrator Privilege account. There are some exceptions to this whereby a user can change some of their own settings where these don't conflict with 'administrative information' (e.g. full name).

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function `GetDCName()` to find out what the domain controller is, should you not be running this on the PDC.

All functions in this section are 'DOMAIN functions'. This means that, for example, the `UserGetLocalGroups()` function actually lists the domain's local groups of which the named user is a member.

The following functions are available.

## UserAdd(server, level, hash, error)

Add a new user account. The user name is taken from the name-key's value in the supplied hash.

server - Scalar String

  The server on which to add the account.

level - Scalar Int

  Level of information provided in hash. This can be either 1, 2 or 3. See USER INFO LEVELS.

hash - Hash Reference

  The information to use to add this account. This should have all the appropriate keys and values required for level.

error - Scalar Int

  Provides information on which field in the hash was not properly specified. See USER FIELD ERRORS for more information about what values this can take.

## UserChangePassword(server, user, old, new)

Changes the password for user. If the policy of the machine/domain only allows password changes if the user is logged on then the user must be logged on to execute this function. With Administrator or Account Operator privilege you can use this function to change anyone's password, so long as you know the old password.

server - Scalar String

  The server on which to change the password.

user - Scalar String

  The name of the user whose password is being changed.

old - Scalar String

  The existing password for user.

new - Scalar String

  The new password for user.

## UserDel(server, user)

Deletes the specified user account. Administrator or Account Operator privilege is required to execute this function.

server - Scalar String

  The server on which to delete the user.

user - Scalar String

  The user account to delete.

## UserEnum(server, array[, filter])

Enumerates all the accounts on server that satisfy filter. Unlike the `NetUserEnum()` function in the API, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it) - see Example 1.

server - Scalar String

  The server on which to enumerate the accounts satisfying filter.

array - Array Reference

  The array that will hold the names of all users on server whose accounts match filter.

filter - Scalar Int (optional)

  The filter to apply (see USER ENUM FILTER). This argument is optional and if not present a default of FILTER_NORMAL_ACCOUNT is used.

## UserGetGroups(server, user, array)

Get the global groups for which user is a member. It returns the group names in array. Unlike the `NetUserGetGroups()` function in the API, this function does not allow you to specify a level (internally is hardcoded to 0). In Perl it is trivial to implement the equivalent function (in the unlikely event that you might need it).

server - Scalar String

  The server from which to get the groups of which user is a member.

user - Scalar String

  The user whose group membership you wish to examine.

array - Scalar String

  The array that will contain the group names to which user belongs.

## UserGetInfo(server, user, level, hash)

Returns the information at the specified level for the named user in hash.

server - Scalar String

  The server from which to get the requested information about user.

user - Scalar String

  The user whose information you want.

level - Scalar Int

  One of: 0, 1, 2, 3, 10, 11 and 20. See USER INFO LEVELS.

hash - Hash Reference

  The hash that will contain the keys and values for the information requested. See USER INFO FIELDS for information about which keys are present in a given level.

## UserGetLocalGroups(server, user, array[, flags])

Gets the names of the local groups of which user is a member. Unlike the `NetUserEnum()` function in the API, this function does not allow you to specify a level. Since the underlying API restricts you to level 0 there really isn't any need to include it...

server - Scalar String

  The server from which to get the local groups of which user is a member.

user - Scalar String

  The user whose local group membership you wish to enumerate.

array - Array Reference

  The array that will hold the names of the local groups to which user belongs.

flags - Scalar Int <em>(optional)</em>

  Either `Win32API::Net::LG_INCLUDE_INDIRECT()` or 0. if flags is omitted, the function internally uses 0. Specifying `LG_INCLUDE_INDIRECT()` will include in the list the names of the groups of which the user is indirectly a member (e.g. by being in a global group that is a member of a local group).

  This field can take no other values.

## UserModalsGet()

This function is not currently implemented.

## UserModalsSet()

This function is not currently implemented.

## UserSetGroups(server, user, array)

Sets the (global) group membership for user to the specified groups. Unlike the API function `NetUserSetGroups()`, this function does not take a level parameter (mainly because this option is largely redundant).

server - Scalar String

  The server on which you wish to set the group membership for user.

user - Scalar String

  The user whose group membership you wish to set.

array - Array Reference

  The array containing the (global) group names to set the users membership of.

This function will fail if any of the group names specified do not exist.

## UserSetInfo(server, user, level, hash, error)

Sets the info for user according to the information contained in hash for level (see USER INFO LEVELS).

server - Scalar String

  The server on which you wish to change the info for user.

user - Scalar String

  The user whose info you wish to change.

level - Scalar Int

  One of 0, 1, 2, 3, or 20 (according to Microsoft documentation). In practice, you can use all the 10xx levels as well to change most of the individual properties of the named user - although this may not be supported in future...

hash - Hash Reference

  The hash that will contain the necessary key/value pairs required for level (see USER INFO LEVELS).

error - Scalar Int

  Provides information on which field in hash were not properly specified. See USER FIELD ERRORS for more information about what values can be returned in this field.

# NET GROUP FUNCTIONS

The `Group*()` functions all operate only on global groups. To modify local groups, use the corresponding `LocalGroup*()` functions.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled.

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function `GetDCName()` to find out what the domain controller is, should you not be running this on the PDC.

The following functions are available.

## GroupAdd(server, level, hash, error)

Adds the specified group.

server - Scalar String

  The server on which to add the group.

level - Scalar String

  The level of information contained in hash. This can be one of 0, 1 or 2. See GROUP INFO LEVELS.

hash - Hash Reference

  A hash containing the required key/value pairs for level.

error - Scalar Int

  Provides information on which field in hash was not properly specified. See GROUP FIELD ERRORS for more information about what values can be returned in this field.

## GroupAddUser(server, group, user)

Adds the specified user to the specified group.

server - Scalar String

  The server on which to add the user to group.

group - Scalar String

  The group to add the user to.

user - Scalar String

  The user to add to group.

## GroupDel(server, group)

Deletes the specified global group.

server - Scalar String

  The server on which to delete the named group.

group -Scalar String

  The group to delete.

## GroupDelUser(server, group, user)

Deletes the specified user from the specified group.

server - Scalar String

  The server on which to delete user from group.

group - Scalar String

  The group from which to delete user.

user - Scalar String

  The user to delete from group.

## GroupEnum(server, array)

Enumerates all the global groups on the server. Unlike the API call `NetGroupEnum()`, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

  The server on which to enumerate the (global) `groups`.

array - Array Reference

  An array that, on return, will contain the group names.

## GroupGetInfo(server, group, level, hash)

Retrieves level information for group returning information in hash.

server - Scalar String

  The server from which to get the group information.

group - Scalar String

  The group whose information you wish to obtain.

level - Scalar Int

  The level of information you wish to retrieve. This can be one of 1, 2 or 3. See GROUP INFO LEVELS.

hash - Hash Reference

  The hash that will contain the information.

## GroupGetUsers(server, group, array)

Returns (in array) the users belonging to group. Unlike the API call `NetGroupGetUsers()`, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

  The server from which to get the group information.

group - Scalar String

  The group whose users you wish to obtain.

array - Array Reference

  The array to hold the user names retrieved.

## GroupSetInfo(server, group, level, hash, error)

Sets the information for group according to level.

server - Scalar String

  The server on which to set the group information.

group - Scalar String

  The group whose information you wish to set.

level - Scalar Int

  The level of information you are supplying in hash. Level can be one of 0, 1 or 2. See GROUP INFO LEVELS.

hash - Hash Reference

  The hash containing the required key/value pairs for level.

error - Scalar String

  On failure, the error parameter will contain a value which specifies which field caused the error. See GROUP FIELD ERRORS.

## GroupSetUsers(server, group, array)

Sets the membership of group to contain only those users specified in array. This function will fail if any user names contained in the array are not valid users on server. On successful completion group will contain only the users specified in array. Use the functions `GroupAddUser()/GroupDelUser()` to add and delete individual users from a group.

server - Scalar String

  The server on which to set the group membership.

group - Scalar String

  The group to set the membership of.

array - Array Reference

  The array containing the names of all users who will be members of group.

# NET LOCAL GROUP FUNCTIONS

The `LocalGroup*()` functions operate on local groups. If these functions are run on a PDC then these functions operate on the domains local groups.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled.

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function `GetDCName()` to find out what the domain controller is, should you not be running this on the PDC.

The following functions are available.

## LocalGroupAdd(server, level, hash, error)

Adds the specified group. The name of the group is contained in the name key of hash.

server - Scalar String

  The server on which to add the group.

level - Scalar String

  The level of information contained in hash. This can be one of 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

  A hash containing the required key/value pairs for level.

error - Scalar Int

  Provides information on which field in hash wasn't properly specified. See LOCAL GROUP FIELD ERRORS for more information about what values this can take.

## LocalGroupAddMember()

This function is obselete in the underlying API and has therefore not been implemented. Use `LocalGroupAddMembers` instead.

## LocalGroupAddMembers(server, group, array)

Adds the specified users (members) to the local group. Unlike the API function `NetLocalGroupAddMembers()`, this function does not allow you to specify a level (internally it is hardcoded to 3). This was done to simplify the implementation. To add a 'local' user, you need only specify the name. You can also specify users using the `DOMAIN\user` syntax.

server - Scalar String

  The server on which to add the members to group.

group - Scalar String

  The group to add the members to.

array - Array Reference

  The array containing the members to add to group.

## LocalGroupDel(server, group)

Delete the specified local group.

server - Scalar String

  The server on which to delete the named group.

group -Scalar String

  The group to delete.

## LocalGroupDelMember()

This function is obselete in the underlying API and has therefore not been implemented. Use `LocalGroupDelMembers()` instead.

## LocalGroupDelMembers(server, group, array)

Delete the specified users (members) of the local group. Unlike the API function `NetLocalGroupDelMembers()`, this function does not allow you to specify a level (internally it is hardcoded to 3). This was done to simplify the implementation. To delete a 'local' user, you need only specify the name. You can also specify users using the `DOMAIN\user` syntax.

server - Scalar String

  The server on which to delete the members from group.

group - Scalar String

  The group to delete the members from.

array - Array Reference

  The array containing the members to delete from group.

## LocalGroupEnum(server, array)

Enumerates all the local groups on the server. Unlike the API call `NetLocalGroupEnum()`, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

  The server on which to enumerate the (local) `groups`.

array - Array Reference

  The array to hold the group names.

## LocalGroupGetInfo(server, group, level, hash)

Retrieves level information for group.

server - Scalar String

  The server from which to get the group information.

group - Scalar String

  The group whose information you wish to obtain.

level - Scalar Int

  The level of information you wish to retrieve. This can be 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

  The hash that will contain the information.

## LocalGroupGetMembers(server, group, hash)

Retrieves the users belonging to group. Unlike the API call `NetLocalGroupGetUsers()`, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

  The server from which to retrieve the group information.

group - Scalar String

  The group whose users you wish to obtain.

array - Array Reference

  The array to hold the user names retrieved.

## LocalGroupSetInfo(server, level, hash, error)

Sets the information for group according to level.

server - Scalar String

  The server on which to set the group information.

group - Scalar String

  The group whose information you wish to set.

level - Scalar Int

  The level of information you are supplying in hash. Level can be one of 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

  The hash containing the required key/value pairs for level.

error - Scalar String

  On failure, the error parameter will contain a value which specifies which field caused the error. See LOCAL GROUP FIELD ERRORS.

## LocalGroupSetMembers()

This function has not been implemented at present.

# NET GET FUNCTIONS

## GetDCName(server, domain, domain-controller)

Gets the `domain-controllder` name for server and domain.

server - Scalar String

  The server whose domain controller you wish to locate.

domain - Scalar String

  The domain that server is a member of whose domain-controller you wish the locate.

domain-controller - Scalar String (output)

  The name of the `domain-controller` for the requested domain.

Note: This module does not implement the `NetGetAnyDCName()`API function as this is obsolete.

# USER INFO LEVELS

Most of the `User*()` functions take a level parameter. This level specifies how much detail the corresponding hash should contain (or in the case of a `UserGet*()` function, will contain after the call). The following level descriptions provide information on what fields should be present for a given level. See USER INFO FIELDS for a description of the fields.

Level 0

  name

Level 1

  name, password, passwordAge, priv, homeDir, comment, flags, scriptPath

Level 2

  name, password, passwordAge, priv, homeDir, comment, flags, scriptPath, authFlags, fullName, usrComment, parms, workstations, lastLogon, lastLogoff, acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount, numLogons, logonServer, countryCode, codePage

Level 3

  name, password, passwordAge, priv, homeDir, comment, flags, scriptPath, authFlags, fullName, usrComment, parms, workstations, lastLogon, lastLogoff, acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount, numLogons, logonServer, countryCode, codePage, userId, primaryGroupId, profile, homeDirDrive, passwordExpired

Level 10

  name, comment, usrComment, fullName

Level 11

  name, comment, usrComment, fullName, priv, authFlags, passwordAge, homeDir, parms, lastLogon, lastLogoff, badPwCount, numLogons, logonServer, countryCode, workstations, maxStorage, unitsPerWeek, logonHours, codePage

Level 20

  name, fullName, comment, flags, userId

Level 21

  Not available in this implementation

Level 22

  Not available in this implementation

Level 1003

  password

Level 1005

  priv

Level 1006

  homeDir

Level 1007

  comment

Level 1008

  flags

Level 1009

  scriptPath

Level 1010

  authFlags

Level 1011

  fullName

Level 1012

  usrComment

Level 1013

  parms

Level 1014

  workstations

Level 1017

  acctExpires

Level 1018

  maxStorage

Level 1020

  unitsPerWeek, logonHours

Level 1023

  logonServer

Level 1024

  countryCode

Level 1025

  codePage

Level 1051

  primaryGroupId

Level 1052

  profile

Level 1053

  homeDirDrive

# USER INFO FIELDS

The following is an alphabetical listing of each possible field, together with the data type that the field is expected to contain.

acctExpires - Scalar Int (UTC)

  The time (as the number of seconds since 00:00:00, 1st January 1970) when the account expires. A -1 in this field specifies that the account never expires.

authFlags - Scalar Int (See USER_AUTH_FLAGS).

  The level of authority that this use has. The value this can take depends on the users group membership - this value is therefore read only and cannot be set using `UserAdd()` or `UserSetInfo()`. Its value can be one of:

            User belongs to group           Flag value
            ---------------------           ----------
            Print Operators                 Win32API::Net::AF_OP_PRINT()
            Server Operators                Win32API::Net::AF_OP_SERVER()
            Account Operators               Win32API::Net::AF_OP_ACCOUNTS()

badPwCount - Scalar Int

  The number of times that the user has failed to logon by specifying an incorrect password.

codePage - Scalar Int

  The code page that this user uses.

comment - Scalar String

  The comment associated with this user account. This can be any string (apparently of any length).

countryCode - Scalar Int

  The country code that this user uses.

flags - Scalar Int (Bitwise OR of USER_FLAGS)

  The flags for this user. See USER FLAGS.

fullName - Scalar String

  The users' full name.

homeDir - Scalar String

  The home directory of the user. This can be either a UNC path or an absolute path (drive letter + path). Can be the empty string (``'').

homeDirDrive - Scalar String

  The home directory drive that the users home directory is mapped to (assuming that the specified home directory is a UNC path).

lastLogon - Scalar Int (UTC)

  The time (as the number of seconds since 00:00:00, 1st January 1970) that the user last logged on.

lastLogoff - Scalar Int (UTC)

  The time (as the number of seconds since 00:00:00, 1st January 1970) that the user last logged off .

logonHours - Reference to Array of Integers (length 21 elements)

  The times at which the user can logon. This should be an integer array with 21 elements. Each element represents an 8 hour period and each bit represents represents an hour. Only the lower byte of each integer is used. If this is left undefined then no restrictions are placed on the account.

logonServer - Scalar String

  The logon server for this user. Under Windows NT, this value cannot be set and will always have the value '\\*' when queried.

maxStorage - Scalar Int

  The current release of Windows NT does not implement disk quotas so it is believed that the value of this key is ignored.

name - Scalar String

  The user name that this request applies to. Most of the functions take the user name as a separate argument. In general, the user name provided should be the same as that in the one provided in the hash.

numLogons - Scalar Int

  The number of times that the named user has successfully logged on to this machine/domain.

parms - Scalar String

  The value of this key can be used by applications. There are none known to to author that use it, although it could be used to hold adminitrative information.

password - Scalar String

  The password to be set. The password is never returned in a `UserGet()` operation.

passwordAge - Scalar Int (UTC)

  The current age of the password (stored as the number of seconds since 00:00:00, 1st January 1970).

passwordExpired - Scalar Int

  The value of this key is used in two different ways. When queried via `UserGetInfo()` the return value is 0 is the password has not expired and 1 if it has. When setting the value via `UserAdd()` or `UserSetInfo()` a value of 0 indicates that the users' password has not expired whereas a value of 1 will force the user to change their password at the next logon.

primaryGroupId - Scalar Int

  The id of the primary group that this user belongs to. When creating accounts with `UserAdd()` you should use a value of 0x201.

priv - Scalar Int (Bitwise OR of USER_PRIVILEGE_FLAGS)

  The privilege level that this user has. This is never returned from a `UserGet()` call. See USER PRIVILEGE FLAGS.

profile - Scalar String

  The profile that is associated with the named user. This can be UNC path, a local path or undefined.

scriptPath - Scalar String

  The path to the logon script for this user. This should be specified as a relative path and will cause the logon script to be run from (relative location) in the logon servers export directory.

unitsPerWeek - Scalar Int

  The value of this key represents the granularity of the logonHours array. Its use is beyond the scope of this package.

usrComment - Scalar String

  The user comment field (contrasted with the comment field ;-).

workstations - Scalar String

  A comma-separated string containing upto 8 workstation that the named user can login to. Setting a value for this key will then allow the named user to login to only those computers named.

userId - Scalar Int

  The user id associated with this user This value is generated by the system and cannot be set or changed using the `UserAdd()` or `UserSetInfo()` calls.

# USER FLAGS

The following is an alphabetical listing of the user flags. The flags key (see USER INFO FIELDS) should be the bitwise OR of one or more of these values.

UF_ACCOUNTDISABLE()

  This account has been disabled.

UF_DONT_EXPIRE_PASSWD()

  Never expire the password on this account.

UF_HOMEDIR_REQUIRED()

  A home directory must be specified (ignored for NT).

UF_INTERDOMAIN_TRUST_ACCOUNT()

  The account represents a interdomain trust account.

UF_LOCKOUT()

  Lock out this account (or this account has been locked out due to security policy - i.e. badLogonCount is greater than your policy allows). This value can be cleared but not set by a `UserSetInfo()` call.

UF_NORMAL_ACCOUNT()

  The account is a normal user account.

UF_PASSWD_CANT_CHANGE()

  The password for this account cannot be changed (execpt by an Administrator using one of the above calls).

UF_PASSWD_NOTREQD()

  A password is not required for this account.

UF_SCRIPT()

  This <strong>must be set when creating account on Windows NT.

UF_SERVER_TRUST_ACCOUNT()

  The account represents a Windows NT Backup Domain Controller account in the domain.

UF_TEMP_DUPLICATE_ACCOUNT()

  To quote the Microsoft Documentation <em>&quot;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()

  The account represents a computer account for a workstation or server in the domain.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

            $ufScript = Win32API::Net::UF_SCRIPT();

# USER PRIVILEGE FLAGS

These following values are used in the priv key. This field is never initialised on a `UserGet*()` call and once set cannot be changed in a `UserSetInfo()` call.

USER_PRIV_ADMIN()

  Account is an an administrative account.

USER_PRIV_GUEST()

  Account is a guest account.

USER_PRIV_USER()

  Account is a user account.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

            $userPrivUser = Win32API::Net::USER_PRIV_USER();

# USER ENUM FILTER

These flags are used in the `UserEnum()` function to specify which accounts to retrieve. It should be a bitwise OR of some (or all) of the following.

FILTER_TEMP_DUPLICATE_ACCOUNT()

  Show temporary duplicate account (one presumes).

FILTER_NORMAL_ACCOUNT()

  Show normal user account.

FILTER_INTERDOMAIN_TRUST_ACCOUNT()

  Show interdomain trust accounts.

FILTER_WORKSTATION_TRUST_ACCOUNT()

  Show workstation trust accounts.

FILTER_SERVER_TRUST_ACCOUNT()

  Show server trust accounts.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

            $filterNormalAccounts = Win32API::Net::FILTER_NORMAL_ACCOUNT();

# USER FIELD ERRORS

For the `User*()` functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing from the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful in debugging.

USER_ACCT_EXPIRES_PARMNUM()

  acctExpires field was absent or not correctly specified.

USER_AUTH_FLAGS_PARMNUM()

  authFlags field was absent or not correctly specified.

USER_BAD_PW_COUNT_PARMNUM()

  `badPasswordCount` field was absent or not correctly specified.

USER_CODE_PAGE_PARMNUM()

  codePage field was absent or not correctly specified.

USER_COMMENT_PARMNUM()

  comment field was absent or not correctly specified.

USER_COUNTRY_CODE_PARMNUM()

  countryCode field was absent or not correctly specified.

USER_FLAGS_PARMNUM()

  flags field was absent or not correctly specified.

USER_FULL_NAME_PARMNUM()

  fullName field was absent or not correctly specified.

USER_HOME_DIR_DRIVE_PARMNUM()

  homeDirDrive field was absent or not correctly specified.

USER_HOME_DIR_PARMNUM()

  homeDir field was absent or not correctly specified.

USER_LAST_LOGOFF_PARMNUM()

  lastLogoff field was absent or not correctly specified.

USER_LAST_LOGON_PARMNUM()

  lastLogon field was absent or not correctly specified.

USER_LOGON_HOURS_PARMNUM()

  logonHours field was absent or not correctly specified.

USER_LOGON_SERVER_PARMNUM()

  logonServer field was absent or not correctly specified.

USER_MAX_STORAGE_PARMNUM()

  maxStorage field was absent or not correctly specified.

USER_NAME_PARMNUM()

  name field was absent or not correctly specified.

USER_NUM_LOGONS_PARMNUM()

  numLogons field was absent or not correctly specified.

USER_PARMS_PARMNUM()

  parms field was absent or not correctly specified.

USER_PASSWORD_AGE_PARMNUM()

  passwordAge field was absent or not correctly specified.

USER_PASSWORD_PARMNUM()

  password field was absent or not correctly specified.

USER_PRIMARY_GROUP_PARMNUM()

  `primaryGroup` field was absent or not correctly specified.

USER_PRIV_PARMNUM()

  priv field was absent or not correctly specified.

USER_PROFILE_PARMNUM()

  profile field was absent or not correctly specified.

USER_SCRIPT_PATH_PARMNUM()

  scriptPath field was absent or not correctly specified.

USER_UNITS_PER_WEEK_PARMNUM()

  `unitPerWeek` field was absent or not correctly specified.

USER_USR_COMMENT_PARMNUM()

  usrComment field was absent or not correctly specified.

USER_WORKSTATIONS_PARMNUM()

  workstations field was absent or not correctly specified.

# GROUP INFO LEVELS

Some of the `Group*()` functions take a level parameter. This level specifies how much detail the corresponding hash should contain (or in the case of a `GroupGetInfo()` function, will contain after the call). The following level descriptions provide information on what fields should be present for a given level. See GROUP INFO FIELDS for a description of the fields.

Level 0

  name.

Level 1

  name, comment.

Level 2

  name, comment, groupId, attributes.

Level 1002

  comment.

Level 1005

  attributes.

# GROUP INFO FIELDS

attributes - Scalar Int

  The attributes of the group. These are no longer settable in Windows NT 4.0 and they are not currently supported in this package either.

comment - Scalar String

  The comment that applies to this group. This is the only value that can be set via a GroupSetInfo call.

groupId - Scalar Int

  The groups Id.

name - Scalar String

  The groups name.

# GROUP FIELD ERRORS

For the `Group*()` functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing from the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful for debugging purposes.

GROUP_ATTRIBUTES_PARMNUM()

  attributes field was absent or not correctly specified.

GROUP_COMMENT_PARMNUM()

  comment field was absent or not correctly specified.

GROUP_NAME_PARMNUM()

  name field was absent or not correctly specified.

# GROUP USERS INFO LEVELS

The `GroupGetUsers()` function can take a level of 0 or 1. These will return the following:

Level 0

  name.

Level 1

  name, attributes.

# GROUP USERS INFO FIELDS

name - Scalar String

  The user's name.

attributes - Scalar Int

  The attributes of the group. These are no longer settable in Windows NT 4.0 and they are not currently supported in this package either.

# LOCAL GROUP INFO LEVELS

Level 0

  name

Level 1

  name, comment

Level 1002

  comment

# LOCAL GROUP INFO FIELDS

name - Scalar String

  The groups name

comment - Scalar String

  The groups 'comment'

# LOCAL GROUP FIELD ERRORS

For the `LocalGroup*()` functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing or incorrectly specified in the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful for debugging purposes.

LOCALGROUP_NAME_PARMNUM()

  The name field was absent or not correctly specified.

LOCALGROUP_COMMENT_PARMNUM()

  The comment field wasabsent or not correctly specified.

# EXAMPLES

The following example shows how you can create a function in Perl that has the same functionality as the `NetUserEnum()` API call. The Perl version doesn't have the level parameter so you must first use the `UserEnum()` function to retrieve all the account names and then iterate through the returned array issuing `UserGetInfo()` calls.

        sub userEnumAtLevel {
           my($server, $level, $filter) = @_;
           my(@array);
           Win32API::Net::UserEnum($server, \@array, $filter);
           for $user (@array) {
              Win32API::Net::UserGetInfo($server, $user, $level, \%hash);
              print "This could access all level $level settings for $user - eg fullName $hash{fullName}\n";
           }
        }
        userEnumAtLevel("", 2, 0);

# AUTHOR

Bret Giddings, <bret@essex.ac.uk>

# SEE ALSO

`perl(1)`

# ACKNOWEDGEMENTS

This work was built upon work done by HiP Communications along with modifications to HiPs code by <michael@ecel.uwa.edu.au> and <rothd@roth.net> In addition, I would like to thank Jenny Emby at GEC Marconi, U.K. for proof reading this manual page and making many suggestions that have led to its current layout. Last but not least I would like to thank Larry Wall and all the other Perl contributors for making this truly wonderful language.