Net(3) User Contributed Perl Documentation Net(3)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
"user"s 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-controller" 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>"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 ALSOperl(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.
perl v5.14.2 2005-09-17 Net(3)
