home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _bafcf3a6433c32ec8797dae9ee946cfa < prev    next >
Text File  |  2000-03-15  |  48KB  |  1,815 lines

  1. package Win32API::Net;
  2.  
  3. use strict;
  4. use Carp;
  5. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);
  6.  
  7. require Exporter;
  8. require DynaLoader;
  9.  
  10. @ISA = qw(Exporter DynaLoader);
  11. # Items to export into callers namespace by default. Note: do not export
  12. # names by default without a very good reason. Use EXPORT_OK instead.
  13. # Do not simply export all your public functions/methods/constants.
  14. @EXPORT = qw();    # don't pollute callees namespace
  15.  
  16. %EXPORT_TAGS=(
  17.     User => [ qw(
  18.         FILTER_INTERDOMAIN_TRUST_ACCOUNT FILTER_NORMAL_ACCOUNT
  19.         FILTER_SERVER_TRUST_ACCOUNT FILTER_TEMP_DUPLICATE_ACCOUNTS
  20.         FILTER_WORKSTATION_TRUST_ACCOUNT
  21.         USER_ACCT_EXPIRES_PARMNUM USER_AUTH_FLAGS_PARMNUM
  22.         USER_CODE_PAGE_PARMNUM USER_COMMENT_PARMNUM USER_COUNTRY_CODE_PARMNUM
  23.         USER_FLAGS_PARMNUM USER_FULL_NAME_PARMNUM USER_HOME_DIR_DRIVE_PARMNUM
  24.         USER_HOME_DIR_PARMNUM USER_LAST_LOGOFF_PARMNUM USER_LAST_LOGON_PARMNUM
  25.         USER_LOGON_HOURS_PARMNUM USER_LOGON_SERVER_PARMNUM
  26.         USER_MAX_STORAGE_PARMNUM USER_NAME_PARMNUM USER_NUM_LOGONS_PARMNUM
  27.         USER_PAD_PW_COUNT_PARMNUM USER_PARMS_PARMNUM USER_PASSWORD_AGE_PARMNUM
  28.         USER_PASSWORD_PARMNUM USER_PRIMARY_GROUP_PARMNUM USER_PRIV_ADMIN
  29.         USER_PRIV_GUEST USER_PRIV_MASK USER_PRIV_PARMNUM USER_PRIV_USER
  30.         USER_PROFILE_PARMNUM USER_PROFILE_PARMNUM USER_SCRIPT_PATH_PARMNUM
  31.         USER_UNITS_PER_WEEK_PARMNUM USER_USR_COMMENT_PARMNUM
  32.         USER_WORKSTATIONS_PARMNUM USER_BAD_PW_COUNT_PARMNUM LG_INCLUDE_INDIRECT
  33.         UF_ACCOUNTDISABLE UF_ACCOUNT_TYPE_MASK UF_DONT_EXPIRE_PASSWD
  34.         UF_HOMEDIR_REQUIRED UF_INTERDOMAIN_TRUST_ACCOUNT UF_LOCKOUT
  35.         UF_MACHINE_ACCOUNT_MASK UF_NORMAL_ACCOUNT UF_PASSWD_CANT_CHANGE
  36.         UF_PASSWD_NOTREQD UF_SCRIPT UF_SERVER_TRUST_ACCOUNT UF_SETTABLE_BITS
  37.         UF_TEMP_DUPLICATE_ACCOUNT UF_WORKSTATION_TRUST_ACCOUNT
  38.         UserAdd UserChangePassword UserDel UserEnum UserGetGroups UserGetInfo 
  39.         UserGetLocalGroups UserModalsGet UserModalsSet UserSetGroups
  40.         UserSetInfo
  41.     )],
  42.     Get => [ qw(
  43.         GetDCName
  44.     )],
  45.     Group => [ qw(
  46.         GROUP_ATTRIBUTES_PARMNUM GROUP_COMMENT_PARMNUM GROUP_NAME_PARMNUM
  47.         GroupAdd GroupAddUser GroupDel GroupDelUser GroupEnum GroupGetInfo 
  48.         GroupGetUsers GroupSetInfo GroupSetUsers 
  49.     )],
  50.     LocalGroup => [ qw(
  51.         LOCALGROUP_COMMENT_PARMNUM LOCALGROUP_NAME_PARMNUM
  52.         LocalGroupAdd LocalGroupAddMember LocalGroupAddMembers LocalGroupDel 
  53.         LocalGroupDelMember LocalGroupDelMembers LocalGroupEnum 
  54.         LocalGroupGetInfo LocalGroupGetMembers LocalGroupSetInfo 
  55.         LocalGroupSetMembers 
  56.     )],
  57. );
  58.  
  59. @EXPORT_OK= ();
  60. { my $ref;
  61.     foreach $ref (  values(%EXPORT_TAGS)  ) {
  62.         push( @EXPORT_OK, @$ref );
  63.     }
  64. }
  65. $EXPORT_TAGS{ALL}= \@EXPORT_OK;
  66.  
  67. $VERSION = '0.08';
  68.  
  69. sub AUTOLOAD {
  70.     my $constname;
  71.     ($constname = $AUTOLOAD) =~ s/.*:://;
  72.     my $val = constant($constname, @_ ? $_[0] : 0);
  73.     if ($! != 0) {
  74.     if ($! =~ /Invalid/) {
  75.         $AutoLoader::AUTOLOAD = $AUTOLOAD;
  76.         goto &AutoLoader::AUTOLOAD;
  77.     }
  78.     else {
  79.         croak "Your vendor has not defined Win32API::Net macro $constname";
  80.     }
  81.     }
  82.     eval "sub $AUTOLOAD { $val }";
  83.     goto &$AUTOLOAD;
  84. }
  85.  
  86. bootstrap Win32API::Net $VERSION;
  87.  
  88. 1;
  89. __END__
  90.  
  91. =head1 NAME
  92.  
  93. Win32API::Net - Perl interface to the Windows NT LanManager API account management functions.
  94.  
  95. =head1 SYNOPSIS
  96.  
  97. use Win32API::Net;
  98.  
  99. =head1 NOTE ON VERSIONS PRIOR TO 0.08
  100.  
  101. As of version 0.08 of this module, the behaviour relating to empty strings
  102. in input hashes has changed. The old behaviour converted such strings to
  103. the NULL pointer. The underlying API uses this value as an indication to
  104. not change the value stored for a given field. This meant that you were not
  105. able to clear (say) the logonScript field for a user using UserSetInfo().
  106.  
  107. The new behaviour is to leave the string as an empty C string which will
  108. allow fields to be cleared.  To pass a NULL pointer to the underlying
  109. API call (and thus, to leave the field as it was), you need to set the
  110. corresponding field to C<undef>.
  111.  
  112. WARNING: B<THIS IS AN INCOMPATIBLE CHANGE>.
  113. B<EXISTING SCRIPTS THAT RELIED ON PRIOR BEHAVIOR MAY NEED TO BE MODIFIED>.
  114.  
  115. =head1 DESCRIPTION
  116.  
  117. Win32API::Net provides a more complete wrapper for the account management
  118. parts of the NT LanManager API than do other similar packages. Most of what
  119. you can achieve with the native C++ API is possible with this package - albeit
  120. in a more Perl like manner by using references to pass information to and
  121. from functions.
  122.  
  123. For an understanding of the environment in which these functions operate see
  124. L<DATA STRUCTURES>.
  125.  
  126. The following groups of functions are available:
  127.  
  128. =over 8
  129.  
  130. =item L<NET USER FUNCTIONS>
  131.  
  132. =item L<NET GROUP FUNCTIONS>
  133.  
  134. =item L<NET LOCAL GROUP FUNCTIONS>
  135.  
  136. =item L<NET GET FUNCTIONS>
  137.  
  138. =back
  139.  
  140. All functions return 0 on failure and 1 on success. Use the
  141. C<Win32::GetLastError()> function to find out more information on why a
  142. function failed. In addition, some functions that take a hash reference
  143. to pass information in (e.g. C<UserAdd()>) have a last argument that will
  144. allow more detailed information on which key/value pair was not properly
  145. specified.
  146.  
  147. =head2 Using References
  148.  
  149. References to hashes and arrays are used throughout this package to pass
  150. information into and out of functions.
  151.  
  152. =over 8
  153.  
  154. =item Using Hash References
  155.  
  156. Where a hash reference is required you can use anything that evaluates to a
  157. hash reference. e.g.
  158.  
  159.     $href = \%someHash;
  160.     UserAdd(server, 2, $hRef);
  161.  
  162. Or more directly:
  163.  
  164.     UserAdd(server, 2, \%someHash);
  165.  
  166. =item Using Array references
  167.  
  168. Array references are used in a similar manner to hash references. e.g.
  169.  
  170.     $aref = \@someArray;
  171.     UserEnum(server, $aref);
  172.  
  173. Or more directly:
  174.  
  175.     UserEnum(server, \@someArray);
  176.  
  177. =back
  178.  
  179. Please note: Any C<*Get*()> or C<*Enum()> operation will first clear the
  180. contents of the input hash or array being referenced.
  181.  
  182. See L<EXAMPLES> and the test.pl script for examples of usage.
  183.  
  184. =head1 DATA STRUCTURES
  185.  
  186. Most the the functions in the underlying API allow the programmer to pass
  187. specify at runtime the amount of information that is supplied to the
  188. function. For example, the C<NetUserGetInfo()> call allows the programmer to
  189. specify levels of 0, 1, 2, 3 (and others). Having specified this level, the
  190. function returns a structure that will contain different fields. For a
  191. level C<0>, the function returns a structure that has only one field. For a
  192. supplied level of 1, the function returns a structure with C<8> fields. The
  193. programmer needs to know in advance what fields should be provided or will
  194. be returned for a given level. This mechanism works very will since it
  195. effectively overloads functions without having to use different function
  196. prototypes. Perl provides better higher level data structures in the form
  197. of arrays and hashes. This package uses hashes as the means to pass these
  198. variable size structure into and out of functions.
  199.  
  200. For any function that takes a reference to a hash as input, the programmer
  201. is expected to provide appropriate keys and corresponding values as well as
  202. the level parameter. The called function will then takes the values out of
  203. the supplied hash and build the approprite structure to pass to the
  204. underlying API function.
  205.  
  206. For any function that takes a reference to a hash to recieve output, the
  207. function will first clear any keys an corresponding values in the supplied
  208. hash. It will call the underlying API call and will then return in the hash
  209. any keys and values that are applicable at the requested level.
  210.  
  211. Example:
  212.  
  213. The C<UserGetInfo()> can takes a number of levels. If called with level C<0>
  214. the supplied hash will, on return from the function, contain a single key
  215. and value - namely B<name>/B<requested-users-name>. If called with a level
  216. of C<1> the supplied hash will, on return from the function, contain 8 keys
  217. and values. The returned keys are C<name, password>, C<passwordAge>,
  218. C<priv>, C<homeDir>, C<comment>, C<flags>, C<scriptPath>. See
  219. L<USER INFO FIELDS> for more information on what these represent.
  220.  
  221.  
  222. =head1 Exports
  223.  
  224. By default, Win32API::Net exports no symbols into the callers namespace.
  225. The following tags can be used to selectively import symbols into the
  226. main namespace.
  227.  
  228. =over 8
  229.  
  230. =item C<:User>
  231.  
  232. Exports all symbols needed for the C<User*()> functions.
  233. See L<NET USER FUNCTIONS>.
  234.  
  235. =item C<:Get>
  236.  
  237. Exports all symbols needed for the C<Get*()> functions.
  238. See L<NET GET FUNCTIONS>.
  239.  
  240. =item C<:Group>
  241.  
  242. Exports all symbols needed for the C<Group*()> functions.
  243. See L<NET GROUP FUNCTIONS>.
  244.  
  245. =item C<:LocalGroup>
  246.  
  247. Exports all symbols needed for the C<LocalGroup*()> functions.
  248. See L<NET LOCAL GROUP FUNCTIONS>.
  249.  
  250. =back
  251.  
  252.  
  253. =head1 NET USER FUNCTIONS
  254.  
  255. The C<User*()> functions operate on NT user accounts.
  256.  
  257. Administrator or Account Operator group membership is required to
  258. successfully execute most of these functions on a remote server or on a
  259. computer that has local security enabled. Administrator privileges are
  260. required to add an Administrator Privilege account.  There are some
  261. exceptions to this whereby a user can change some of their own settings
  262. where these don't conflict with 'administrative information' (e.g. full
  263. name).
  264.  
  265. The C<server> field can be the empty string, in which case the function
  266. defaults to running on the local computer. If you leave this field blank
  267. then you should ensure that you are running the function on a PDC or BDC
  268. for your current domain. Use the support function C<GetDCName()> to find out
  269. what the domain controller is, should you not be running this on the PDC.
  270.  
  271. All functions in this section are 'DOMAIN functions'. This means that,
  272. for example, the C<UserGetLocalGroups()> function actually lists the
  273. domain's local groups of which the named user is a member.
  274.  
  275. The following functions are available.
  276.  
  277.  
  278. =head2 UserAdd(server, level, hash, error)
  279.  
  280. Add a new user account. The user name is taken from the C<name>-key's
  281. value in the supplied hash.
  282.  
  283. =over 8
  284.  
  285. =item C<server> - Scalar String
  286.  
  287. The server on which to add the account.
  288.  
  289. =item C<level> - Scalar Int
  290.  
  291. Level of information provided in hash. This can be either 1, 2 or 3.
  292. See L<USER INFO LEVELS>.
  293.  
  294. =item C<hash> - Hash Reference
  295.  
  296. The information to use to add this account. This should have all the
  297. appropriate keys and values required for C<level>.
  298.  
  299. =item C<error> - Scalar Int
  300.  
  301. Provides information on which field in the hash was not properly specified.
  302. See L<USER FIELD ERRORS> for more information about what values this can
  303. take.
  304.  
  305. =back
  306.  
  307. =head2 UserChangePassword(server, user, old, new)
  308.  
  309. Changes the password for C<user>. If the policy of the machine/domain
  310. only allows password changes if the C<user> is logged on then the C<user>
  311. must be logged on to execute this function. With Administrator or Account
  312. Operator privilege you can use this function to change anyone's password,
  313. so long as you know the old password.
  314.  
  315. =over 8
  316.  
  317. =item C<server> - Scalar String
  318.  
  319. The C<server> on which to change the password.
  320.  
  321. =item C<user> - Scalar String
  322.  
  323. The name of the C<user> whose password is being changed.
  324.  
  325. =item C<old> - Scalar String
  326.  
  327. The existing password for C<user>.
  328.  
  329. =item C<new> - Scalar String
  330.  
  331. The new password for C<user>.
  332.  
  333. =back
  334.  
  335.  
  336. =head2 UserDel(server, user)
  337.  
  338. Deletes the specified C<user> account. Administrator or Account Operator
  339. privilege is required to execute this function.
  340.  
  341. =over 8
  342.  
  343. =item C<server> - Scalar String
  344.  
  345. The C<server> on which to delete the C<user>.
  346.  
  347. =item C<user> - Scalar String
  348.  
  349. The C<user> account to delete.
  350.  
  351. =back
  352.  
  353. =head2 UserEnum(server, array[, filter])
  354.  
  355. Enumerates all the accounts on server that satisfy C<filter>. Unlike the
  356. C<NetUserEnum()> function in the API, this function does not allow you
  357. to specify a level (internally it is hardcoded to 0). In Perl it is
  358. trivial to implement the equivalent function (should you need it) - see
  359. L<Example 1>.
  360.  
  361. =over 8
  362.  
  363. =item C<server> - Scalar String
  364.  
  365. The C<server> on which to enumerate the accounts satisfying C<filter>.
  366.  
  367. =item C<array> - Array Reference
  368.  
  369. The array that will hold the names of all users on C<server> whose
  370. accounts match C<filter>.
  371.  
  372. =item C<filter> - Scalar Int (optional)
  373.  
  374. The filter to apply (see L<USER ENUM FILTER>). This argument is optional
  375. and if not present a default of C<FILTER_NORMAL_ACCOUNT> is used.
  376.  
  377. =back
  378.  
  379. =head2 UserGetGroups(server, user, array)
  380.  
  381. Get the global groups for which C<user> is a member. It returns the group
  382. names in C<array>. Unlike the C<NetUserGetGroups()> function in the API,
  383. this function does not allow you to specify a level (internally is
  384. hardcoded to 0). In Perl it is trivial to implement the equivalent function
  385. (in the unlikely event that you might need it).
  386.  
  387. =over 8
  388.  
  389. =item C<server> - Scalar String
  390.  
  391. The C<server> from which to get the groups of which C<user> is a member.
  392.  
  393. =item C<user> - Scalar String
  394.  
  395. The C<user> whose group membership you wish to examine.
  396.  
  397. =item C<array> - Scalar String
  398.  
  399. The array that will contain the group names to which C<user> belongs.
  400.  
  401. =back
  402.  
  403. =head2 UserGetInfo(server, user, level, hash)
  404.  
  405. Returns the information at the specified C<level> for the named C<user>
  406. in C<hash>.
  407.  
  408. =over 8
  409.  
  410. =item C<server> - Scalar String
  411.  
  412. The C<server> from which to get the requested information about C<user>.
  413.  
  414. =item C<user> - Scalar String
  415.  
  416. The C<user> whose information you want.
  417.  
  418. =item C<level> - Scalar Int
  419.  
  420. One of: 0, 1, 2, 3, 10, 11 and 20. See L<USER INFO LEVELS>.
  421.  
  422. =item C<hash> - Hash Reference
  423.  
  424. The hash that will contain the keys and values for the information
  425. requested. See L<USER INFO FIELDS> for information about which keys are
  426. present in a given level.
  427.  
  428. =back
  429.  
  430. =head2 UserGetLocalGroups(server, user, array[, flags])
  431.  
  432. Gets the names of the local groups of which C<user> is a member. Unlike
  433. the C<NetUserEnum()> function in the API, this function does not allow you
  434. to specify a level. Since the underlying API restricts you to level 0 there
  435. really isn't any need to include it...
  436.  
  437. =over 8
  438.  
  439. =item C<server> - Scalar String
  440.  
  441. The server from which to get the local groups of which C<user> is a member.
  442.  
  443. =item C<user> - Scalar String
  444.  
  445. The C<user> whose local group membership you wish to enumerate.
  446.  
  447. =item C<array> - Array Reference
  448.  
  449. The array that will hold the names of the local groups to which C<user>
  450. belongs.
  451.  
  452. =item C<flags> - Scalar Int <em>(optional)</em>
  453.  
  454. Either C<Win32API::Net::LG_INCLUDE_INDIRECT()> or 0. if C<flags> is
  455. omitted, the function internally uses 0. Specifying C<LG_INCLUDE_INDIRECT()>
  456. will include in the list the names of the groups of which the C<user> is
  457. indirectly a member (e.g. by being in a global group that is a member of a
  458. local group).
  459.  
  460. This field can take no other values.
  461.  
  462. =back
  463.  
  464.  
  465. =head2 UserModalsGet()
  466.  
  467. This function is not currently implemented.
  468.  
  469.  
  470. =head2 UserModalsSet()
  471.  
  472. This function is not currently implemented.
  473.  
  474.  
  475. =head2 UserSetGroups(server, user, array)
  476.  
  477. Sets the (global) group membership for C<user> to the specified groups.
  478. Unlike the API function C<NetUserSetGroups()>, this function does not take a
  479. C<level> parameter (mainly because this option is largely redundant).
  480.  
  481. =over 8
  482.  
  483. =item C<server> - Scalar String
  484.  
  485. The C<server> on which you wish to set the group membership for C<user>.
  486.  
  487. =item C<user> - Scalar String
  488.  
  489. The C<user> whose group membership you wish to set.
  490.  
  491. =item C<array> - Array Reference
  492.  
  493. The array containing the (global) group names to set the C<user>s
  494. membership of.
  495.  
  496. =back
  497.  
  498. This function will fail if any of the group names specified do not exist.
  499.  
  500. =head2 UserSetInfo(server, user, level, hash, error)
  501.  
  502. Sets the info for C<user> according to the information contained in C<hash>
  503. for C<level> (see L<USER INFO LEVELS>).
  504.  
  505. =over 8
  506.  
  507. =item C<server> - Scalar String
  508.  
  509. The C<server> on which you wish to change the info for C<user>.
  510.  
  511. =item C<user> - Scalar String
  512.  
  513. The C<user> whose info you wish to change.
  514.  
  515. =item C<level> - Scalar Int
  516.  
  517. One of 0, 1, 2, 3, or 20 (according to Microsoft documentation). In
  518. practice, you can use all the 10xx levels as well to change most of the
  519. individual properties of the named C<user> - although this may not be
  520. supported in future...
  521.  
  522. =item C<hash> - Hash Reference
  523.  
  524. The hash that will contain the necessary key/value pairs required for
  525. C<level> (see L<USER INFO LEVELS>).
  526.  
  527. =item C<error> - Scalar Int
  528.  
  529. Provides information on which field in C<hash> were not properly
  530. specified. See L<USER FIELD ERRORS> for more information about what
  531. values can be returned in this field.
  532.  
  533. =back
  534.  
  535. =head1 NET GROUP FUNCTIONS
  536.  
  537. The C<Group*()> functions all operate only on global groups. To modify
  538. local groups, use the corresponding C<LocalGroup*()> functions.
  539.  
  540. Administrator or Account Operator group membership is required to
  541. successfully execute most of these functions on a remote server or on
  542. a computer that has local security enabled.
  543.  
  544. The C<server> field can be the empty string, in which case the function
  545. defaults to running on the local computer. If you leave this field blank
  546. then you should ensure that you are running the function on a PDC or BDC
  547. for your current domain. Use the support function C<GetDCName()> to find out
  548. what the domain controller is, should you not be running this on the PDC.
  549.  
  550. The following functions are available.
  551.  
  552.  
  553. =head2 GroupAdd(server, level, hash, error)
  554.  
  555. Adds the specified group.
  556.  
  557. =over 8
  558.  
  559. =item C<server> - Scalar String
  560.  
  561. The C<server> on which to add the group.
  562.  
  563. =item C<level> - Scalar String
  564.  
  565. The C<level> of information contained in C<hash>. This can be one of 0, 1
  566. or 2. See L<GROUP INFO LEVELS>.
  567.  
  568. =item C<hash> - Hash Reference
  569.  
  570. A hash containing the required key/value pairs for C<level>.
  571.  
  572. =item C<error> - Scalar Int
  573.  
  574. Provides information on which field in C<hash> was not properly specified.
  575. See L<GROUP FIELD ERRORS> for more information about what values can be
  576. returned in this field.
  577.  
  578. =back
  579.  
  580.  
  581. =head2 GroupAddUser(server, group, user)
  582.  
  583. Adds the specified C<user> to the specified C<group>.
  584.  
  585. =over 8
  586.  
  587. =item C<server> - Scalar String
  588.  
  589. The C<server> on which to add the C<user> to C<group>.
  590.  
  591. =item C<group> - Scalar String
  592.  
  593. The C<group> to add the C<user> to.
  594.  
  595. =item C<user> - Scalar String
  596.  
  597. The C<user> to add to C<group>.
  598.  
  599. =back
  600.  
  601.  
  602.  
  603. =head2 GroupDel(server, group)
  604.  
  605. Deletes the specified global group.
  606.  
  607. =over 8
  608.  
  609. =item C<server> - Scalar String
  610.  
  611. The C<server> on which to delete the named C<group>.
  612.  
  613. =item C<group> -Scalar String
  614.  
  615. The C<group> to delete.
  616.  
  617. =back
  618.  
  619.  
  620.  
  621. =head2 GroupDelUser(server, group, user)
  622.  
  623. Deletes the specified user from the specified group.
  624.  
  625. =over 8
  626.  
  627. =item C<server> - Scalar String
  628.  
  629. The C<server> on which to delete C<user> from C<group>.
  630.  
  631. =item C<group> - Scalar String
  632.  
  633. The C<group> from which to delete C<user>.
  634.  
  635. =item C<user> - Scalar String
  636.  
  637. The C<user> to delete from C<group>.
  638.  
  639. =back
  640.  
  641.  
  642. =head2 GroupEnum(server, array)
  643.  
  644. Enumerates all the global groups on the server. Unlike the API call
  645. C<NetGroupEnum()>, this function does not allow you to specify a level
  646. (internally it is hardcoded to 0). In Perl it is trivial to implement
  647. the equivalent function (should you need it).
  648.  
  649. =over 8
  650.  
  651. =item C<server> - Scalar String
  652.  
  653. The server on which to enumerate the (global) C<groups>.
  654.  
  655. =item C<array> - Array Reference
  656.  
  657. An array that, on return, will contain the C<group> names.
  658.  
  659. =back
  660.  
  661.  
  662. =head2 GroupGetInfo(server, group, level, hash)
  663.  
  664. Retrieves C<level> information for C<group> returning information in
  665. C<hash>.
  666.  
  667. =over 8
  668.  
  669. =item C<server> - Scalar String
  670.  
  671. The C<server> from which to get the group information.
  672.  
  673. =item C<group> - Scalar String
  674.  
  675. The C<group> whose information you wish to obtain.
  676.  
  677. =item C<level> - Scalar Int
  678.  
  679. The C<level> of information you wish to retrieve. This can be one of 1, 2
  680. or 3. See L<GROUP INFO LEVELS>.
  681.  
  682. =item C<hash> - Hash Reference
  683.  
  684. The hash that will contain the information.
  685.  
  686. =back
  687.  
  688.  
  689. =head2 GroupGetUsers(server, group, array)
  690.  
  691. Returns (in C<array>) the users belonging to C<group>. Unlike the API
  692. call C<NetGroupGetUsers()>, this function does not allow you to specify
  693. a level (internally it is hardcoded to 0). In Perl it is trivial to
  694. implement the equivalent function (should you need it).
  695.  
  696. =over 8
  697.  
  698. =item C<server> - Scalar String
  699.  
  700. The C<server> from which to get the group information.
  701.  
  702. =item C<group> - Scalar String
  703.  
  704. The C<group> whose users you wish to obtain.
  705.  
  706. =item C<array> - Array Reference
  707.  
  708. The array to hold the user names retrieved.
  709.  
  710. =back
  711.  
  712. =head2 GroupSetInfo(server, group, level, hash, error)
  713.  
  714. Sets the information for C<group> according to C<level>.
  715.  
  716. =over 8
  717.  
  718. =item C<server> - Scalar String
  719.  
  720. The C<server> on which to set the C<group> information.
  721.  
  722. =item C<group> - Scalar String
  723.  
  724. The C<group> whose information you wish to set.
  725.  
  726. =item C<level> - Scalar Int
  727.  
  728. The C<level> of information you are supplying in C<hash>.  Level can be
  729. one of 0, 1 or 2. See L<GROUP INFO LEVELS>.
  730.  
  731. =item C<hash> - Hash Reference
  732.  
  733. The hash containing the required key/value pairs for C<level>.
  734.  
  735. =item C<error> - Scalar String
  736.  
  737. On failure, the C<error> parameter will contain a value which specifies
  738. which field caused the error. See L<GROUP FIELD ERRORS>.
  739.  
  740. =back
  741.  
  742. =head2 GroupSetUsers(server, group, array)
  743.  
  744. Sets the membership of C<group> to contain only those users specified
  745. in C<array>. This function will fail if any user names contained in the
  746. array are not valid users on C<server>.  On successful completion
  747. C<group> will contain only the users specified in C<array>.  Use the
  748. functions C<GroupAddUser()/GroupDelUser()> to add and delete individual
  749. users from a group.
  750.  
  751. =over 8
  752.  
  753. =item C<server> - Scalar String
  754.  
  755. The C<server> on which to set the C<group> membership.
  756.  
  757. =item C<group> - Scalar String
  758.  
  759. The C<group> to set the membership of.
  760.  
  761. =item C<array> - Array Reference
  762.  
  763. The array containing the names of all users who will be members of C<group>.
  764.  
  765. =back
  766.  
  767. =head1 NET LOCAL GROUP FUNCTIONS
  768.  
  769. The C<LocalGroup*()> functions operate on local groups. If these
  770. functions are run on a PDC then these functions operate on the domains
  771. local groups.
  772.  
  773. Administrator or Account Operator group membership is required to
  774. successfully execute most of these functions on a remote server or on a
  775. computer that has local security enabled.
  776.  
  777. The C<server> field can be the empty string, in which case the function
  778. defaults to running on the local computer. If you leave this field blank
  779. then you should ensure that you are running the function on a PDC or BDC
  780. for your current domain. Use the support function C<GetDCName()> to find
  781. out what the domain controller is, should you not be running this on the PDC.
  782.  
  783. The following functions are available.
  784.  
  785. =head2 LocalGroupAdd(server, level, hash, error)
  786.  
  787. Adds the specified group. The name of the group is contained in the C<name>
  788. key of C<hash>.
  789.  
  790. =over 8
  791.  
  792. =item C<server> - Scalar String
  793.  
  794. The C<server> on which to add the group.
  795.  
  796. =item C<level> - Scalar String
  797.  
  798. The C<level> of information contained in C<hash>. This can be one of 0 or 1.
  799. See L<LOCAL GROUP INFO LEVELS>.
  800.  
  801. =item C<hash> - Hash Reference
  802.  
  803. A hash containing the required key/value pairs for C<level>.
  804.  
  805. =item C<error> - Scalar Int
  806.  
  807. Provides information on which field in C<hash> wasn't properly specified.
  808. See L<LOCAL GROUP FIELD ERRORS> for more information about what values
  809. this can take.
  810.  
  811. =back
  812.  
  813. =head2 LocalGroupAddMember()
  814.  
  815. This function is obselete in the underlying API and has therefore not
  816. been implemented.  Use C<LocalGroupAddMembers> instead.
  817.  
  818. =head2 LocalGroupAddMembers(server, group, array)
  819.  
  820. Adds the specified users (members) to the local group. Unlike the API
  821. function C<NetLocalGroupAddMembers()>, this function does not allow you
  822. to specify a level (internally it is hardcoded to 3).
  823. This was done to simplify the implementation. To add a 'local' user, you
  824. need only specify the C<name>. You can also specify users using the
  825. C<DOMAIN\user> syntax.
  826.  
  827. =over 8
  828.  
  829. =item C<server> - Scalar String
  830.  
  831. The C<server> on which to add the members to C<group>.
  832.  
  833. =item C<group> - Scalar String
  834.  
  835. The C<group> to add the members to.
  836.  
  837. =item C<array> - Array Reference
  838.  
  839. The array containing the members to add to C<group>.
  840.  
  841. =back
  842.  
  843. =head2 LocalGroupDel(server, group)
  844.  
  845. Delete the specified local group.
  846.  
  847. =over 8
  848.  
  849. =item C<server> - Scalar String
  850.  
  851. The C<server> on which to delete the named C<group>.
  852.  
  853. =item C<group> -Scalar String
  854.  
  855. The C<group> to delete.
  856.  
  857. =back
  858.  
  859. =head2 LocalGroupDelMember()
  860.  
  861. This function is obselete in the underlying API and has therefore not
  862. been implemented.  Use C<LocalGroupDelMembers()> instead.
  863.  
  864. =head2 LocalGroupDelMembers(server, group, array)
  865.  
  866. Delete the specified users (members) of the local group. Unlike the API
  867. function C<NetLocalGroupDelMembers()>, this function does not allow you
  868. to specify a level (internally it is hardcoded to 3). This was done to
  869. simplify the implementation. To delete a 'local' user, you need only
  870. specify the C<name>. You can also specify users using the C<DOMAIN\user>
  871. syntax.
  872.  
  873. =over 8
  874.  
  875. =item C<server> - Scalar String
  876.  
  877. The C<server> on which to delete the members from C<group>.
  878.  
  879. =item C<group> - Scalar String
  880.  
  881. The C<group> to delete the members from.
  882.  
  883. =item C<array> - Array Reference
  884.  
  885. The array containing the members to delete from C<group>.
  886.  
  887. =back
  888.  
  889. =head2 LocalGroupEnum(server, array)
  890.  
  891. Enumerates all the local groups on the server. Unlike the API call
  892. C<NetLocalGroupEnum()>, this function does not allow you to specify a
  893. level (internally it is hardcoded to 0). In Perl it is trivial to
  894. implement the equivalent function (should you need it).
  895.  
  896. =over 8
  897.  
  898. =item C<server> - Scalar String
  899.  
  900. The server on which to enumerate the (local) C<groups>.
  901.  
  902. =item C<array> - Array Reference
  903.  
  904. The array to hold the C<group> names.
  905.  
  906. =back
  907.  
  908. =head2 LocalGroupGetInfo(server, group, level, hash)
  909.  
  910. Retrieves C<level> information for C<group>.
  911.  
  912. =over 8
  913.  
  914. =item C<server> - Scalar String
  915.  
  916. The C<server> from which to get the group information.
  917.  
  918. =item C<group> - Scalar String
  919.  
  920. The C<group> whose information you wish to obtain.
  921.  
  922. =item C<level> - Scalar Int
  923.  
  924. The C<level> of information you wish to retrieve. This can be 0 or 1.
  925. See L<LOCAL GROUP INFO LEVELS>.
  926.  
  927. =item C<hash> - Hash Reference
  928.  
  929. The hash that will contain the information.
  930.  
  931. =back
  932.  
  933. =head2 LocalGroupGetMembers(server, group, hash)
  934.  
  935. Retrieves the users belonging to C<group>. Unlike the API call
  936. C<NetLocalGroupGetUsers()>, this function does not allow you to specify
  937. a level (internally it is hardcoded to 0). In Perl it is trivial to
  938. implement the equivalent function (should you need it).
  939.  
  940. =over 8
  941.  
  942. =item C<server> - Scalar String
  943.  
  944. The C<server> from which to retrieve the group information.
  945.  
  946. =item C<group> - Scalar String
  947.  
  948. The C<group> whose users you wish to obtain.
  949.  
  950. =item C<array> - Array Reference
  951.  
  952. The array to hold the user names retrieved.
  953.  
  954. =back
  955.  
  956. =head2 LocalGroupSetInfo(server, level, hash, error)
  957.  
  958. Sets the information for C<group> according to C<level>.
  959.  
  960. =over 8
  961.  
  962. =item C<server> - Scalar String
  963.  
  964. The C<server> on which to set the C<group> information.
  965.  
  966. =item C<group> - Scalar String
  967.  
  968. The C<group> whose information you wish to set.
  969.  
  970. =item C<level> - Scalar Int
  971.  
  972. The C<level> of information you are supplying in C<hash>.
  973. Level can be one of 0 or 1. See L<LOCAL GROUP INFO LEVELS>.
  974.  
  975. =item C<hash> - Hash Reference
  976.  
  977. The hash containing the required key/value pairs for C<level>.
  978.  
  979. =item C<error> - Scalar String
  980.  
  981. On failure, the C<error> parameter will contain a value which specifies
  982. which field caused the error. See L<LOCAL GROUP FIELD ERRORS>.
  983.  
  984. =back
  985.  
  986. =head2 LocalGroupSetMembers()
  987.  
  988. This function has not been implemented at present.
  989.  
  990.  
  991. =head1 NET GET FUNCTIONS
  992.  
  993. =head2 GetDCName(server, domain, domain-controller)
  994.  
  995. Gets the C<domain-controllder> name for C<server> and C<domain>.
  996.  
  997. =over 8
  998.  
  999. =item C<server> - Scalar String
  1000.  
  1001. The C<server> whose domain controller you wish to locate.
  1002.  
  1003. =item C<domain> - Scalar String
  1004.  
  1005. The C<domain> that C<server> is a member of whose domain-controller
  1006. you wish the locate.
  1007.  
  1008. =item C<domain-controller> - Scalar String (output)
  1009.  
  1010. The name of the C<domain-controller> for the requested C<domain>.
  1011.  
  1012. =back
  1013.  
  1014. Note: This module does not implement the C<NetGetAnyDCName()>API function
  1015. as this is obsolete.
  1016.  
  1017.  
  1018.  
  1019. =head1 USER INFO LEVELS
  1020.  
  1021. Most of the C<User*()> functions take a C<level> parameter. This C<level>
  1022. specifies how much detail the corresponding C<hash> should contain (or in
  1023. the case of a C<UserGet*()> function, will contain after the call). The
  1024. following C<level> descriptions provide information on what fields should
  1025. be present for a given level. See L<USER INFO FIELDS> for a description of
  1026. the fields.
  1027.  
  1028. =over 8
  1029.  
  1030. =item Level 0
  1031.  
  1032. name
  1033.  
  1034. =item Level 1
  1035.  
  1036. name, password, passwordAge, priv, homeDir, comment, flags, scriptPath
  1037.  
  1038. =item Level 2
  1039.  
  1040. name, password, passwordAge, priv, homeDir, comment, flags, scriptPath,
  1041. authFlags, fullName, usrComment, parms, workstations, lastLogon,
  1042. lastLogoff, acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount,
  1043. numLogons, logonServer, countryCode, codePage
  1044.  
  1045. =item Level 3
  1046.  
  1047. name, password, passwordAge, priv, homeDir, comment, flags, scriptPath,
  1048. authFlags, fullName, usrComment, parms, workstations, lastLogon, lastLogoff,
  1049. acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount, numLogons,
  1050. logonServer, countryCode, codePage, userId, primaryGroupId, profile,
  1051. homeDirDrive, passwordExpired
  1052.  
  1053. =item Level 10
  1054.  
  1055. name, comment, usrComment, fullName
  1056.  
  1057. =item Level 11
  1058.  
  1059. name, comment, usrComment, fullName, priv, authFlags, passwordAge, homeDir,
  1060. parms, lastLogon, lastLogoff, badPwCount, numLogons, logonServer,
  1061. countryCode, workstations, maxStorage, unitsPerWeek, logonHours, codePage
  1062.  
  1063. =item Level 20
  1064.  
  1065. name, fullName, comment, flags, userId
  1066.  
  1067. =item Level 21
  1068.  
  1069. B<Not available in this implementation>
  1070.  
  1071. =item Level 22
  1072.  
  1073. B<Not available in this implementation>
  1074.  
  1075. =item Level 1003
  1076.  
  1077. password
  1078.  
  1079. =item Level 1005
  1080.  
  1081. priv
  1082.  
  1083. =item Level 1006
  1084.  
  1085. homeDir
  1086.  
  1087. =item Level 1007
  1088.  
  1089. comment
  1090.  
  1091. =item Level 1008
  1092.  
  1093. flags
  1094.  
  1095. =item Level 1009
  1096.  
  1097. scriptPath
  1098.  
  1099. =item Level 1010
  1100.  
  1101. authFlags
  1102.  
  1103. =item Level 1011
  1104.  
  1105. fullName
  1106.  
  1107. =item Level 1012
  1108.  
  1109. usrComment
  1110.  
  1111. =item Level 1013
  1112.  
  1113. parms
  1114.  
  1115. =item Level 1014
  1116.  
  1117. workstations
  1118.  
  1119. =item Level 1017
  1120.  
  1121. acctExpires
  1122.  
  1123. =item Level 1018
  1124.  
  1125. maxStorage
  1126.  
  1127. =item Level 1020
  1128.  
  1129. unitsPerWeek, logonHours
  1130.  
  1131. =item Level 1023
  1132.  
  1133. logonServer
  1134.  
  1135. =item Level 1024
  1136.  
  1137. countryCode
  1138.  
  1139. =item Level 1025
  1140.  
  1141. codePage
  1142.  
  1143. =item Level 1051
  1144.  
  1145. primaryGroupId
  1146.  
  1147. =item Level 1052
  1148.  
  1149. profile
  1150.  
  1151. =item Level 1053
  1152.  
  1153. homeDirDrive
  1154.  
  1155. =back
  1156.  
  1157.  
  1158.  
  1159. =head1 USER INFO FIELDS
  1160.  
  1161. The following is an alphabetical listing of each possible field, together
  1162. with the data type that the field is expected to contain.
  1163.  
  1164. =over 8
  1165.  
  1166. =item C<acctExpires> - Scalar Int (UTC)
  1167.  
  1168. The time (as the number of seconds since 00:00:00, 1st January 1970) when
  1169. the account expires. A -1 in this field specifies that the account never
  1170. expires.
  1171.  
  1172. =item C<authFlags> - Scalar Int (See USER_AUTH_FLAGS).
  1173.  
  1174. The level of authority that this use has. The value this can take depends
  1175. on the users group membership - this value is therefore read only and
  1176. cannot be set using C<UserAdd()> or C<UserSetInfo()>. Its value can be one
  1177. of:
  1178.  
  1179. =back
  1180.  
  1181.  
  1182.     User belongs to group        Flag value
  1183.     ---------------------        ----------
  1184.     Print Operators            Win32API::Net::AF_OP_PRINT()
  1185.     Server Operators        Win32API::Net::AF_OP_SERVER()
  1186.     Account Operators        Win32API::Net::AF_OP_ACCOUNTS()
  1187.  
  1188.  
  1189. =over 8
  1190.  
  1191. =item C<badPwCount> - Scalar Int
  1192.  
  1193. The number of times that the user has failed to logon by specifying an
  1194. incorrect password.
  1195.  
  1196. =item C<codePage> - Scalar Int
  1197.  
  1198. The code page that this user uses.
  1199.  
  1200. =item C<comment> - Scalar String
  1201.  
  1202. The comment associated with this user account. This can be any string
  1203. (apparently of any length).
  1204.  
  1205. =item C<countryCode> - Scalar Int
  1206.  
  1207. The country code that this user uses.
  1208.  
  1209. =item C<flags> - Scalar Int (Bitwise OR of USER_FLAGS)
  1210.  
  1211. The flags for this user. See L<USER FLAGS>.
  1212.  
  1213. =item C<fullName> - Scalar String
  1214.  
  1215. The users' full name.
  1216.  
  1217. =item C<homeDir> - Scalar String
  1218.  
  1219. The home directory of the user. This can be either a UNC path or an
  1220. absolute path (drive letter + path). Can be the empty string ("").
  1221.  
  1222. =item C<homeDirDrive> - Scalar String
  1223.  
  1224. The home directory drive that the users home directory is mapped to
  1225. (assuming that the specified home directory is a UNC path).
  1226.  
  1227. =item C<lastLogon> - Scalar Int (UTC)
  1228.  
  1229. The time (as the number of seconds since 00:00:00, 1st January 1970)
  1230. that the user last logged on.
  1231.  
  1232. =item C<lastLogoff> - Scalar Int (UTC)
  1233.  
  1234. The time (as the number of seconds since 00:00:00, 1st January 1970)
  1235. that the user last logged off .
  1236.  
  1237. =item C<logonHours> - Reference to Array of Integers (length 21 elements)
  1238.  
  1239. The times at which the user can logon. This should be an integer array
  1240. with 21 elements.  Each element represents an 8 hour period and each bit
  1241. represents represents an hour. Only the lower byte of each integer is
  1242. used. If this is left undefined then no restrictions are placed on the
  1243. account.
  1244.  
  1245. =item C<logonServer> - Scalar String
  1246.  
  1247. The logon server for this user. Under Windows NT, this value cannot be
  1248. set and will always have the value '\\*' when queried.
  1249.  
  1250. =item C<maxStorage> - Scalar Int
  1251.  
  1252. The current release of Windows NT does not implement disk quotas so
  1253. it is believed that the value of this key is ignored.
  1254.  
  1255. =item C<name> - Scalar String
  1256.  
  1257. The user name that this request applies to. Most of the functions take
  1258. the user name as a separate argument. In general, the user name provided
  1259. should be the same as that in the one provided in the hash.
  1260.  
  1261. =item C<numLogons> - Scalar Int
  1262.  
  1263. The number of times that the named user has successfully logged on to
  1264. this machine/domain.
  1265.  
  1266. =item C<parms> - Scalar String
  1267.  
  1268. The value of this key can be used by applications. There are none known
  1269. to to author that use it, although it could be used to hold adminitrative
  1270. information.
  1271.  
  1272. =item C<password> - Scalar String
  1273.  
  1274. The password to be set. The password is never returned in a C<UserGet()>
  1275. operation.
  1276.  
  1277. =item C<passwordAge> - Scalar Int (UTC)
  1278.  
  1279. The current age of the password (stored as the number of seconds since
  1280. 00:00:00, 1st January 1970).
  1281.  
  1282. =item C<passwordExpired> - Scalar Int
  1283.  
  1284. The value of this key is used in two different ways. When queried via
  1285. C<UserGetInfo()> the return value is 0 is the password has not expired
  1286. and 1 if it has. When setting the value via C<UserAdd()> or
  1287. C<UserSetInfo()> a value of 0 indicates that the users' password has
  1288. not expired whereas a value of 1 will force the user to change their
  1289. password at the next logon.
  1290.  
  1291. =item C<primaryGroupId> - Scalar Int
  1292.  
  1293. The id of the primary group that this user belongs to. When creating
  1294. accounts with C<UserAdd()> you should use a value of 0x201.
  1295.  
  1296. =item C<priv> - Scalar Int (Bitwise OR of USER_PRIVILEGE_FLAGS)
  1297.  
  1298. The privilege level that this user has. This is never returned from a
  1299. C<UserGet()> call. See L<USER PRIVILEGE FLAGS>.
  1300.  
  1301. =item C<profile> - Scalar String
  1302.  
  1303. The profile that is associated with the named user. This can be UNC path,
  1304. a local path or undefined.
  1305.  
  1306. =item C<scriptPath> - Scalar String
  1307.  
  1308. The path to the logon script for this user. This should be specified as a
  1309. relative path and will cause the logon script to be run from (relative
  1310. location) in the logon servers export directory.
  1311.  
  1312. =item C<unitsPerWeek> - Scalar Int
  1313.  
  1314. The value of this key represents the granularity of the logonHours array.
  1315. Its use is beyond the scope of this package.
  1316.  
  1317. =item C<usrComment> - Scalar String
  1318.  
  1319. The user comment field (contrasted with the comment field ;-).
  1320.  
  1321. =item C<workstations> - Scalar String
  1322.  
  1323. A comma-separated string containing upto 8 workstation that the named
  1324. user can login to.  Setting a value for this key will then allow the
  1325. named user to login to only those computers named.
  1326.  
  1327. =item C<userId> - Scalar Int
  1328.  
  1329. The user id associated with this user This value is generated by the
  1330. system and cannot be set or changed using the C<UserAdd()> or
  1331. C<UserSetInfo()> calls.
  1332.  
  1333. =back
  1334.  
  1335.  
  1336.  
  1337. =head1 USER FLAGS
  1338.  
  1339. The following is an alphabetical listing of the user flags.
  1340. The C<flags> key (see L<USER INFO FIELDS>) should be the bitwise OR of one
  1341. or more of these values.
  1342.  
  1343. =over 8
  1344.  
  1345. =item C<UF_ACCOUNTDISABLE()>
  1346.  
  1347. This account has been disabled.
  1348.  
  1349. =item C<UF_DONT_EXPIRE_PASSWD()>
  1350.  
  1351. Never expire the password on this account.
  1352.  
  1353. =item C<UF_HOMEDIR_REQUIRED()>
  1354.  
  1355. A home directory must be specified (ignored for NT).
  1356.  
  1357. =item C<UF_INTERDOMAIN_TRUST_ACCOUNT()>
  1358.  
  1359. The account represents a interdomain trust account.
  1360.  
  1361. =item C<UF_LOCKOUT()>
  1362.  
  1363. Lock out this account (or this account has been locked out due to
  1364. security policy - i.e.  badLogonCount is greater than your policy allows).
  1365. This value can be cleared but not set by a C<UserSetInfo()> call.
  1366.  
  1367. =item C<UF_NORMAL_ACCOUNT()>
  1368.  
  1369. The account is a normal user account.
  1370.  
  1371. =item C<UF_PASSWD_CANT_CHANGE()>
  1372.  
  1373. The password for this account cannot be changed (execpt by an Administrator
  1374. using one of the above calls).
  1375.  
  1376. =item C<UF_PASSWD_NOTREQD()>
  1377.  
  1378. A password is not required for this account.
  1379.  
  1380. =item C<UF_SCRIPT()>
  1381.  
  1382. This <strong>must be set when creating account on Windows NT.
  1383.  
  1384. =item C<UF_SERVER_TRUST_ACCOUNT()>
  1385.  
  1386. The account represents a Windows NT Backup Domain Controller account in
  1387. the domain.
  1388.  
  1389. =item C<UF_TEMP_DUPLICATE_ACCOUNT()>
  1390.  
  1391. To quote the Microsoft Documentation <em>"This is an account for
  1392. users whose primary account is in another domain. This account provides
  1393. user access to this domain, but not to any domain that trusts this domain.
  1394. The User Manager refers to this account type as a local user account.
  1395.  
  1396. =item C<UF_WORKSTATION_TRUST_ACCOUNT()>
  1397.  
  1398. The account represents a computer account for a workstation or server in
  1399. the domain.
  1400.  
  1401. =back
  1402.  
  1403. Please note that these are implemented as functions and are therefore
  1404. called in the same way as other functions. You should typically use them
  1405. like:
  1406.  
  1407.     $ufScript = Win32API::Net::UF_SCRIPT();
  1408.  
  1409. =head1 USER PRIVILEGE FLAGS
  1410.  
  1411. These following values are used in the C<priv> key. This field is never
  1412. initialised on a C<UserGet*()> call and once set cannot be changed in a
  1413. C<UserSetInfo()> call.
  1414.  
  1415. =over 8
  1416.  
  1417. =item C<USER_PRIV_ADMIN()>
  1418.  
  1419. Account is an an administrative account.
  1420.  
  1421. =item C<USER_PRIV_GUEST()>
  1422.  
  1423. Account is a guest account.
  1424.  
  1425. =item C<USER_PRIV_USER()>
  1426.  
  1427. Account is a user account.
  1428.  
  1429. =back
  1430.  
  1431. Please note that these are implemented as functions and are therefore
  1432. called in the same way as other functions. You should typically use them
  1433. like:
  1434.  
  1435.     $userPrivUser = Win32API::Net::USER_PRIV_USER();
  1436.  
  1437. =head1 USER ENUM FILTER
  1438.  
  1439. These flags are used in the C<UserEnum()> function to specify which
  1440. accounts to retrieve. It should be a bitwise OR of some (or all) of
  1441. the following.
  1442.  
  1443. =over 8
  1444.  
  1445. =item C<FILTER_TEMP_DUPLICATE_ACCOUNT()>
  1446.  
  1447. Show temporary duplicate account (one presumes).
  1448.  
  1449. =item C<FILTER_NORMAL_ACCOUNT()>
  1450.  
  1451. Show normal user account.
  1452.  
  1453. =item C<FILTER_INTERDOMAIN_TRUST_ACCOUNT()>
  1454.  
  1455. Show interdomain trust accounts.
  1456.  
  1457. =item C<FILTER_WORKSTATION_TRUST_ACCOUNT()>
  1458.  
  1459. Show workstation trust accounts.
  1460.  
  1461. =item C<FILTER_SERVER_TRUST_ACCOUNT()>
  1462.  
  1463. Show server trust accounts.
  1464.  
  1465. =back
  1466.  
  1467. Please note that these are implemented as functions and are therefore
  1468. called in the same way as other functions. You should typically use them
  1469. like:
  1470.  
  1471.     $filterNormalAccounts = Win32API::Net::FILTER_NORMAL_ACCOUNT();
  1472.  
  1473. =head1 USER FIELD ERRORS
  1474.  
  1475. For the C<User*()> functions that take an C<error> parameter this variable
  1476. will, on failure, contain one of the following constants. Note that the
  1477. function may fail because more than one key/value was missing from the
  1478. input hash. You will only find out about the first one that was incorrectly
  1479. specified. This is only really useful in debugging.
  1480.  
  1481. =over 8
  1482.  
  1483. =item C<USER_ACCT_EXPIRES_PARMNUM()>
  1484.  
  1485. C<acctExpires> field was absent or not correctly specified.
  1486.  
  1487. =item C<USER_AUTH_FLAGS_PARMNUM()>
  1488.  
  1489. C<authFlags> field was absent or not correctly specified.
  1490.  
  1491. =item C<USER_BAD_PW_COUNT_PARMNUM()>
  1492.  
  1493. C<badPasswordCount> field was absent or not correctly specified.
  1494.  
  1495. =item C<USER_CODE_PAGE_PARMNUM()>
  1496.  
  1497. C<codePage> field was absent or not correctly specified.
  1498.  
  1499. =item C<USER_COMMENT_PARMNUM()>
  1500.  
  1501. C<comment> field was absent or not correctly specified.
  1502.  
  1503. =item C<USER_COUNTRY_CODE_PARMNUM()>
  1504.  
  1505. C<countryCode> field was absent or not correctly specified.
  1506.  
  1507. =item C<USER_FLAGS_PARMNUM()>
  1508.  
  1509. C<flags> field was absent or not correctly specified.
  1510.  
  1511. =item C<USER_FULL_NAME_PARMNUM()>
  1512.  
  1513. C<fullName> field was absent or not correctly specified.
  1514.  
  1515. =item C<USER_HOME_DIR_DRIVE_PARMNUM()>
  1516.  
  1517. C<homeDirDrive> field was absent or not correctly specified.
  1518.  
  1519. =item C<USER_HOME_DIR_PARMNUM()>
  1520.  
  1521. C<homeDir> field was absent or not correctly specified.
  1522.  
  1523. =item C<USER_LAST_LOGOFF_PARMNUM()>
  1524.  
  1525. C<lastLogoff> field was absent or not correctly specified.
  1526.  
  1527. =item C<USER_LAST_LOGON_PARMNUM()>
  1528.  
  1529. C<lastLogon> field was absent or not correctly specified.
  1530.  
  1531. =item C<USER_LOGON_HOURS_PARMNUM()>
  1532.  
  1533. C<logonHours> field was absent or not correctly specified.
  1534.  
  1535. =item C<USER_LOGON_SERVER_PARMNUM()>
  1536.  
  1537. C<logonServer> field was absent or not correctly specified.
  1538.  
  1539. =item C<USER_MAX_STORAGE_PARMNUM()>
  1540.  
  1541. C<maxStorage> field was absent or not correctly specified.
  1542.  
  1543. =item C<USER_NAME_PARMNUM()>
  1544.  
  1545. C<name> field was absent or not correctly specified.
  1546.  
  1547. =item C<USER_NUM_LOGONS_PARMNUM()>
  1548.  
  1549. C<numLogons> field was absent or not correctly specified.
  1550.  
  1551. =item C<USER_PARMS_PARMNUM()>
  1552.  
  1553. C<parms> field was absent or not correctly specified.
  1554.  
  1555. =item C<USER_PASSWORD_AGE_PARMNUM()>
  1556.  
  1557. C<passwordAge> field was absent or not correctly specified.
  1558.  
  1559. =item C<USER_PASSWORD_PARMNUM()>
  1560.  
  1561. C<password> field was absent or not correctly specified.
  1562.  
  1563. =item C<USER_PRIMARY_GROUP_PARMNUM()>
  1564.  
  1565. C<primaryGroup> field was absent or not correctly specified.
  1566.  
  1567. =item C<USER_PRIV_PARMNUM()>
  1568.  
  1569. C<priv> field was absent or not correctly specified.
  1570.  
  1571. =item C<USER_PROFILE_PARMNUM()>
  1572.  
  1573. C<profile> field was absent or not correctly specified.
  1574.  
  1575. =item C<USER_SCRIPT_PATH_PARMNUM()>
  1576.  
  1577. C<scriptPath> field was absent or not correctly specified.
  1578.  
  1579. =item C<USER_UNITS_PER_WEEK_PARMNUM()>
  1580.  
  1581. C<unitPerWeek> field was absent or not correctly specified.
  1582.  
  1583. =item C<USER_USR_COMMENT_PARMNUM()>
  1584.  
  1585. C<usrComment> field was absent or not correctly specified.
  1586.  
  1587. =item C<USER_WORKSTATIONS_PARMNUM()>
  1588.  
  1589. C<workstations> field was absent or not correctly specified.
  1590.  
  1591. =back
  1592.  
  1593.  
  1594. =head1 GROUP INFO LEVELS
  1595.  
  1596. Some of the C<Group*()> functions take a C<level> parameter. This C<level>
  1597. specifies how much detail the corresponding C<hash> should contain (or in
  1598. the case of a C<GroupGetInfo()> function, will contain after the call).
  1599. The following C<level> descriptions provide information on what fields
  1600. should be present for a given level. See L<GROUP INFO FIELDS>
  1601. for a description of the fields.
  1602.  
  1603. =over 8
  1604.  
  1605. =item C<Level 0>
  1606.  
  1607. name.
  1608.  
  1609. =item C<Level 1>
  1610.  
  1611. name, comment.
  1612.  
  1613. =item C<Level 2>
  1614.  
  1615. name, comment, groupId, attributes.
  1616.  
  1617. =item C<Level 1002>
  1618.  
  1619. comment.
  1620.  
  1621. =item C<Level 1005>
  1622.  
  1623. attributes.
  1624.  
  1625. =back
  1626.  
  1627.  
  1628. =head1 GROUP INFO FIELDS
  1629.  
  1630. =over 8
  1631.  
  1632. =item C<attributes> - Scalar Int
  1633.  
  1634. The attributes of the group. These are no longer settable in Windows NT 4.0
  1635. and they are not currently supported in this package either.
  1636.  
  1637. =item C<comment> - Scalar String
  1638.  
  1639. The C<comment> that applies to this group. This is the only value that
  1640. can be set via a GroupSetInfo call.
  1641.  
  1642. =item C<groupId> - Scalar Int
  1643.  
  1644. The groups Id.
  1645.  
  1646. =item C<name> - Scalar String
  1647.  
  1648. The groups name.
  1649.  
  1650. =back
  1651.  
  1652.  
  1653.  
  1654. =head1 GROUP FIELD ERRORS
  1655.  
  1656. For the C<Group*()> functions that take an C<error> parameter
  1657. this variable will, on failure, contain one of the following constants.
  1658. Note that the function may fail because more than one key/value was
  1659. missing from the input hash. You will only find out about the first one
  1660. that was incorrectly specified. This is only really useful for debugging
  1661. purposes.
  1662.  
  1663. =over 8
  1664.  
  1665. =item C<GROUP_ATTRIBUTES_PARMNUM()>
  1666.  
  1667. C<attributes> field was absent or not correctly specified.
  1668.  
  1669. =item C<GROUP_COMMENT_PARMNUM()>
  1670.  
  1671. C<comment> field was absent or not correctly specified.
  1672.  
  1673. =item C<GROUP_NAME_PARMNUM()>
  1674.  
  1675. C<name> field was absent or not correctly specified.
  1676.  
  1677. =back
  1678.  
  1679.  
  1680.  
  1681. =head1 GROUP USERS INFO LEVELS
  1682.  
  1683. The C<GroupGetUsers()> function can take a level of 0 or 1. These will
  1684. return the following:
  1685.  
  1686. =over 8
  1687.  
  1688. =item C<Level 0>
  1689.  
  1690. name.
  1691.  
  1692. =item C<Level 1>
  1693.  
  1694. name, attributes.
  1695.  
  1696. =back
  1697.  
  1698.  
  1699. =head1 GROUP USERS INFO FIELDS
  1700.  
  1701. =over 8
  1702.  
  1703. =item C<name> - Scalar String
  1704.  
  1705. The user's name.
  1706.  
  1707. =item C<attributes> - Scalar Int
  1708.  
  1709. The attributes of the group. These are no longer settable in Windows NT
  1710. 4.0 and they are not currently supported in this package either.
  1711.  
  1712. =back
  1713.  
  1714.  
  1715.  
  1716. =head1 LOCAL GROUP INFO LEVELS
  1717.  
  1718. =over 8
  1719.  
  1720. =item C<Level 0>
  1721.  
  1722. name
  1723.  
  1724. =item C<Level 1>
  1725.  
  1726. name, comment
  1727.  
  1728. =item C<Level 1002>
  1729.  
  1730. comment
  1731.  
  1732.  
  1733. =back
  1734.  
  1735.  
  1736.  
  1737. =head1 LOCAL GROUP INFO FIELDS
  1738.  
  1739. =over 8
  1740.  
  1741. =item C<name> - Scalar String
  1742.  
  1743. The groups name
  1744.  
  1745. =item C<comment> - Scalar String
  1746.  
  1747. The groups 'comment'
  1748.  
  1749. =back
  1750.  
  1751.  
  1752. =head1 LOCAL GROUP FIELD ERRORS
  1753.  
  1754. For the C<LocalGroup*()> functions that take an C<error> parameter this
  1755. variable will, on failure, contain one of the following constants. Note
  1756. that the function may fail because more than one key/value was missing
  1757. or incorrectly specified in the input hash. You will only find out about
  1758. the first one that was incorrectly specified. This is only really useful
  1759. for debugging purposes.
  1760.  
  1761. =over 8
  1762.  
  1763. =item C<LOCALGROUP_NAME_PARMNUM()>
  1764.  
  1765. The C<name> field was absent or not correctly specified.
  1766.  
  1767. =item C<LOCALGROUP_COMMENT_PARMNUM()>
  1768.  
  1769. The C<comment> field wasabsent or not correctly specified.
  1770.  
  1771. =back
  1772.  
  1773. =head1 EXAMPLES
  1774.  
  1775. The following example shows how you can create a function in Perl that
  1776. has the same functionality as the C<NetUserEnum()> API call. The Perl
  1777. version doesn't have the level parameter so you must first use the
  1778. C<UserEnum()> function to retrieve all the account names and then iterate
  1779. through the returned array issuing C<UserGetInfo()> calls.
  1780.  
  1781.     sub userEnumAtLevel {
  1782.        my($server, $level, $filter) = @_;
  1783.        my(@array);
  1784.        Win32API::Net::UserEnum($server, \@array, $filter);
  1785.        for $user (@array) {
  1786.       Win32API::Net::UserGetInfo($server, $user, $level, \%hash);
  1787.       print "This could access all level $level settings for $user - eg fullName $hash{fullName}\n";
  1788.        }
  1789.     }
  1790.     userEnumAtLevel("", 2, 0);
  1791.  
  1792.  
  1793.  
  1794. =head1 AUTHOR
  1795.  
  1796. Bret Giddings, <bret@essex.ac.uk>
  1797.  
  1798.  
  1799. =head1 SEE ALSO
  1800.  
  1801. C<perl(1)>
  1802.  
  1803.  
  1804. =head1 ACKNOWEDGEMENTS
  1805.  
  1806. This work was built upon work done by HiP Communications along with
  1807. modifications to HiPs code by <michael@ecel.uwa.edu.au> and <rothd@roth.net>.
  1808. In addition, I would like to thank Jenny Emby at GEC Marconi, U.K. for
  1809. proof reading this manual page and making many suggestions that have led
  1810. to its current layout. Last but not least I would like to thank Larry Wall
  1811. and all the other Perl contributors for making this truly wonderful
  1812. language.
  1813.  
  1814. =cut
  1815.