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