net.pm

来自「ARM上的如果你对底层感兴趣」· PM 代码 · 共 1,799 行 · 第 1/4 页

package Win32API::Net;

use strict;
use Carp;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);

require Exporter;
require DynaLoader;

@ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw();	# don't pollute callees namespace

%EXPORT_TAGS=(
    User => [ qw(
        FILTER_INTERDOMAIN_TRUST_ACCOUNT FILTER_NORMAL_ACCOUNT
        FILTER_SERVER_TRUST_ACCOUNT FILTER_TEMP_DUPLICATE_ACCOUNTS
        FILTER_WORKSTATION_TRUST_ACCOUNT
        USER_ACCT_EXPIRES_PARMNUM USER_AUTH_FLAGS_PARMNUM
        USER_CODE_PAGE_PARMNUM USER_COMMENT_PARMNUM USER_COUNTRY_CODE_PARMNUM
        USER_FLAGS_PARMNUM USER_FULL_NAME_PARMNUM USER_HOME_DIR_DRIVE_PARMNUM
        USER_HOME_DIR_PARMNUM USER_LAST_LOGOFF_PARMNUM USER_LAST_LOGON_PARMNUM
        USER_LOGON_HOURS_PARMNUM USER_LOGON_SERVER_PARMNUM
        USER_MAX_STORAGE_PARMNUM USER_NAME_PARMNUM USER_NUM_LOGONS_PARMNUM
        USER_PAD_PW_COUNT_PARMNUM USER_PARMS_PARMNUM USER_PASSWORD_AGE_PARMNUM
        USER_PASSWORD_PARMNUM USER_PRIMARY_GROUP_PARMNUM USER_PRIV_ADMIN
        USER_PRIV_GUEST USER_PRIV_MASK USER_PRIV_PARMNUM USER_PRIV_USER
        USER_PROFILE_PARMNUM USER_PROFILE_PARMNUM USER_SCRIPT_PATH_PARMNUM
        USER_UNITS_PER_WEEK_PARMNUM USER_USR_COMMENT_PARMNUM
        USER_WORKSTATIONS_PARMNUM LG_INCLUDE_INDIRECT
        UF_ACCOUNTDISABLE UF_ACCOUNT_TYPE_MASK UF_DONT_EXPIRE_PASSWD
        UF_HOMEDIR_REQUIRED UF_INTERDOMAIN_TRUST_ACCOUNT UF_LOCKOUT
        UF_MACHINE_ACCOUNT_MASK UF_NORMAL_ACCOUNT UF_PASSWD_CANT_CHANGE
        UF_PASSWD_NOTREQD UF_SCRIPT UF_SERVER_TRUST_ACCOUNT UF_SETTABLE_BITS
        UF_TEMP_DUPLICATE_ACCOUNT UF_WORKSTATION_TRUST_ACCOUNT
        UserAdd UserChangePassword UserDel UserEnum UserGetGroups UserGetInfo 
        UserGetLocalGroups UserModalsGet UserModalsSet UserSetGroups
        UserSetInfo
    )],
    Get => [ qw(
        GetDCName
    )],
    Group => [ qw(
        GROUP_ATTRIBUTES_PARMNUM GROUP_COMMENT_PARMNUM GROUP_NAME_PARMNUM
        GroupAdd GroupAddUser GroupDel GroupDelUser GroupEnum GroupGetInfo 
        GroupGetUsers GroupSetInfo GroupSetUsers 
    )],
    LocalGroup => [ qw(
        LOCALGROUP_COMMENT_PARMNUM LOCALGROUP_NAME_PARMNUM
        LocalGroupAdd LocalGroupAddMember LocalGroupAddMembers LocalGroupDel 
        LocalGroupDelMember LocalGroupDelMembers LocalGroupEnum 
        LocalGroupGetInfo LocalGroupGetMembers LocalGroupSetInfo 
        LocalGroupSetMembers 
    )],
);

@EXPORT_OK= ();
{ my $ref;
    foreach $ref (  values(%EXPORT_TAGS)  ) {
        push( @EXPORT_OK, @$ref );
    }
}
$EXPORT_TAGS{ALL}= \@EXPORT_OK;

$VERSION = '0.04';

