home *** CD-ROM | disk | FTP | other *** search
/ PC Format (South-Africa) 2001 June / PCFJune.iso / Xenon / C++ / FreeCommandLineTools.exe / Include / userenv.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-01-31  |  35.1 KB  |  1,022 lines
  1.  
  2. //=============================================================================
  3. //  userenv.h   -   Header file for user environment API.
  4. //                  User Profiles, environment variables, and Group Policy
  5. //
  6. //  Copyright (c) Microsoft Corporation 1995-1999
  7. //  All rights reserved
  8. //
  9. //=============================================================================
  10.  
  11.  
  12. #ifndef _INC_USERENV
  13. #pragma option push -b -a8 -pc -A- /*P_O_Push*/
  14. #define _INC_USERENV
  15.  
  16. //
  17. // Define API decoration for direct importing of DLL references.
  18. //
  19.  
  20. #if !defined(_USERENV_)
  21. #define USERENVAPI DECLSPEC_IMPORT
  22. #else
  23. #define USERENVAPI
  24. #endif
  25.  
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. //=============================================================================
  32. //
  33. // LoadUserProfile
  34. //
  35. // Loads the specified user's profile.
  36. //
  37. // Most applications should not need to use this function.  It's used
  38. // when a user has logged onto the system or a service starts in a named
  39. // user account.
  40. //
  41. // hToken        - Token for the user, returned from LogonUser()
  42. // lpProfileInfo - Address of a PROFILEINFO structure
  43. //
  44. // Returns:  TRUE if successful
  45. //           FALSE if not.  Call GetLastError() for more details
  46. //
  47. // Note:  The caller of this function must have admin privileges on the machine.
  48. //
  49. //        Upon successful return, the hProfile member of the PROFILEINFO
  50. //        structure is a registry key handle opened to the root
  51. //        of the user's hive.  It has been opened with full access. If
  52. //        you need to read or write to the user's registry file, use
  53. //        this key instead of HKEY_CURRENT_USER.  Do not close this
  54. //        handle.  Instead pass it to UnloadUserProfile to close
  55. //        the handle.
  56. //
  57. //=============================================================================
  58.  
  59. //
  60. // Flags that can be set in the dwFlags field
  61. //
  62.  
  63. #define PI_NOUI         0x00000001      // Prevents displaying of messages
  64. #define PI_APPLYPOLICY  0x00000002      // Apply NT4 style policy
  65.  
  66. typedef struct _PROFILEINFOA {
  67.     DWORD       dwSize;                 // Set to sizeof(PROFILEINFO) before calling
  68.     DWORD       dwFlags;                // See flags above
  69.     LPSTR       lpUserName;             // User name (required)
  70.     LPSTR       lpProfilePath;          // Roaming profile path (optional, can be NULL)
  71.     LPSTR       lpDefaultPath;          // Default user profile path (optional, can be NULL)
  72.     LPSTR       lpServerName;           // Validating domain controller name in netbios format (optional, can be NULL but group NT4 style policy won't be applied)
  73.     LPSTR       lpPolicyPath;           // Path to the NT4 style policy file (optional, can be NULL)
  74.     HANDLE      hProfile;               // Filled in by the function.  Registry key handle open to the root.
  75. } PROFILEINFOA, FAR * LPPROFILEINFOA;
  76. typedef struct _PROFILEINFOW {
  77.     DWORD       dwSize;                 // Set to sizeof(PROFILEINFO) before calling
  78.     DWORD       dwFlags;                // See flags above
  79.     LPWSTR      lpUserName;             // User name (required)
  80.     LPWSTR      lpProfilePath;          // Roaming profile path (optional, can be NULL)
  81.     LPWSTR      lpDefaultPath;          // Default user profile path (optional, can be NULL)
  82.     LPWSTR      lpServerName;           // Validating domain controller name in netbios format (optional, can be NULL but group NT4 style policy won't be applied)
  83.     LPWSTR      lpPolicyPath;           // Path to the NT4 style policy file (optional, can be NULL)
  84.     HANDLE      hProfile;               // Filled in by the function.  Registry key handle open to the root.
  85. } PROFILEINFOW, FAR * LPPROFILEINFOW;
  86. #ifdef UNICODE
  87. typedef PROFILEINFOW PROFILEINFO;
  88. typedef LPPROFILEINFOW LPPROFILEINFO;
  89. #else
  90. typedef PROFILEINFOA PROFILEINFO;
  91. typedef LPPROFILEINFOA LPPROFILEINFO;
  92. #endif // UNICODE
  93.  
  94.  
  95.  
  96. USERENVAPI
  97. BOOL
  98. WINAPI
  99. LoadUserProfileA(
  100.     IN HANDLE hToken,
  101.     IN OUT LPPROFILEINFOA lpProfileInfo);
  102. USERENVAPI
  103. BOOL
  104. WINAPI
  105. LoadUserProfileW(
  106.     IN HANDLE hToken,
  107.     IN OUT LPPROFILEINFOW lpProfileInfo);
  108. #ifdef UNICODE
  109. #define LoadUserProfile  LoadUserProfileW
  110. #else
  111. #define LoadUserProfile  LoadUserProfileA
  112. #endif // !UNICODE
  113.  
  114.  
  115. //=============================================================================
  116. //
  117. // UnloadUserProfile
  118. //
  119. // Unloads a user's profile that was loaded by LoadUserProfile()
  120. //
  121. // hToken        -  Token for the user, returned from LogonUser()
  122. // hProfile      -  hProfile member of the PROFILEINFO structure
  123. //
  124. // Returns:  TRUE if successful
  125. //           FALSE if not.  Call GetLastError() for more details
  126. //
  127. // Note:     The caller of this function must have admin privileges on the machine.
  128. //
  129. //=============================================================================
  130.  
  131. USERENVAPI
  132. BOOL
  133. WINAPI
  134. UnloadUserProfile(
  135.     IN HANDLE hToken,
  136.     IN HANDLE hProfile);
  137.  
  138.  
  139. //=============================================================================
  140. //
  141. // GetProfilesDirectory
  142. //
  143. // Returns the path to the root of where all user profiles are stored.
  144. //
  145. // lpProfilesDir  -  Receives the path
  146. // lpcchSize      -  Size of lpProfilesDir
  147. //
  148. // Returns:  TRUE if successful
  149. //           FALSE if not.  Call GetLastError() for more details
  150. //
  151. // Note:     If lpProfilesDir is not large enough, the function will fail,
  152. //           and lpcchSize will contain the necessary buffer size.
  153. //
  154. // Example return value: C:\Documents and Settings
  155. //
  156. //=============================================================================
  157.  
  158. USERENVAPI
  159. BOOL
  160. WINAPI
  161. GetProfilesDirectoryA(
  162.     OUT LPSTR lpProfilesDir,
  163.     IN OUT LPDWORD lpcchSize);
  164. USERENVAPI
  165. BOOL
  166. WINAPI
  167. GetProfilesDirectoryW(
  168.     OUT LPWSTR lpProfilesDir,
  169.     IN OUT LPDWORD lpcchSize);
  170. #ifdef UNICODE
  171. #define GetProfilesDirectory  GetProfilesDirectoryW
  172. #else
  173. #define GetProfilesDirectory  GetProfilesDirectoryA
  174. #endif // !UNICODE
  175.  
  176.  
  177. //=============================================================================
  178. //
  179. //  GetProfileType()
  180. //
  181. //  Returns the type of the profile that is loaded for a user.
  182. //
  183. //  dwFlags   - Returns the profile flags
  184. //
  185. //  Return:     TRUE if successful
  186. //              FALSE if an error occurs. Call GetLastError for more details
  187. //
  188. //  Comments:   if profile is not already loaded the function will return an error.
  189. //              The caller needs to have access to HKLM part of the registry.
  190. //              (exists by default)
  191. //
  192. //=============================================================================
  193.  
  194. #if(WINVER >= 0x0500)
  195.  
  196. //
  197. // Flags that can be set in the dwFlags field
  198. //
  199.  
  200. #define PT_TEMPORARY         0x00000001      // A profile has been allocated that will be deleted at logoff.
  201. #define PT_ROAMING           0x00000002      // The loaded profile is a roaming profile.
  202. #define PT_MANDATORY         0x00000004      // The loaded profile is mandatory.
  203.  
  204. USERENVAPI
  205. BOOL
  206. WINAPI
  207. GetProfileType(
  208.     OUT DWORD *dwFlags);
  209.  
  210. #endif /* WINVER >= 0x0500 */
  211.  
  212. //=============================================================================
  213. //
  214. //  DeleteProfile()
  215. //
  216. //  Deletes the profile and all other user related settings from the machine
  217. //
  218. //  lpSidString    - String form of the user sid.
  219. //  lpProfilePath  - ProfilePath (if Null, lookup in the registry)
  220. //  lpComputerName - Computer Name from which profile has to be deleted
  221. //
  222. //  Return:     TRUE if successful
  223. //              FALSE if an error occurs. Call GetLastError for more details
  224. //
  225. //  Comments:   Deletes the profile directory, registry and appmgmt stuff
  226. //=============================================================================
  227.  
  228. #if(WINVER >= 0x0500)
  229.  
  230. USERENVAPI
  231. BOOL
  232. WINAPI
  233. DeleteProfileA (
  234.         IN LPCSTR lpSidString,
  235.         IN LPCSTR lpProfilePath,
  236.     IN LPCSTR lpComputerName);
  237. USERENVAPI
  238. BOOL
  239. WINAPI
  240. DeleteProfileW (
  241.         IN LPCWSTR lpSidString,
  242.         IN LPCWSTR lpProfilePath,
  243.     IN LPCWSTR lpComputerName);
  244. #ifdef UNICODE
  245. #define DeleteProfile  DeleteProfileW
  246. #else
  247. #define DeleteProfile  DeleteProfileA
  248. #endif // !UNICODE
  249.  
  250. #endif /* WINVER >= 0x0500 */
  251.  
  252. //=============================================================================
  253. //
  254. // GetDefaultUserProfilesDirectory
  255. //
  256. // Returns the path to the root of the default user profile
  257. //
  258. // lpProfileDir   -  Receives the path
  259. // lpcchSize      -  Size of lpProfileDir
  260. //
  261. // Returns:  TRUE if successful
  262. //           FALSE if not.  Call GetLastError() for more details
  263. //
  264. // Note:     If lpProfileDir is not large enough, the function will fail,
  265. //           and lpcchSize will contain the necessary buffer size.
  266. //
  267. // Example return value: C:\Documents and Settings\Default User
  268. //
  269. //=============================================================================
  270.  
  271. #if(WINVER >= 0x0500)
  272.  
  273. USERENVAPI
  274. BOOL
  275. WINAPI
  276. GetDefaultUserProfileDirectoryA(
  277.     OUT LPSTR lpProfileDir,
  278.     IN OUT LPDWORD lpcchSize);
  279. USERENVAPI
  280. BOOL
  281. WINAPI
  282. GetDefaultUserProfileDirectoryW(
  283.     OUT LPWSTR lpProfileDir,
  284.     IN OUT LPDWORD lpcchSize);
  285. #ifdef UNICODE
  286. #define GetDefaultUserProfileDirectory  GetDefaultUserProfileDirectoryW
  287. #else
  288. #define GetDefaultUserProfileDirectory  GetDefaultUserProfileDirectoryA
  289. #endif // !UNICODE
  290.  
  291. #endif /* WINVER >= 0x0500 */
  292.  
  293. //=============================================================================
  294. //
  295. // GetAllUsersProfilesDirectory
  296. //
  297. // Returns the path to the root of the All Users profile
  298. //
  299. // lpProfileDir   -  Receives the path
  300. // lpcchSize      -  Size of lpProfileDir
  301. //
  302. // Returns:  TRUE if successful
  303. //           FALSE if not.  Call GetLastError() for more details
  304. //
  305. // Note:     If lpProfileDir is not large enough, the function will fail,
  306. //           and lpcchSize will contain the necessary buffer size.
  307. //
  308. // Example return value: C:\Documents and Settings\All Users
  309. //
  310. //=============================================================================
  311.  
  312. #if(WINVER >= 0x0500)
  313.  
  314. USERENVAPI
  315. BOOL
  316. WINAPI
  317. GetAllUsersProfileDirectoryA(
  318.     OUT LPSTR lpProfileDir,
  319.     IN OUT LPDWORD lpcchSize);
  320. USERENVAPI
  321. BOOL
  322. WINAPI
  323. GetAllUsersProfileDirectoryW(
  324.     OUT LPWSTR lpProfileDir,
  325.     IN OUT LPDWORD lpcchSize);
  326. #ifdef UNICODE
  327. #define GetAllUsersProfileDirectory  GetAllUsersProfileDirectoryW
  328. #else
  329. #define GetAllUsersProfileDirectory  GetAllUsersProfileDirectoryA
  330. #endif // !UNICODE
  331.  
  332. #endif /* WINVER >= 0x0500 */
  333.  
  334. //=============================================================================
  335. //
  336. // GetUserProfileDirectory
  337. //
  338. // Returns the path to the root of the requested user's profile
  339. //
  340. // hToken         -  User's token returned from LogonUser()
  341. // lpProfileDir   -  Receives the path
  342. // lpcchSize      -  Size of lpProfileDir
  343. //
  344. // Returns:  TRUE if successful
  345. //           FALSE if not.  Call GetLastError() for more details
  346. //
  347. // Note:     If lpProfileDir is not large enough, the function will fail,
  348. //           and lpcchSize will contain the necessary buffer size.
  349. //
  350. // Example return value: C:\Documents and Settings\Joe
  351. //
  352. //=============================================================================
  353.  
  354. USERENVAPI
  355. BOOL
  356. WINAPI
  357. GetUserProfileDirectoryA(
  358.     IN HANDLE  hToken,
  359.     OUT LPSTR lpProfileDir,
  360.     IN OUT LPDWORD lpcchSize);
  361. USERENVAPI
  362. BOOL
  363. WINAPI
  364. GetUserProfileDirectoryW(
  365.     IN HANDLE  hToken,
  366.     OUT LPWSTR lpProfileDir,
  367.     IN OUT LPDWORD lpcchSize);
  368. #ifdef UNICODE
  369. #define GetUserProfileDirectory  GetUserProfileDirectoryW
  370. #else
  371. #define GetUserProfileDirectory  GetUserProfileDirectoryA
  372. #endif // !UNICODE
  373.  
  374.  
  375. //=============================================================================
  376. //
  377. // CreateEnvironmentBlock
  378. //
  379. // Returns the environment variables for the specified user.  This block
  380. // can then be passed to CreateProcessAsUser().
  381. //
  382. // lpEnvironment  -  Receives a pointer to the new environment block
  383. // hToken         -  User's token returned from LogonUser() (optional, can be NULL)
  384. // bInherit       -  Inherit from the current process's environment block
  385. //                   or start from a clean state.
  386. //
  387. // Returns:  TRUE if successful
  388. //           FALSE if not.  Call GetLastError() for more details
  389. //
  390. // Note:     If hToken is NULL, the returned environment block will contain
  391. //           system variables only.
  392. //
  393. //           Call DestroyEnvironmentBlock to free the buffer when finished.
  394. //
  395. //           If this block is passed to CreateProcessAsUser, the
  396. //           CREATE_UNICODE_ENVIRONMENT flag must also be set.
  397. //
  398. //=============================================================================
  399.  
  400. USERENVAPI
  401. BOOL
  402. WINAPI
  403. CreateEnvironmentBlock(
  404.     OUT LPVOID *lpEnvironment,
  405.     IN HANDLE  hToken,
  406.     IN BOOL    bInherit);
  407.  
  408.  
  409. //=============================================================================
  410. //
  411. // DestroyEnvironmentBlock
  412. //
  413. // Frees environment variables created by CreateEnvironmentBlock
  414. //
  415. // lpEnvironment  -  A pointer to the environment block
  416. //
  417. // Returns:  TRUE if successful
  418. //           FALSE if not.  Call GetLastError() for more details
  419. //
  420. //=============================================================================
  421.  
  422. USERENVAPI
  423. BOOL
  424. WINAPI
  425. DestroyEnvironmentBlock(
  426.     IN LPVOID  lpEnvironment);
  427.  
  428.  
  429. //=============================================================================
  430. //
  431. // ExpandEnvironmentStringsForUser
  432. //
  433. // Expands the source string using the environment block for the
  434. // specified user.  If hToken is null, the system environment block
  435. // will be used (no user environment variables).
  436. //
  437. // hToken         -  User's token returned from LogonUser() (optional, can be NULL)
  438. // lpSrc          -  Pointer to the string with environment variables
  439. // lpDest         -  Buffer that receives the expanded string
  440. // dwSize         -  Size of lpDest in characters (max chars)
  441. //
  442. // Returns:  TRUE if successful
  443. //           FALSE if not.  Call GetLastError() for more details
  444. //
  445. // Note:     If the user profile for hToken is not loaded, this api will fail.
  446. //
  447. //=============================================================================
  448.  
  449. #if(WINVER >= 0x0500)
  450.  
  451. USERENVAPI
  452. BOOL
  453. WINAPI
  454. ExpandEnvironmentStringsForUserA(
  455.     IN HANDLE hToken,
  456.     IN LPCSTR lpSrc,
  457.     OUT LPSTR lpDest,
  458.     IN DWORD dwSize);
  459. USERENVAPI
  460. BOOL
  461. WINAPI
  462. ExpandEnvironmentStringsForUserW(
  463.     IN HANDLE hToken,
  464.     IN LPCWSTR lpSrc,
  465.     OUT LPWSTR lpDest,
  466.     IN DWORD dwSize);
  467. #ifdef UNICODE
  468. #define ExpandEnvironmentStringsForUser  ExpandEnvironmentStringsForUserW
  469. #else
  470. #define ExpandEnvironmentStringsForUser  ExpandEnvironmentStringsForUserA
  471. #endif // !UNICODE
  472.  
  473. #endif /* WINVER >= 0x0500 */
  474.  
  475. //=============================================================================
  476. //
  477. // RefreshPolicy()
  478. //
  479. // Causes group policy to be applied immediately on the client machine
  480. //
  481. // bMachine  -  Refresh machine or user policy
  482. //
  483. // Returns:  TRUE if successful
  484. //           FALSE if not.  Call GetLastError() for more details
  485. //
  486. //=============================================================================
  487.  
  488. #if(WINVER >= 0x0500)
  489.  
  490. USERENVAPI
  491. BOOL
  492. WINAPI
  493. RefreshPolicy(
  494.     IN BOOL bMachine);
  495.  
  496. #endif /* WINVER >= 0x0500 */
  497.  
  498. //=============================================================================
  499. //
  500. // EnterCriticalPolicySection
  501. //
  502. // Pauses the background application of group policy to allow safe
  503. // reading of the registry.  Applications that need to read multiple
  504. // policy entries and ensure that the values are not changed while reading
  505. // them should use this function.
  506. //
  507. // The maximum amount of time an application can hold a critical section
  508. // is 10 minutes.  After 10 minutes, policy can be applied again.
  509. //
  510. // bMachine -  Pause machine or user policy
  511. //
  512. // Returns:  Handle if successful
  513. //           NULL if not.  Call GetLastError() for more details
  514. //
  515. // Note 1:  The handle returned should be passed to LeaveCriticalPolicySection
  516. // when finished.  Do not close this handle, LeaveCriticalPolicySection
  517. // will do that.
  518. //
  519. // Note 2:  If both user and machine critical sections need to be acquired then
  520. // they should be done in this order: first acquire user critical section and
  521. // then acquire machine critical section.
  522. //
  523. //=============================================================================
  524.  
  525. #if(WINVER >= 0x0500)
  526.  
  527. USERENVAPI
  528. HANDLE
  529. WINAPI
  530. EnterCriticalPolicySection(
  531.     IN BOOL bMachine);
  532.  
  533. #endif /* WINVER >= 0x0500 */
  534.  
  535. //=============================================================================
  536. //
  537. // LeaveCriticalPolicySection
  538. //
  539. // Resumes the background application of group policy.  See
  540. // EnterCriticalPolicySection for more details.
  541. //
  542. // hSection - Handle returned from EnterCriticalPolicySection
  543. //
  544. // Returns:  TRUE if successful
  545. //           FALSE if not.  Call GetLastError() for more details
  546. //
  547. // Note:  This function will close the handle.
  548. //
  549. //=============================================================================
  550.  
  551. #if(WINVER >= 0x0500)
  552.  
  553. USERENVAPI
  554. BOOL
  555. WINAPI
  556. LeaveCriticalPolicySection(
  557.     IN HANDLE hSection);
  558.  
  559. #endif /* WINVER >= 0x0500 */
  560.  
  561. //=============================================================================
  562. //
  563. // RegisterGPNotification
  564. //
  565. // Entry point for registering for Group Policy change notification.
  566. //
  567. // Parameters: hEvent     -   Event to be notified, by calling SetEvent(hEvent)
  568. //             bMachine   -   If true, then register machine policy notification
  569. //                                     else register user policy notification
  570. //
  571. // Returns:    True if successful
  572. //             False if error occurs
  573. //
  574. // Notes:      Group Policy Notifications.  There are 2 ways an application can
  575. //             be notify when Group Policy is finished being applied.
  576. //
  577. //             1) Using the RegisterGPNotifcation function and waiting for the
  578. //                event to be signalled.
  579. //
  580. //             2) A WM_SETTINGCHANGE message is broadcast to all desktops.
  581. //                wParam - 1 if machine policy was applied, 0 if user policy was applied.
  582. //                lParam - Points to the string "Policy"
  583. //
  584. //=============================================================================
  585.  
  586. #if(WINVER >= 0x0500)
  587.  
  588. USERENVAPI
  589. BOOL
  590. WINAPI
  591. RegisterGPNotification(
  592.     IN HANDLE hEvent,
  593.     IN BOOL bMachine );
  594.  
  595. #endif /* WINVER >= 0x0500 */
  596.  
  597. //=============================================================================
  598. //
  599. // UnregisterGPNotification
  600. //
  601. // Removes registration for a Group Policy change notification.
  602. //
  603. // Parameters: hEvent    -   Event to be removed
  604. //
  605. // Returns:    True if successful
  606. //             False if error occurs
  607. //
  608. //=============================================================================
  609.  
  610. #if(WINVER >= 0x0500)
  611.  
  612. USERENVAPI
  613. BOOL
  614. WINAPI
  615. UnregisterGPNotification(
  616.     IN HANDLE hEvent );
  617.  
  618. #endif /* WINVER >= 0x0500 */
  619.  
  620. //=============================================================================
  621. //
  622. // GPOptions flags
  623. //
  624. // These are the flags found in the GPOptions property of a DS object
  625. //
  626. // For a given DS object (Site, Domain, OU), the GPOptions property
  627. // contains options that effect all the GPOs link to this SDOU.
  628. //
  629. // This is a DWORD type
  630. //
  631. //=============================================================================
  632.  
  633. #if(WINVER >= 0x0500)
  634.  
  635. #define GPC_BLOCK_POLICY        0x00000001  // Block all non-forced policy from above
  636.  
  637. #endif /* WINVER >= 0x0500 */
  638.  
  639. //=============================================================================
  640. //
  641. // GPLink flags
  642. //
  643. // These are the flags found on the GPLink property of a DS object after
  644. // the GPO path.
  645. //
  646. // For a given DS object (Site, Domain, OU), the GPLink property will
  647. // be in this text format
  648. //
  649. // [LDAP://CN={E615A0E3-C4F1-11D1-A3A7-00AA00615092},CN=Policies,CN=System,DC=ntdev,DC=Microsoft,DC=Com;1]
  650. //
  651. // The GUID is the GPO name, and the number following the LDAP path are the options
  652. // for that link from this DS object.  Note, there can be multiple GPOs
  653. // each in their own square brackets in a prioritized list.
  654. //
  655. //=============================================================================
  656.  
  657. #if(WINVER >= 0x0500)
  658.  
  659. //
  660. // Options for a GPO link
  661. //
  662.  
  663. #define GPO_FLAG_DISABLE        0x00000001  // This GPO is disabled
  664. #define GPO_FLAG_FORCE          0x00000002  // Don't override the settings in
  665.                                             // this GPO with settings from
  666.                                             // a GPO below it.
  667. #endif /* WINVER >= 0x0500 */
  668.  
  669. //=============================================================================
  670. //
  671. // GetGPOList
  672. //
  673. //
  674. // Queries for the list of Group Policy Objects for the specified
  675. // user or machine.  This function will return a link list
  676. // of Group Policy Objects.  Call FreeGPOList to free the list.
  677. //
  678. // Note, most applications will not need to call this function.
  679. // This will primarily be used by services acting on behalf of
  680. // another user or machine.  The caller of this function will
  681. // need to look in each GPO for their specific policy
  682. //
  683. // This function can be called two different ways.  Either the hToken for
  684. // a user or machine can be supplied and the correct name and domain
  685. // controller name will be generated, or hToken is NULL and the caller
  686. // must supply the name and the domain controller name.
  687. //
  688. // Calling this function with an hToken ensures the list of Group Policy
  689. // Objects is correct for the user or machine since security access checking
  690. // can be perfomed.  If hToken is not supplied, the security of the caller
  691. // is used instead which means that list may or may not be 100% correct
  692. // for the intended user / machine.  However, this is the fastest way
  693. // to call this function.
  694. //
  695. // hToken           - User or machine token, if NULL, lpName and lpHostName must be supplied
  696. // lpName           - User or machine name in DN format, if hToken is supplied, this must be NULL
  697. // lpHostName       - Domain DN name or domain controller name. If hToken is supplied, this must be NULL
  698. // lpComputerName   - Computer name to use to determine site location.  If NULL,
  699. //                    the local computer is used as the reference. Format:  \\machinename
  700. // dwFlags          - Flags field.  See flags definition below
  701. // pGPOList         - Address of a pointer which receives the link list of GPOs
  702. //
  703. //
  704. // Returns:  TRUE if successful
  705. //           FALSE if not.  Use GetLastError() for more details.
  706. //
  707. // Examples:
  708. //
  709. // Here's how this function will typically be called for
  710. // looking up the list of GPOs for a user:
  711. //
  712. //      LPGROUP_POLICY_OBJECT  pGPOList
  713. //
  714. //      if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
  715. //      {
  716. //          // do processing here...
  717. //          FreeGPOList (pGPOList)
  718. //      }
  719. //
  720. //
  721. // Here's how this function will typically be called for
  722. // looking up the list of GPOs for a machine:
  723. //
  724. //      LPGROUP_POLICY_OBJECT  pGPOList
  725. //
  726. //      if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName,
  727. //                      GPO_LIST_FLAG_MACHINE, &pGPOList))
  728. //      {
  729. //          // do processing here...
  730. //          FreeGPOList (pGPOList)
  731. //      }
  732. //
  733. //=============================================================================
  734.  
  735. #if(WINVER >= 0x0500)
  736.  
  737. //
  738. // Each Group Policy Object is associated (linked) with a site, domain,
  739. // organizational unit, or machine.
  740. //
  741.  
  742. typedef enum _GPO_LINK {
  743.     GPLinkUnknown = 0,                     // No link information available
  744.     GPLinkMachine,                         // GPO linked to a machine (local or remote)
  745.     GPLinkSite,                            // GPO linked to a site
  746.     GPLinkDomain,                          // GPO linked to a domain
  747.     GPLinkOrganizationalUnit               // GPO linked to a organizational unit
  748. } GPO_LINK, *PGPO_LINK;
  749.  
  750. typedef struct _GROUP_POLICY_OBJECTA {
  751.     DWORD       dwOptions;                  // See GPLink option flags above
  752.     DWORD       dwVersion;                  // Revision number of the GPO
  753.     LPSTR       lpDSPath;                   // Path to the Active Directory portion of the GPO
  754.     LPSTR       lpFileSysPath;              // Path to the file system portion of the GPO
  755.     LPSTR       lpDisplayName;              // Friendly display name
  756.     CHAR        szGPOName[50];              // Unique name
  757.     GPO_LINK    GPOLink;                    // Link information
  758.     LPARAM      lParam;                     // Free space for the caller to store GPO specific information
  759.     struct _GROUP_POLICY_OBJECTA * pNext;   // Next GPO in the list
  760.     struct _GROUP_POLICY_OBJECTA * pPrev;   // Previous GPO in the list
  761.     LPSTR       lpExtensions;               // Extensions that are relevant for this GPO
  762.     LPARAM      lParam2;                    // Free space for the caller to store GPO specific information
  763. } GROUP_POLICY_OBJECTA, *PGROUP_POLICY_OBJECTA;
  764. typedef struct _GROUP_POLICY_OBJECTW {
  765.     DWORD       dwOptions;                  // See GPLink option flags above
  766.     DWORD       dwVersion;                  // Revision number of the GPO
  767.     LPWSTR      lpDSPath;                   // Path to the Active Directory portion of the GPO
  768.     LPWSTR      lpFileSysPath;              // Path to the file system portion of the GPO
  769.     LPWSTR      lpDisplayName;              // Friendly display name
  770.     WCHAR       szGPOName[50];              // Unique name
  771.     GPO_LINK    GPOLink;                    // Link information
  772.     LPARAM      lParam;                     // Free space for the caller to store GPO specific information
  773.     struct _GROUP_POLICY_OBJECTW * pNext;   // Next GPO in the list
  774.     struct _GROUP_POLICY_OBJECTW * pPrev;   // Previous GPO in the list
  775.     LPWSTR      lpExtensions;               // Extensions that are relevant for this GPO
  776.     LPARAM      lParam2;                    // Free space for the caller to store GPO specific information
  777. } GROUP_POLICY_OBJECTW, *PGROUP_POLICY_OBJECTW;
  778. #ifdef UNICODE
  779. typedef GROUP_POLICY_OBJECTW GROUP_POLICY_OBJECT;
  780. typedef PGROUP_POLICY_OBJECTW PGROUP_POLICY_OBJECT;
  781. #else
  782. typedef GROUP_POLICY_OBJECTA GROUP_POLICY_OBJECT;
  783. typedef PGROUP_POLICY_OBJECTA PGROUP_POLICY_OBJECT;
  784. #endif // UNICODE
  785.  
  786.  
  787. //
  788. // dwFlags for GetGPOList()
  789. //
  790.  
  791. #define GPO_LIST_FLAG_MACHINE   0x00000001  // Return machine policy information
  792. #define GPO_LIST_FLAG_SITEONLY  0x00000002  // Return site policy information only
  793.  
  794.  
  795. USERENVAPI
  796. BOOL
  797. WINAPI
  798. GetGPOListA (
  799.     IN HANDLE hToken,
  800.     IN LPCSTR lpName,
  801.     IN LPCSTR lpHostName,
  802.     IN LPCSTR lpComputerName,
  803.     IN DWORD dwFlags,
  804.     OUT PGROUP_POLICY_OBJECTA *pGPOList);
  805. USERENVAPI
  806. BOOL
  807. WINAPI
  808. GetGPOListW (
  809.     IN HANDLE hToken,
  810.     IN LPCWSTR lpName,
  811.     IN LPCWSTR lpHostName,
  812.     IN LPCWSTR lpComputerName,
  813.     IN DWORD dwFlags,
  814.     OUT PGROUP_POLICY_OBJECTW *pGPOList);
  815. #ifdef UNICODE
  816. #define GetGPOList  GetGPOListW
  817. #else
  818. #define GetGPOList  GetGPOListA
  819. #endif // !UNICODE
  820.  
  821. #endif /* WINVER >= 0x0500 */
  822.  
  823. //=============================================================================
  824. //
  825. // FreeGPOList
  826. //
  827. //
  828. // Frees the link list returned from GetGPOList
  829. //
  830. // pGPOList - Pointer to the link list of GPOs
  831. //
  832. //
  833. // Returns:  TRUE if successful
  834. //           FALSE if not
  835. //
  836. //=============================================================================
  837.  
  838. #if(WINVER >= 0x0500)
  839.  
  840. USERENVAPI
  841. BOOL
  842. WINAPI
  843. FreeGPOListA (
  844.     IN PGROUP_POLICY_OBJECTA pGPOList);
  845. USERENVAPI
  846. BOOL
  847. WINAPI
  848. FreeGPOListW (
  849.     IN PGROUP_POLICY_OBJECTW pGPOList);
  850. #ifdef UNICODE
  851. #define FreeGPOList  FreeGPOListW
  852. #else
  853. #define FreeGPOList  FreeGPOListA
  854. #endif // !UNICODE
  855.  
  856. #endif /* WINVER >= 0x0500 */
  857.  
  858. //=============================================================================
  859. //
  860. // GetAppliedGPOList
  861. //
  862. // Queries for the list of applied Group Policy Objects for the specified
  863. // user or machine and specified client side extension. This function will return
  864. // a linked listof Group Policy Objects.  Call FreeGPOList to free the list.
  865. //
  866. // dwFlags          - User or machine policy, if it is GPO_LIST_FLAG_MACHINE then
  867. //                    return machine policy information
  868. // pMachineName     - Name of remote computer in the form \\computername. If null
  869. //                    then local computer is used.
  870. // pSidUser         - Security id of user (relevant for user policy). If pMachineName is
  871. //                    null and pSidUser is null then it means current logged on user.
  872. //                    If pMachine is null and pSidUser is non-null then it means user
  873. //                    represented by pSidUser on local machine. If pMachineName is non-null
  874. //                    then and if dwFlags specifies user policy, then pSidUser must be
  875. //                    non-null.
  876. // pGuidExtension   - Guid of the specified extension
  877. // ppGPOList        - Address of a pointer which receives the link list of GPOs
  878. //
  879. // The return value is a Win32 error code. ERROR_SUCCESS means the GetAppliedGPOList
  880. // function completed successfully. Otherwise it indicates that the function failed.
  881. //
  882. //=============================================================================
  883.  
  884. #if(WINVER >= 0x0500)
  885.  
  886. USERENVAPI
  887. DWORD
  888. WINAPI
  889. GetAppliedGPOListA (
  890.     IN DWORD dwFlags,
  891.     IN LPCSTR pMachineName,
  892.     IN PSID pSidUser,
  893.     IN GUID *pGuidExtension,
  894.     OUT PGROUP_POLICY_OBJECTA *ppGPOList);
  895. USERENVAPI
  896. DWORD
  897. WINAPI
  898. GetAppliedGPOListW (
  899.     IN DWORD dwFlags,
  900.     IN LPCWSTR pMachineName,
  901.     IN PSID pSidUser,
  902.     IN GUID *pGuidExtension,
  903.     OUT PGROUP_POLICY_OBJECTW *ppGPOList);
  904. #ifdef UNICODE
  905. #define GetAppliedGPOList  GetAppliedGPOListW
  906. #else
  907. #define GetAppliedGPOList  GetAppliedGPOListA
  908. #endif // !UNICODE
  909.  
  910. #endif /* WINVER >= 0x0500 */
  911.  
  912. //=============================================================================
  913. //
  914. // Group Policy Object client side extension support
  915. //
  916. // Flags, data structures and function prototype
  917. //
  918. // To register your extension, create a subkey under this key
  919. //
  920. // Software\Microsoft\Windows NT\CurrentVersion\Winlogon\GPExtensions
  921. //
  922. // The subkey needs to be a guid so that it is unique. The noname value of the subkey
  923. // can be the friendly name of the extension. Then add these values:
  924. //
  925. //     DllName                      REG_EXPAND_SZ  Path to your DLL
  926. //     ProcessGroupPolicy           REG_SZ       Function name (see PFNPROCESSGROUPPOLICY prototype)
  927. //     NoMachinePolicy              REG_DWORD    True, if extension does not have to be called when
  928. //                                                 machine policies are being processed.
  929. //     NoUserPolicy                 REG_DWORD    True, if extension does not have to be called when
  930. //                                                 user policies are being processed.
  931. //     NoSlowLink                   REG_DWORD    True, if extension does not have to be called on a slow link
  932. //     NoBackgroundPolicy           REG_DWORD    True, if extension does not have to be called on.
  933. //                                                 policies applied in background.
  934. //     NoGPOListChanges             REG_DWORD    True, if extension does not have to be called when
  935. //                                                 there are no changes between cached can current GPO lists.
  936. //     PerUserLocalSettings         REG_DWORD    True, if user policies have to be cached on a per user and
  937. //                                                 per machine basis.
  938. //     RequiresSuccessfulRegistry   REG_DWORD    True, if extension should be called only if registry extension
  939. //                                                 was successfully processed.
  940. //     EnableAsynchronousProcessing REG_DWORD    True, if registry extension will complete its processing
  941. //                                                 asynchronously.
  942. //     NotifyLinkTransition         REG_DWORD    True, if extension should be called when a change in link
  943. //                                                 speed is detected between previous policy application and
  944. //                                                 current policy application.
  945. //
  946. // The return value is a Win32 error code. ERROR_SUCCESS means the ProcessGroupPolicy
  947. // function completed successfully. If return value is ERROR_OVERRIDE_NOCHANGES then it
  948. // means that the extension will be called the next time even if NoGPOListChanges is set
  949. // and there are no changes to the GPO list. Any other return value indicates that the
  950. // ProcessGroupPolicy function failed.
  951. //
  952. //=============================================================================
  953.  
  954. #if(WINVER >= 0x0500)
  955.  
  956. #define GPO_INFO_FLAG_MACHINE          0x00000001  // Apply machine policy rather than user policy
  957. #define GPO_INFO_FLAG_BACKGROUND       0x00000010  // Background refresh of policy (ok to do slow stuff)
  958. #define GPO_INFO_FLAG_SLOWLINK         0x00000020  // Policy is being applied across a slow link
  959. #define GPO_INFO_FLAG_VERBOSE          0x00000040  // Verbose output to the eventlog
  960. #define GPO_INFO_FLAG_NOCHANGES        0x00000080  // No changes were detected to the Group Policy Objects
  961. #define GPO_INFO_FLAG_LINKTRANSITION   0x00000100  // A change in link speed was detected between previous policy
  962.                                                    // application and current policy application
  963.  
  964. typedef UINT_PTR ASYNCCOMPLETIONHANDLE;
  965. typedef DWORD (*PFNSTATUSMESSAGECALLBACK)(BOOL bVerbose, LPWSTR lpMessage);
  966.  
  967. typedef DWORD(*PFNPROCESSGROUPPOLICY)(
  968.     IN DWORD dwFlags,                              // GPO_INFO_FLAGS
  969.     IN HANDLE hToken,                              // User or machine token
  970.     IN HKEY hKeyRoot,                              // Root of registry
  971.     IN PGROUP_POLICY_OBJECT  pDeletedGPOList,      // Linked list of deleted GPOs
  972.     IN PGROUP_POLICY_OBJECT  pChangedGPOList,      // Linked list of changed GPOs
  973.     IN ASYNCCOMPLETIONHANDLE pHandle,              // For asynchronous completion
  974.     IN BOOL *pbAbort,                              // If true, then abort GPO processing
  975.     IN PFNSTATUSMESSAGECALLBACK pStatusCallback);  // Callback function for displaying status messages
  976.                                                    // Note, this can be NULL
  977.  
  978. //
  979. // GUID that identifies the registry extension
  980. //
  981.  
  982. #define REGISTRY_EXTENSION_GUID  { 0x35378EAC, 0x683F, 0x11D2, 0xA8, 0x9A, 0x00, 0xC0, 0x4F, 0xBB, 0xCF, 0xA2 }
  983.  
  984. #endif /* WINVER >= 0x0500 */
  985.  
  986. //=============================================================================
  987. //
  988. // Group Policy Object client side asynchronous extension processing
  989. //
  990. // extensionId    - Unique guid identifying the extension
  991. // pAsyncHandle   - Asynchronous completion handle that was passed to extension in
  992. //                  ProcessGroupPolicy call
  993. // dwStatus       - Completion status of asynchronous processing
  994. //
  995. // The return value is a Win32 error code. ERROR_SUCCESS means the ProcessGroupPolicyCompleted
  996. // function completed successfully. Otherwise it indicates that the function failed.
  997. //
  998. //=============================================================================
  999.  
  1000. #if(WINVER >= 0x0500)
  1001.  
  1002. typedef GUID *REFGPEXTENSIONID;
  1003.  
  1004. USERENVAPI
  1005. DWORD
  1006. WINAPI
  1007. ProcessGroupPolicyCompleted(
  1008.     IN REFGPEXTENSIONID extensionId,
  1009.     IN ASYNCCOMPLETIONHANDLE pAsyncHandle,
  1010.     IN DWORD dwStatus);
  1011.  
  1012. #endif /* WINVER >= 0x0500 */
  1013.  
  1014.  
  1015. #ifdef __cplusplus
  1016. }
  1017. #endif
  1018.  
  1019.  
  1020. #pragma option pop /*P_O_Pop*/
  1021. #endif // _INC_USERENV
  1022.