sub AUTOLOAD {
    my $constname;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	if ($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
		croak "Your vendor has not defined Win32API::Net macro $constname";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

bootstrap Win32API::Net $VERSION;

1;
__END__

=head1 NAME

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

=head1 SYNOPSIS

use Win32API::Net;

=head1 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
L<DATA STRUCTURES>.

The following groups of functions are available:

=over 8

=item L<NET USER FUNCTIONS>

=item L<NET GROUP FUNCTIONS>

=item L<NET LOCAL GROUP FUNCTIONS>

=item L<NET GET FUNCTIONS>

=back

All functions return 0 on failure and 1 on success. Use the
C<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. C<UserAdd()>) have a last argument that will
allow more detailed information on which key/value pair was not properly
specified.

=head2 Using References

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

=over 8

=item 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);

=item 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);

=back

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

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

=head1 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 C<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 C<0>, the function returns a structure that has only one field. For a
supplied level of 1, the function returns a structure with C<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 C<UserGetInfo()> can takes a number of levels. If called with level C<0>
the supplied hash will, on return from the function, contain a single key
and value - namely B<name>/B<requested-users-name>. If called with a level
of C<1> the supplied hash will, on return from the function, contain 8 keys
and values. The returned keys are C<name, password>, C<passwordAge>,
C<priv>, C<homeDir>, C<comment>, C<flags>, C<scriptPath>. See
L<USER INFO FIELDS> for more information on what these represent.


=head1 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.

=over 8

=item C<:User>

Exports all symbols needed for the C<User*()> functions.
See L<NET USER FUNCTIONS>.

=item C<:Get>

Exports all symbols needed for the C<Get*()> functions.
See L<NET GET FUNCTIONS>.

=item C<:Group>

Exports all symbols needed for the C<Group*()> functions.
See L<NET GROUP FUNCTIONS>.

=item C<:LocalGroup>

Exports all symbols needed for the C<LocalGroup*()> functions.
See L<NET LOCAL GROUP FUNCTIONS>.

=back


=head1 NET USER FUNCTIONS

The C<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 C<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 C<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 C<UserGetLocalGroups()> function actually lists the
domain's local groups of which the named user is a member.

The following functions are available.


=head2 UserAdd(server, level, hash, error)

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

=over 8

=item C<server> - Scalar String

The server on which to add the account.

=item C<level> - Scalar Int

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

=item C<hash> - Hash Reference

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

=item C<error> - Scalar Int

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

=back

=head2 UserChangePassword(server, user, old, new)

Changes the password for C<user>. If the policy of the machine/domain
only allows password changes if the C<user> is logged on then the C<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.

=over 8

=item C<server> - Scalar String

The C<server> on which to change the password.

=item C<user> - Scalar String

The name of the C<user> whose password is being changed.

=item C<old> - Scalar String

The existing password for C<user>.

=item C<new> - Scalar String

The new password for C<user>.

=back


=head2 UserDel(server, user)

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

=over 8

=item C<server> - Scalar String

The C<server> on which to delete the C<user>.

=item C<user> - Scalar String

The C<user> account to delete.

=back

=head2 UserEnum(server, array[, filter])

Enumerates all the accounts on server that satisfy C<filter>. Unlike the
C<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
L<Example 1>.

=over 8

=item C<server> - Scalar String

The C<server> on which to enumerate the accounts satisfying C<filter>.

=item C<array> - Array Reference

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

=item C<filter> - Scalar Int (optional)

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

=back

=head2 UserGetGroups(server, user, array)

Get the global groups for which C<user> is a member. It returns the group
names in C<array>. Unlike the C<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).

=over 8

=item C<server> - Scalar String

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

=item C<user> - Scalar String

The C<user> whose group membership you wish to examine.

=item C<array> - Scalar String

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

=back

=head2 UserGetInfo(server, user, level, hash)

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

=over 8

=item C<server> - Scalar String

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

=item C<user> - Scalar String

The C<user> whose information you want.

=item C<level> - Scalar Int

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

=item C<hash> - Hash Reference

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

=back

=head2 UserGetLocalGroups(server, user, array[, flags])

Gets the names of the local groups of which C<user> is a member. Unlike
the C<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...

=over 8

=item C<server> - Scalar String

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

=item C<user> - Scalar String

The C<user> whose local group membership you wish to enumerate.

=item C<array> - Array Reference

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

=item C<flags> - Scalar Int <em>(optional)</em>

Either C<Win32API::Net::LG_INCLUDE_INDIRECT()> or 0. if C<flags> is
omitted, the function internally uses 0. Specifying C<LG_INCLUDE_INDIRECT()>
will include in the list the names of the groups of which the C<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.

=back


=head2 UserModalsGet()