home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / dskquota.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-25  |  74.0 KB  |  2,000 lines
  1. /************************************************************************
  2. *                                                                       *
  3. *   dskquota.h --  public header for Windows NT disk quota interfaces.  *
  4. *                                                                       *
  5. *   Copyright 1991-1998, Microsoft Corp. All rights reserved.       *
  6. *                                                                       *
  7. ************************************************************************/
  8. #ifndef __DSKQUOTA_H
  9. #define __DSKQUOTA_H
  10.  
  11. //
  12. // This is the public header for the Windows NT disk quota control 
  13. // COM library.  The interfaces are implemented in DSKQUOTA.DLL.
  14. //
  15. // Define the INITGUIDS macros in one source module (and only one source
  16. // module) before including this header.  This will generate a single 
  17. // definition for the GUIDs used by the library.
  18. //
  19. // DSKQUOTA.DLL is self-registering using REGSVR32.
  20. //
  21. //
  22. // Interfaces -----------------------------------------------------------------
  23. //
  24. //      IDiskQuotaControl
  25. //
  26. //          Represents an NTFS volume for purposes of managing disk quota.
  27. //          Instantiate this interface for each volume to be controlled.
  28. //          Through it you can:
  29. //              * Enable/Disable disk quotas.
  30. //              * Obtain status of quota system on the volume.
  31. //              * Deny disk space to users exceding their quota limit.
  32. //              * Assign default warning threshold and quota limit values
  33. //                to be used for new volume users.
  34. //              * Locate a single user quota entry.
  35. //              * Mark a user quota entry for deletion.
  36. //              * Create an enumeration object for enumerating user quota
  37. //                entries.
  38. //              * Create a batch object for updating multiple user quota
  39. //                entries efficiently.
  40. //
  41. //      IDiskQuotaUser
  42. //
  43. //          Represents a user quota entry on the volume.
  44. //          Instantiated through IEnumDiskQuotaUsers, 
  45. //              IDiskQuotaControl::FindUserSid or 
  46. //              IDiskQuotaControl::FindUserName or
  47. //              IDiskQuotaControl::AddUser
  48. //
  49. //          Through it you can:
  50. //              * Set/Retrieve the user's quota warning threshold and quota
  51. //                limit.
  52. //              * Retrieve the user's quota amount "used" value.
  53. //              * Retrieve the user's domain, account and friendly name.
  54. //              * Retrieve the user's security ID (SID).
  55. //
  56. //      IEnumDiskQuotaUsers
  57. //
  58. //          Enumerates user quota entries on the volume.  Implements the
  59. //          standard OLE IEnumXXXX interface.
  60. //          Instantiated through IDiskQuotaControl::CreateEnumUsers.
  61. //
  62. //      IDiskQuotaUserBatch
  63. //
  64. //          Coordinates the update of multiple user quota entries into
  65. //          a single call to NTFS.  Improves update efficiency when 
  66. //          multiple entries must be updated.
  67. //          Instantiated through IDiskQuotaControl::CreateUserBatch.
  68. //
  69. //      IDiskQuotaEvents
  70. //
  71. //          The DiskQuotaControl object services this interface as
  72. //          an OLE connection point.  The connection point is used to
  73. //          notify client code when a significant event has occured in
  74. //          the quota system.  Currently, the only event supported is
  75. //          the asynchronous update of a quota user object's name 
  76. //          information.
  77. //
  78. // Interfaces [end] -----------------------------------------------------------
  79. //          
  80. //
  81. #ifndef _WINDOWS_
  82. #include <windows.h>
  83. #endif
  84.  
  85. #ifndef _OLE2_H_
  86. #include <ole2.h>
  87. #endif
  88.  
  89. #ifndef _OLECTL_H_
  90. #include <olectl.h>
  91. #endif
  92.  
  93. #ifdef INITGUIDS
  94. #include <initguid.h>
  95. #endif
  96.  
  97.  
  98. //
  99. // Class IDs
  100. //
  101. // {7988B571-EC89-11cf-9C00-00AA00A14F56}
  102. DEFINE_GUID(CLSID_DiskQuotaControl, 
  103. 0x7988b571, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  104.  
  105. //
  106. // Interface IDs
  107. //
  108. // {7988B572-EC89-11cf-9C00-00AA00A14F56}
  109. DEFINE_GUID(IID_IDiskQuotaControl, 
  110. 0x7988b572, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  111.  
  112. // {7988B574-EC89-11cf-9C00-00AA00A14F56}
  113. DEFINE_GUID(IID_IDiskQuotaUser, 
  114. 0x7988b574, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  115.  
  116. // {7988B576-EC89-11cf-9C00-00AA00A14F56}
  117. DEFINE_GUID(IID_IDiskQuotaUserBatch, 
  118. 0x7988b576, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  119.  
  120. // {7988B577-EC89-11cf-9C00-00AA00A14F56}
  121. DEFINE_GUID(IID_IEnumDiskQuotaUsers, 
  122. 0x7988b577, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  123.  
  124. // {7988B579-EC89-11cf-9C00-00AA00A14F56}
  125. DEFINE_GUID(IID_IDiskQuotaEvents, 
  126. 0x7988b579, 0xec89, 0x11cf, 0x9c, 0x0, 0x0, 0xaa, 0x0, 0xa1, 0x4f, 0x56);
  127.  
  128.  
  129. //
  130. // Definitions for value and bits in DWORD returned by GetQuotaState().
  131. //
  132. #define DISKQUOTA_STATE_DISABLED            0x00000000
  133. #define DISKQUOTA_STATE_TRACK               0x00000001
  134. #define DISKQUOTA_STATE_ENFORCE             0x00000002
  135. #define DISKQUOTA_STATE_MASK                0x00000003
  136. #define DISKQUOTA_FILESTATE_INCOMPLETE      0x00000100
  137. #define DISKQUOTA_FILESTATE_REBUILDING      0x00000200
  138. #define DISKQUOTA_FILESTATE_MASK            0x00000300
  139.  
  140. //
  141. // Helper macros for setting and testing state value.
  142. //
  143. #define DISKQUOTA_SET_DISABLED(s) \
  144.             ((s) &= ~DISKQUOTA_STATE_MASK)
  145.  
  146. #define DISKQUOTA_SET_TRACKED(s) \
  147.             ((s) |= (DISKQUOTA_STATE_MASK & DISKQUOTA_STATE_TRACK))
  148.  
  149. #define DISKQUOTA_SET_ENFORCED(s) \
  150.             ((s) |= (DISKQUOTA_STATE_ENFORCE & DISKQUOTA_STATE_ENFORCE))
  151.  
  152. #define DISKQUOTA_IS_DISABLED(s) \
  153.             (DISKQUOTA_STATE_DISABLED == ((s) & DISKQUOTA_STATE_MASK))
  154.  
  155. #define DISKQUOTA_IS_TRACKED(s) \
  156.             (DISKQUOTA_STATE_TRACK == ((s) & DISKQUOTA_STATE_MASK))
  157.  
  158. #define DISKQUOTA_IS_ENFORCED(s) \
  159.             (DISKQUOTA_STATE_ENFORCE == ((s) & DISKQUOTA_STATE_MASK))
  160. //
  161. // These file state flags are read-only.
  162. //
  163. #define DISKQUOTA_FILE_INCOMPLETE(s) \
  164.             (0 != ((s) & DISKQUOTA_FILESTATE_INCOMPLETE))
  165.  
  166. #define DISKQUOTA_FILE_REBUILDING(s) \
  167.             (0 != ((s) & DISKQUOTA_FILESTATE_REBUILDING))
  168.  
  169.  
  170. //
  171. // Definitions for bits in DWORD returned by GetQuotaLogFlags().
  172. //
  173. #define DISKQUOTA_LOGFLAG_USER_THRESHOLD    0x00000001
  174. #define DISKQUOTA_LOGFLAG_USER_LIMIT        0x00000002
  175.  
  176. //
  177. // Helper macros to interrogate a log flags DWORD.
  178. //
  179. #define DISKQUOTA_IS_LOGGED_USER_THRESHOLD(f) \
  180.             (0 != ((f) & DISKQUOTA_LOGFLAG_USER_THRESHOLD))
  181.  
  182. #define DISKQUOTA_IS_LOGGED_USER_LIMIT(f) \
  183.             (0 != ((f) & DISKQUOTA_LOGFLAG_USER_LIMIT))
  184.  
  185. //
  186. // Helper macros to set/clear bits in a log flags DWORD.
  187. //
  188. #define DISKQUOTA_SET_LOG_USER_THRESHOLD(f,yn) \
  189.               ((f &= ~DISKQUOTA_LOGFLAG_USER_THRESHOLD) |= ((yn) ? DISKQUOTA_LOGFLAG_USER_THRESHOLD : 0))
  190.  
  191. #define DISKQUOTA_SET_LOG_USER_LIMIT(f,yn) \
  192.               ((f &= ~DISKQUOTA_LOGFLAG_USER_LIMIT) |= ((yn) ? DISKQUOTA_LOGFLAG_USER_LIMIT : 0))
  193.  
  194. //
  195. // Per-user quota information.
  196. //
  197. typedef struct DiskQuotaUserInformation {    
  198.     LONGLONG QuotaUsed;
  199.     LONGLONG QuotaThreshold;
  200.     LONGLONG QuotaLimit;
  201. } DISKQUOTA_USER_INFORMATION, *PDISKQUOTA_USER_INFORMATION;
  202.  
  203.  
  204. //
  205. // Values for fNameResolution argument to:
  206. //
  207. //      IDiskQuotaControl::AddUser
  208. //      IDiskQuotaControl::FindUserSid
  209. //      IDiskQuotaControl::CreateEnumUsers
  210. //
  211. #define DISKQUOTA_USERNAME_RESOLVE_NONE     0
  212. #define DISKQUOTA_USERNAME_RESOLVE_SYNC     1
  213. #define DISKQUOTA_USERNAME_RESOLVE_ASYNC    2
  214.  
  215. //
  216. // Values for status returned by IDiskQuotaUser::GetAccountStatus.
  217. //
  218. #define DISKQUOTA_USER_ACCOUNT_RESOLVED     0
  219. #define DISKQUOTA_USER_ACCOUNT_UNAVAILABLE  1
  220. #define DISKQUOTA_USER_ACCOUNT_DELETED      2
  221. #define DISKQUOTA_USER_ACCOUNT_INVALID      3
  222. #define DISKQUOTA_USER_ACCOUNT_UNKNOWN      4
  223. #define DISKQUOTA_USER_ACCOUNT_UNRESOLVED   5
  224.  
  225.  
  226. ///////////////////////////////////////////////////////////////////////////////
  227. // IDiskQuotaUser interface
  228. //
  229. // This interface represents a single user entry in the volume's quota
  230. // information file.  Through this interface, you can query and modify
  231. // user-specific quota information on an NTFS volume.  An IDiskQuotaUser 
  232. // interface is instantiated through IEnumDiskQuotaUsers, 
  233. // IDiskQuotaControl::FindUserSid, IDiskQuotaControl::FindUserName or
  234. // IDiskQuotaControl::AddUser.
  235. //
  236. // IDiskQuotaUser::GetName ----------------------------------------------------
  237. //
  238. //      Retrieves the various name strings associated with a disk quota user.
  239. //
  240. //      Arguments:
  241. //
  242. //          pszDomain - Address of buffer to receive the name of the user's 
  243. //              network domain.  May be NULL.
  244. //
  245. //          cchDomain - Size of domain name buffer in characters.  Ignored if
  246. //              pszDomain is NULL.
  247. //
  248. //          pszName - Address of buffer to receive the name of the user's
  249. //              account in the network domain.  May be NULL.
  250. //
  251. //          cchName - Size of the name buffer in characters.  Ignored if pszName
  252. //              is NULL.
  253. //
  254. //          pszFullName - Address of buffer to receive the "full" name for
  255. //              the quota user.  The "full" name is the friendly name 
  256. //              associated with the user's account.  For example, user 
  257. //              John Doe might have an account name of "jdoe" while his
  258. //              "full" name is the string "John Doe".  May be NULL.
  259. //
  260. //          cchFullName - Size of the "full name" buffer in characters.  Ignored
  261. //              if pszFullName is NULL.
  262. //
  263. //      Returns:
  264. //          NOERROR           - Success.
  265. //          DQC_E_LOCK_FAILED - Could not gain exclusive lock on user object.
  266. //
  267. //
  268. // IDiskQuotaUser::GetSidLength -----------------------------------------------
  269. //
  270. //      Retrieves the length of the user's security ID (SID) in bytes.  The
  271. //      return value is used to size the destination buffer passed to
  272. //      IDiskQuotaUser::GetSid.
  273. //
  274. //      Arguments:
  275. //
  276. //          pdwLength - Address of DWORD variable to receive SID length.
  277. //
  278. //      Returns:
  279. //
  280. //          NOERROR           - Success.
  281. //          E_POINTER         - pdwLength argument is NULL.
  282. //          DQC_E_INVALID_SID - User's SID is invalid.
  283. //          DQC_E_LOCK_FAILED - Could not gain exclusive lock on user object.
  284. //          
  285. //
  286. // IDiskQuotaUser::GetSid -----------------------------------------------------
  287. //
  288. //      Retrieves the user's security ID (SID).
  289. //
  290. //      Arguments:
  291. //
  292. //          pbSidBuffer - Address of destination buffer to receive SID.
  293. //
  294. //          cbSidBuffer - Size of destination buffer in bytes.
  295. //
  296. //      Returns:
  297. //
  298. //          NOERROR                   - Success.
  299. //          E_POINTER                 - pbSidBuffer is NULL.
  300. //          DQC_E_INVALID_SID         - Quota entry SID is invalid.
  301. //          DQC_E_INSUFFICIENT_BUFFER - Insufficient destination buffer size.
  302. //          DQC_E_LOCK_FAILED         - Couldn't lock user object.
  303. //          
  304. //
  305. // IDiskQuotaUser::GetQuotaThreshold ------------------------------------------
  306. //
  307. //      Retrieves the user's quota "threshold" value on the volume.  The
  308. //      threshold is an arbitrary value set by the volume's quota 
  309. //      administrator.  It may be used to identify users who are approaching
  310. //      their quota limit.
  311. //
  312. //      Arguments:
  313. //
  314. //          pllThreshold - Address of LONGLONG variable to receive the 
  315. //              threshold value.
  316. //
  317. //      Returns:
  318. //
  319. //          NOERROR             - Success.
  320. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  321. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  322. //          E_POINTER           - pllThreshold is NULL.
  323. //          E_OUTOFMEMORY       - Insufficient memory.
  324. //          E_FAIL              - Failed reading quota information.
  325. //          
  326. //
  327. // IDiskQuotaUser::GetQuotaThresholdText --------------------------------------
  328. //
  329. //      Retrieves the user's quota "threshold" value expressed as a text
  330. //      string (i.e. "10.5 MB").  If the user's threshold is unlimited,
  331. //      the string "No Limit" is returned (localized).
  332. //
  333. //      Arguments:
  334. //
  335. //          pszText - Address of character buffer to receive text.
  336. //
  337. //          cchText - Size of destination buffer in bytes.
  338. //
  339. //      Returns:
  340. //
  341. //          NOERROR             - Success.
  342. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  343. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  344. //          E_OUTOFMEMORY       - Insufficient memory.
  345. //          E_FAIL              - Failed reading quota information.
  346. //
  347. //
  348. // IDiskQuotaUser::GetQuotaLimit ----------------------------------------------
  349. //
  350. //      Retrieves the user's quota "limit" value on the volume.  The
  351. //      limit is set as the maximum amount of disk space available to the
  352. //      volume user.  There are two special-case values associated with the
  353. //      quota limit.
  354. //
  355. //          -1 = User has unlimited quota on the volume.
  356. //          -2 = User's quota entry is marked for deletion.  If the entry's
  357. //               value for quota "used" is 0, the record will be deleted by
  358. //               NTFS at some future time.
  359. //
  360. //      Arguments:
  361. //
  362. //          pllLimit - Address of LONGLONG variable to receive the limit value.
  363. //
  364. //      Returns:
  365. //
  366. //          NOERROR             - Success.
  367. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  368. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  369. //          E_POINTER           - pllLimit is NULL.
  370. //          E_OUTOFMEMORY       - Insufficient memory.
  371. //          E_FAIL              - Failed reading quota information.
  372. //          
  373. //
  374. // IDiskQuotaUser::GetQuotaLimitText ------------------------------------------
  375. //
  376. //      Retrieves the user's quota "limit" value expressed as a text
  377. //      string (i.e. "10.5 MB").  If the user's limit is unlimited,
  378. //      the string "No Limit" is returned (localized).
  379. //
  380. //      Arguments:
  381. //
  382. //          pszText - Address of character buffer to receive text.
  383. //
  384. //          cchText - Size of destination buffer in bytes.
  385. //
  386. //      Returns:
  387. //
  388. //          NOERROR             - Success.
  389. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  390. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  391. //          E_OUTOFMEMORY       - Insufficient memory.
  392. //          E_FAIL              - Failed reading quota information.
  393. //
  394. //
  395. // IDiskQuotaUser::GetQuotaUsed -----------------------------------------------
  396. //
  397. //      Retrieves the user's quota "used" value on the volume.  This is the
  398. //      amount of information stored on the volume by the user.  Note that
  399. //      this is the amount of uncompressed information.  Therefore, the 
  400. //      use of NTFS compression does not affect this value.
  401. //
  402. //      Arguments:
  403. //
  404. //          pllUsed - Address of LONGLONG variable to receive the 
  405. //              quota used value.
  406. //
  407. //      Returns:
  408. //
  409. //          NOERROR             - Success.
  410. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  411. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  412. //          E_POINTER           - pllUsed is NULL.
  413. //          E_OUTOFMEMORY       - Insufficient memory.
  414. //          E_FAIL              - Failed reading quota information.
  415. //          
  416. //
  417. // IDiskQuotaUser::GetQuotaUsedText -------------------------------------------
  418. //
  419. //      Retrieves the user's quota "used" value expressed as a text
  420. //      string (i.e. "10.5 MB").
  421. //
  422. //      Arguments:
  423. //
  424. //          pszText - Address of character buffer to receive text.
  425. //
  426. //          cchText - Size of destination buffer in bytes.
  427. //
  428. //      Returns:
  429. //
  430. //          NOERROR             - Success.
  431. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  432. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  433. //          E_OUTOFMEMORY       - Insufficient memory.
  434. //          E_FAIL              - Failed reading quota information.
  435. //
  436. //
  437. // IDiskQuotaUser::GetQuotaInformation ----------------------------------------
  438. //
  439. //      Retrieves the user's quota "threshold", "used" and "limit" values in 
  440. //      a single function call.
  441. //
  442. //      Arguments:
  443. //
  444. //          pQuotaInfo - Address of DISKQUOTA_USER_INFORMATION structure to 
  445. //              receive the quota information.
  446. //
  447. //          cbQuotaInfo - Size of the desination buffer in bytes.
  448. //
  449. //      Returns:
  450. //
  451. //          NOERROR             - Success.
  452. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  453. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  454. //          E_POINTER           - pQuotaInfo is NULL.
  455. //          E_OUTOFMEMORY       - Insufficient memory.
  456. //          E_FAIL              - Failed reading quota information.
  457. //          
  458. //
  459. // IDiskQuotaUser::SetQuotaThreshold ------------------------------------------
  460. //
  461. //      Sets the user's quota "threshold" value on the volume.  The
  462. //      threshold is an arbitrary value set by the volume's quota 
  463. //      administrator.  It may be used to identify users who are approaching
  464. //      their quota limit.
  465. //
  466. //      Arguments:
  467. //
  468. //          llThreshold - Threshold value.
  469. //
  470. //          fWriteThrough - Set this to TRUE if you want to immediately write
  471. //              the value to the volume's quota file.  Otherwise, the value
  472. //              is only written to the quota user object's local memory.
  473. //              This value should normally be set to TRUE.  Set it to FALSE 
  474. //              when using the IDiskQuotaUserBatch interface to modify 
  475. //              multiple user quota entries at once.
  476. //
  477. //      Returns:
  478. //
  479. //          NOERROR             - Success.
  480. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  481. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  482. //          E_FAIL              - Failed writing quota information.
  483. //          
  484. //
  485. // IDiskQuotaUser::SetQuotaLimit ----------------------------------------------
  486. //
  487. //      Sets the user's quota "limit" value on the volume.  The
  488. //      limit is set as the maximum amount of disk space available to the
  489. //      volume user.  
  490. //
  491. //      Arguments:
  492. //
  493. //          llLimit - Limit value (bytes).  -1 = Unlimitd quota.
  494. //
  495. //          fWriteThrough - Set this to TRUE if you want to immediately write
  496. //              the value to the volume's quota file.  Otherwise, the value
  497. //              is only written to the quota user object's local memory.
  498. //              This value should normally be set to TRUE.  Set it to FALSE 
  499. //              when using the IDiskQuotaUserBatch interface to modify 
  500. //              multiple user quota entries at once.
  501. //
  502. //      Returns:
  503. //
  504. //          NOERROR             - Success.
  505. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  506. //          DQC_E_LOCK_FAILED   - Couldn't lock user object.
  507. //          E_FAIL              - Failed writing quota information.
  508. //          
  509. //
  510. // IDiskQuotaUser::Invalidate -------------------------------------------------
  511. //
  512. //      Invalidates the quota information stored in the quota user object.
  513. //      The next time information is requested, it is refreshed from disk.
  514. //
  515. //      Arguments: None.
  516. //
  517. //      Returns:   NOERROR.
  518. //          
  519. //
  520. // IDiskQuotaUser::GetAccountStatus -------------------------------------------
  521. //
  522. //      Retrieves the status of the user object's account.  User information
  523. //      is identified in the quota system by user security ID (SID).  This
  524. //      SID must be resolved to a user account for the user's domain,
  525. //      account name or full name to be retrieved.  This status information
  526. //      may be used to determine why a user's name string(s) are not available.
  527. //
  528. //      Arguments:
  529. //
  530. //          pdwStatus - Address of DWORD variable to receive user's account
  531. //              status.  The status value may be one of the following:
  532. //
  533. //              DISKQUOTA_USER_ACCOUNT_RESOLVED - SID has been resolved to
  534. //                  a user account.  Names are available through GetName().
  535. //
  536. //              DISKQUOTA_USER_ACCOUNT_UNAVAILABLE - User's account is 
  537. //                  unavailable at this time.  Network domain controller
  538. //                  may not be available.  Name information will not be
  539. //                  available.
  540. //
  541. //              DISKQUOTA_USER_ACCOUNT_DELETED - User's account has been
  542. //                  deleted from the domain.  Name information will not be
  543. //                  available.
  544. //
  545. //              DISKQUOTA_USER_ACCOUNT_INVALID - User's account is invalid.
  546. //                  Name information will not be available.
  547. //
  548. //              DISKQUOTA_USER_ACCOUNT_UNKNOWN - User's account is unknown.
  549. //                  Name information will not be available.
  550. //
  551. //              DISKQUOTA_USER_ACCOUNT_UNRESOLVED - SID has yet to be resolved
  552. //                  to a user account.  
  553. //
  554. //
  555. //      Returns:   NOERROR   - Success.
  556. //                 E_POINTER - pdwStatus argument is NULL.
  557. //
  558. ///////////////////////////////////////////////////////////////////////////////
  559. #undef  INTERFACE
  560. #define INTERFACE IDiskQuotaUser
  561.  
  562. DECLARE_INTERFACE_(IDiskQuotaUser, IUnknown)
  563. {
  564.     STDMETHOD(GetName)(THIS_ 
  565.         LPWSTR pszDomain, 
  566.         DWORD cchDomain, 
  567.         LPWSTR pszName, 
  568.         DWORD cchName, 
  569.         LPWSTR pszFullName, 
  570.         DWORD cchFullName) PURE;
  571.  
  572.     STDMETHOD(GetSidLength)(THIS_ 
  573.         LPDWORD pdwLength) PURE;
  574.  
  575.     STDMETHOD(GetSid)(THIS_ 
  576.         LPBYTE pbSidBuffer, 
  577.         DWORD cbSidBuffer) PURE;
  578.  
  579.     STDMETHOD(GetQuotaThreshold)(THIS_ 
  580.         PLONGLONG pllThreshold) PURE;
  581.  
  582.     STDMETHOD(GetQuotaThresholdText)(THIS_
  583.         LPWSTR pszText,
  584.         DWORD cchText) PURE;
  585.  
  586.     STDMETHOD(GetQuotaLimit)(THIS_ 
  587.         PLONGLONG pllLimit) PURE;
  588.  
  589.     STDMETHOD(GetQuotaLimitText)(THIS_
  590.         LPWSTR pszText,
  591.         DWORD cchText) PURE;
  592.  
  593.     STDMETHOD(GetQuotaUsed)(THIS_ 
  594.         PLONGLONG pllUsed) PURE;
  595.  
  596.     STDMETHOD(GetQuotaUsedText)(THIS_
  597.         LPWSTR pszText,
  598.         DWORD cchText) PURE;
  599.  
  600.     STDMETHOD(GetQuotaInformation)(THIS_ 
  601.         LPVOID pbQuotaInfo, 
  602.         DWORD cbQuotaInfo) PURE;
  603.  
  604.     STDMETHOD(SetQuotaThreshold)(THIS_ 
  605.         LONGLONG llThreshold,
  606.         BOOL fWriteThrough) PURE;
  607.  
  608.     STDMETHOD(SetQuotaLimit)(THIS_ 
  609.         LONGLONG llLimit,
  610.         BOOL fWriteThrough) PURE;
  611.  
  612.     STDMETHOD(Invalidate)(THIS) PURE;
  613.  
  614.     STDMETHOD(GetAccountStatus)(THIS_ 
  615.         LPDWORD pdwStatus) PURE;
  616. };
  617.  
  618. typedef IDiskQuotaUser DISKQUOTA_USER, *PDISKQUOTA_USER;
  619.  
  620.  
  621. ///////////////////////////////////////////////////////////////////////////////
  622. // IEnumDiskQuotaUsers interface
  623. //
  624. // Implementation of a standard OLE IEnumXXXX interface for enumerating 
  625. // IDiskQuotaUser objects.  IEnumDiskQuotaUsers is instantiated 
  626. // with IDiskQuotaControl::CreateEnumUsers.
  627. //
  628. // For a description of argument and return values, see the OLE documentation 
  629. // for IEnumXXXX.
  630. //
  631. ///////////////////////////////////////////////////////////////////////////////
  632. #undef  INTERFACE
  633. #define INTERFACE IEnumDiskQuotaUsers
  634.  
  635. DECLARE_INTERFACE_(IEnumDiskQuotaUsers, IUnknown)
  636. {
  637.     STDMETHOD(Next)(THIS_ 
  638.         DWORD cUsers, 
  639.         PDISKQUOTA_USER *rgUsers, 
  640.         LPDWORD pcUsersFetched) PURE;
  641.  
  642.     STDMETHOD(Skip)(THIS_ 
  643.         DWORD cUsers) PURE;
  644.  
  645.     STDMETHOD(Reset)(THIS) PURE;
  646.  
  647.     STDMETHOD(Clone)(THIS_ 
  648.         IEnumDiskQuotaUsers **ppEnum) PURE;
  649. };
  650.  
  651. typedef IEnumDiskQuotaUsers ENUM_DISKQUOTA_USERS, *PENUM_DISKQUOTA_USERS;
  652.  
  653.  
  654.  
  655. ///////////////////////////////////////////////////////////////////////////////
  656. // IDiskQuotaUserBatch interface
  657. //
  658. // This interface provides a mechanism for optimizing updates of quota
  659. // information on multiple users.  Through this interface, you can add quota
  660. // user objects to a container that is then submitted for update in a single
  661. // call.  This reduces the number of calls to the underlying file system
  662. // providing optimal performance when large numbers of user objects must
  663. // be updated.
  664. //
  665. // IDiskQuotaUserBatch::Add ---------------------------------------------------
  666. //
  667. //      Adds an IDiskQuotaUser pointer to the batch list.  When setting values
  668. //      on a quota user object in preparation for batch processing, specify
  669. //      FALSE for the fWriteThrough flag in the SetQuotaLimit and
  670. //      SetQuotaThreshold functions.  This will store the values in memory
  671. //      without writing through to disk.  Calling FlushToDisk will write the
  672. //      changes to disk.
  673. //      This function calls AddRef() on the pUser interface pointer.
  674. //      Release() is automatically called on each contained IDiskQuotaUser 
  675. //      interface pointer when the batch object is destroyed.
  676. //
  677. //      Arguments:
  678. //
  679. //          pUser - Address of quota user object's IDiskQuotaUser interface.
  680. //
  681. //      Returns:
  682. //
  683. //          NOERROR        - Success.
  684. //          E_POINTER      - pUser arg is NULL. 
  685. //          E_OUTOFMEMORY  - Insufficient memory.
  686. //          E_UNEXPECTED   - Unexpected exception occured.
  687. //          
  688. //
  689. // IDiskQuotaUserBatch::Remove ------------------------------------------------
  690. //
  691. //      Removes an IDiskQuotaUser pointer from the batch list.
  692. //
  693. //      Arguments:
  694. //
  695. //          pUser - Address of quota user object's IDiskQuotaUser interface.
  696. //
  697. //      Returns:
  698. //
  699. //          NOERROR       - Success.
  700. //          S_FALSE       - Quota user object not found in batch.
  701. //          E_POINTER     - pUser arg is NULL. 
  702. //          E_UNEXPECTED  - An unexpected exception occured.
  703. //
  704. //
  705. // IDiskQuotaUserBatch::RemoveAll ---------------------------------------------
  706. //
  707. //      Removes all IDiskQuotaUser pointers from the batch list.
  708. //
  709. //      Arguments: None.
  710. //
  711. //      Returns:
  712. //
  713. //          NOERROR      - Success.
  714. //          E_UNEXPECTED - An unexpected exception occured.
  715. //
  716. //
  717. // IDiskQuotaUserBatch::FlushToDisk -------------------------------------------
  718. //
  719. //      Writes user object changes to disk in a single call to NTFS.
  720. //
  721. //      Note that there are limitations as to how much information can be
  722. //      written to disk in a single call to the file system.  The flush 
  723. //      operation may require multiple calls to NTFS.  Nonetheless, it will
  724. //      be much more efficient than a single call for each user object.
  725. //
  726. //      Arguments: None.
  727. //
  728. //      Returns:
  729. //
  730. //          NOERROR             - Success.
  731. //          E_FAIL              - Error writing quota information.
  732. //          E_OUTOFMEMORY       - Insufficient memory.
  733. //          E_UNEXPECTED        - An unexpected exception occured.
  734. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  735. //
  736. ///////////////////////////////////////////////////////////////////////////////
  737. #undef  INTERFACE
  738. #define INTERFACE IDiskQuotaUserBatch
  739.  
  740. DECLARE_INTERFACE_(IDiskQuotaUserBatch, IUnknown)
  741. {
  742.     STDMETHOD(Add)(THIS_ 
  743.         PDISKQUOTA_USER pUser) PURE;
  744.  
  745.     STDMETHOD(Remove)(THIS_ 
  746.         PDISKQUOTA_USER pUser) PURE;
  747.  
  748.     STDMETHOD(RemoveAll)(THIS) PURE;
  749.  
  750.     STDMETHOD(FlushToDisk)(THIS) PURE;
  751. };
  752.  
  753.  
  754. typedef IDiskQuotaUserBatch DISKQUOTA_USER_BATCH, *PDISKQUOTA_USER_BATCH;
  755.  
  756.  
  757. ///////////////////////////////////////////////////////////////////////////////
  758. // IDiskQuotaControl interface
  759. //
  760. // This interface is the principle point of control for the disk quota control
  761. // library.  A client instantiates this interface through CoCreateInstance
  762. // using the the class ID CLSID_DiskQuotaControl.  The resulting quota control 
  763. // object provides a layer of abstraction around the disk quota facilities of 
  764. // a single NTFS volume.  Through the IDiskQuotaControl interface, the client
  765. // may query and set volume-specific quota attributes as well as enumerate
  766. // all quota user entries on the volume.
  767. //
  768. // The DiskQuotaControl object also implements IConnectionPointContainer
  769. // to service the IDiskQuotaEvents connection point interface.
  770. //
  771. //
  772. // IDiskQuotaControl::Initialize ----------------------------------------------
  773. //
  774. //      Initializes a new QuotaControl object by opening the NTFS volume
  775. //      with the requested access rights.  The return value indicates
  776. //      if the volume does not support NTFS disk quotas or if the caller
  777. //      does not have sufficient access rights.  
  778. //
  779. //                        >>>>>>  NOTE  <<<<<<<
  780. //
  781. //          Accessing quota information on remote volumes is not 
  782. //          supported for NT5 Beta 1.  Remote volume support will be
  783. //          added after Beta 1.
  784. //
  785. //      Arguments:
  786. //
  787. //          pszPath - Name of NTFS path to open.
  788. //                    To obtain WRITE access, this string must be
  789. //                    "\\.\X" where 'X' is the drive letter for the 
  790. //                    volume.  If only READ access is desired, the
  791. //                    path may be simply "X:\"
  792. //
  793. //          bReadWrite - TRUE  = Open for read/write.
  794. //                       FALSE = Open for read only
  795. //
  796. //      Returns:
  797. //
  798. //        NOERROR               - Success.
  799. //        E_FAIL                - Error getting volume information.
  800. //        DQC_E_INITIALIZED     - Controller object already initialized.
  801. //        DQC_E_ACCESS_DENIED   - Caller has insufficient access rights.
  802. //        DQC_E_INVALID_NAME    - Invalid path string at pszPath.
  803. //        DQC_E_FILE_NOT_FOUND  - Specified path doesn't exist.
  804. //        DQC_E_PATH_NOT_FOUND  - Specified path doesn't exist.
  805. //        DQC_E_BAD_PATHNAME    - Specified path name is invalid.
  806. //        DQC_E_NO_QUOTAS_FS    - File system isn't NTFS.
  807. //        DQC_E_NO_QUOTAS_FSVER - File system isn't NTFS v5.0 or greater.
  808. //          
  809. //              
  810. // IDiskQuotaControl::SetQuotaState -------------------------------------------
  811. //
  812. //      Sets the state of the quota system.  Note that not all state attributes
  813. //      can be modified.  The enable/disable and track/enforce attributes can
  814. //      be modified.
  815. //
  816. //      Arguments:
  817. //
  818. //          dwState - DWORD containing the state to be applied to the volume.
  819. //              Use the following macros to set the proper bits in the dwState
  820. //              argument:
  821. //
  822. //                                       Enable?   Track?  Enforce?
  823. //                                       --------- ------- --------
  824. //              DISKQUOTA_SET_DISABLED -   No        No       No
  825. //              DISKQUOTA_SET_TRACKED  -   Yes       Yes      No
  826. //              DISKQUOTA_SET_ENFORCED -   Yes       Yes      Yes
  827. //
  828. //      Returns:
  829. //
  830. //          NOERROR             - Success.
  831. //          E_INVALIDARG        - dwState value is incorrect.
  832. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  833. //          E_FAIL              - Failed writing quota information.
  834. //          
  835. //
  836. // IDiskQuotaControl::GetQuotaState -------------------------------------------
  837. //
  838. //      Retrieves a set of flags describing the state of the quota system.
  839. //
  840. //      Arguments:
  841. //
  842. //          pdwState - Address of DWORD to receive the state flags.  The flag
  843. //              bits are defined as follows:
  844. //
  845. //              DISKQUOTA_STATE_DISABLED - Quotas are not enabled on the volume.
  846. //
  847. //              DISKQUOTA_STATE_TRACK - Quotas are enabled but the limit value
  848. //                  is not being enforced.  Users may exceed their quota limit.
  849. //
  850. //              DISKQUOTA_STATE_ENFORCE - Quotas are enabled and the limit 
  851. //                  value is enforced.  Users cannot exceed their quota limit.
  852. //
  853. //              DISKQUOTA_FILESTATE_INCOMPLETE - The volume's quota information
  854. //                  is out of date.  Quotas are probably disabled.
  855. //
  856. //              DISKQUOTA_FILESTATE_REBUILDING - The volume is rebuilding it's
  857. //                  quota information.
  858. //
  859. //      Returns:
  860. //
  861. //          NOERROR             - Success.
  862. //          E_POINTER           - pdwState argument is NULL.
  863. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  864. //          E_FAIL              - Error reading quota information.
  865. //          
  866. //
  867. // IDiskQuotaControl::SetQuotaLogFlags ----------------------------------------
  868. //
  869. //      Controls the logging of user-related quota events on the volume. 
  870. //      Logging consists of an entry in the volume server system's event log.
  871. //
  872. //      Arguments:
  873. //
  874. //          dwFlags - DWORD containing the flags to be applied to the volume.
  875. //              Use the following macros to set the proper bits in the dwFlags
  876. //              argument:
  877. //
  878. //              DISKQUOTA_SET_LOG_USER_THRESHOLD - Turn on/off logging of 
  879. //                  user quota threshold violations.  If set, an event log
  880. //                  entry will be created when the user exceeds their assigned
  881. //                  quota warning threshold.
  882. //
  883. //              DISKQUOTA_SET_LOG_USER_LIMIT - Turn on/off logging of user
  884. //                  quota limit violations.  If set, an event log entry will
  885. //                  be created when the user exceeds their assigned quota 
  886. //                  limit.
  887. //
  888. //      Returns:
  889. //
  890. //          NOERROR             - Success.
  891. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  892. //          E_FAIL              - Failed writing quota information.
  893. //          
  894. //
  895. // IDiskQuotaControl::GetQuotaLogFlags ----------------------------------------
  896. //
  897. //      Retrieves the flags that control the logging of user-related quota 
  898. //      events on the volume. Logging consists of an entry in the volume 
  899. //      server's event log.
  900. //
  901. //      Arguments:
  902. //
  903. //          pdwFlags - Address of DWORD variable to receive the volume's
  904. //              quota logging flags.  Use the following macros to 
  905. //              interrogate the contents of the flag value:
  906. //
  907. //              DISKQUOTA_IS_LOGGED_USER_THRESHOLD
  908. //              DISKQUOTA_IS_LOGGED_USER_LIMIT
  909. //
  910. //      Returns:
  911. //
  912. //          NOERROR             - Success.
  913. //          E_POINTER           - pdwFlags argument is NULL.
  914. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  915. //          E_FAIL              - Failed reading volume quota information.
  916. //          
  917. //          
  918. // IDiskQuotaControl::SetDefaultQuotaLimit ------------------------------------
  919. //
  920. //      Modifies the default quota limit applied automatically to new users
  921. //      of the volume.
  922. //
  923. //      Arguments:
  924. //
  925. //          llLimit - Default quota limit value.
  926. //
  927. //      Returns:
  928. //
  929. //          NOERROR             - Success.
  930. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  931. //          E_FAIL              - Failed writing quota information.
  932. //          
  933. //
  934. // IDiskQuotaControl::GetDefaultQuotaLimit ------------------------------------
  935. //
  936. //      Retrieves the default quota limit applied automatically to new users
  937. //      of the volume.
  938. //
  939. //      Arguments:
  940. //
  941. //          pllLimit - Address of LONGLONG variable to receive the limit value.
  942. //
  943. //      Returns:
  944. //
  945. //          NOERROR             - Success.
  946. //          E_POINTER           - pllLimit argument is NULL.
  947. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  948. //          E_FAIL              - Failed reading quota information.
  949. //          
  950. //
  951. // IDiskQuotaControl::GetDefaultQuotaLimitText --------------------------------
  952. //
  953. //      Retrieves the volume's default quota "limit" expressed as a text
  954. //      string (i.e. "10.5 MB"). If the volume's limit is unlimited,
  955. //      the string "No Limit" is returned (localized).
  956. //
  957. //      Arguments:
  958. //
  959. //          pszText - Address of character buffer to receive text.
  960. //
  961. //          cchText - Size of destination buffer in bytes.
  962. //
  963. //      Returns:
  964. //          NOERROR             - Success.
  965. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  966. //          E_FAIL              - Failed reading quota information.
  967. //
  968. //
  969. // IDiskQuotaControl::SetDefaultQuotaThreshold --------------------------------
  970. //
  971. //      Modifies the default quota warning threshold applied automatically to 
  972. //      new users of the volume.
  973. //
  974. //      Arguments:
  975. //
  976. //          llThreshold - Default quota threshold value.
  977. //
  978. //      Returns:
  979. //
  980. //          NOERROR             - Success.
  981. //          DQC_E_ACCESS_DENIED - No WRITE access to quota information.
  982. //          E_FAIL              - Failed writing quota information.
  983. //          
  984. //
  985. // IDiskQuotaControl::GetDefaultQuotaThreshold --------------------------------
  986. //
  987. //      Retrieves the default quota warning threshold applied automatically to 
  988. //      new users of the volume.
  989. //
  990. //      Arguments:
  991. //
  992. //          pllThreshold - Address of LONGLONG variable to receive the 
  993. //              warning threshold value.
  994. //
  995. //      Returns:
  996. //
  997. //          NOERROR             - Success.
  998. //          E_POINTER           - pllThreshold argument is NULL.
  999. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  1000. //          E_FAIL              - Failed reading quota information.
  1001. //          
  1002. //
  1003. // IDiskQuotaControl::GetDefaultQuotaThresholdText ----------------------------
  1004. //
  1005. //      Retrieves the volume's default quota "threshold" expressed as a text
  1006. //      string (i.e. "10.5 MB"). If the volume's threshold is unlimited,
  1007. //      the string "No Limit" is returned (localized).
  1008. //
  1009. //      Arguments:
  1010. //
  1011. //          pszText - Address of character buffer to receive text.
  1012. //
  1013. //          cchText - Size of destination buffer in bytes.
  1014. //
  1015. //      Returns:
  1016. //          NOERROR             - Success.
  1017. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  1018. //          E_FAIL              - Failed reading quota information.
  1019. //
  1020. //
  1021. // IDiskQuotaControl::AddUserSid ----------------------------------------------
  1022. // IDiskQuotaControl::AddUserName ---------------------------------------------
  1023. //
  1024. //      Adds a new quota entry on the volume for a given user.  Note that 
  1025. //      NTFS automatically creates a user quota entry when a user first writes
  1026. //      to the volume.  Automatically created user entries are assigned the
  1027. //      volume's default threshold and limit values.  This function allows
  1028. //      you to create a user quota entry before a user has written information
  1029. //      to the volume.  One reason for doing this might be to pre-assign
  1030. //      a threshold or limit value different than the volume defaults.
  1031. //
  1032. //      Arguments:
  1033. //
  1034. //          pUserSid - Address of buffer containing user's security ID (SID).
  1035. //
  1036. //          pszDomain - Address of user's domain name string.
  1037. //
  1038. //          pszName - Address of user's account name string.
  1039. //              If pszDomain points to a blank string, it is assumed that
  1040. //              pszName points to a fully-qualified "Domain\Account" string.
  1041. //
  1042. //          fNameResolution - Flag indicating how the user's account information
  1043. //              is to be obtained.  The volume's quota information contains
  1044. //              only security IDs for identifying users.  The user's account 
  1045. //              information such as domain name, account name and full user 
  1046. //              name must be obtained from the network domain controller, or 
  1047. //              the local machine if the machine is not networked.  This 
  1048. //              information may be obtained synchronously, asynchronously or 
  1049. //              not at all.
  1050. //              Specify one of the following values in this argument:
  1051. //
  1052. //              DISKQUOTA_USERNAME_RESOLVE_NONE - Do not resolve user account
  1053. //                  information.
  1054. //
  1055. //              DISKQUOTA_USERNAME_RESOLVE_SYNC - Resolve user account 
  1056. //                  information synchronously.  AddUser will not return until 
  1057. //                  the information has been resolved.  If the information
  1058. //                  is present in the disk quota SID cache, the return of
  1059. //                  information will be immediate.  If not cached, the
  1060. //                  function can take a considerable amount of time to 
  1061. //                  locate the user's information.  This period is dependent
  1062. //                  upon many network-related factors.  It can be on the
  1063. //                  order of several seconds.
  1064. //
  1065. //              DISKQUOTA_USERNAME_RESOLVE_ASYNC - Resolve user account 
  1066. //                  information asynchronously.  AddUser will return 
  1067. //                  immediately.  The caller must implement 
  1068. //                  IDiskQuotaUserEvents to receive notification when the 
  1069. //                  account information is available.  This option causes
  1070. //                  the user object to be placed on a queue.  This queue
  1071. //                  is serviced by a thread dedicated to obtaining account
  1072. //                  information for disk quota users on the volume. If the 
  1073. //                  information has been cached from a previous request,
  1074. //                  the notification occurs as soon as the object is serviced.
  1075. //                  If the information is not cached, the thread obtains
  1076. //                  the information from the network domain controller and
  1077. //                  then notifies IDiskQuotaUserEvents that the operation
  1078. //                  is complete.
  1079. //
  1080. //          ppUser - Address of IDiskQuotaUser pointer variable to receive
  1081. //              the interface pointer of the newly created quota user object.
  1082. //
  1083. //
  1084. //      Returns:
  1085. //
  1086. //          SUCCESS            - Success.
  1087. //          E_OUTOFMEMORY      - Insufficient memory.
  1088. //          S_FALSE            - User already exists.  Not added.
  1089. //          E_POINTER          - Pointer argument was NULL.
  1090. //          DQC_E_USER_UNKNOWN - User name provided is unknown.
  1091. //
  1092. //
  1093. // IDiskQuotaControl::FindUserSid ---------------------------------------------
  1094. //
  1095. //      Locates a specific user entry in the volume's quota information.
  1096. //      The user's security ID (SID) is used as the search key.
  1097. //
  1098. //      Arguments:
  1099. //
  1100. //          pUserSid - Address of buffer containing user's security ID (SID).
  1101. //
  1102. //          fNameResolution - Flag indicating how the user's account information
  1103. //              is to be resolved.  See description in AddUser for details.
  1104. //
  1105. //          ppUser - Address of IDiskQuotaUser pointer variable to receive
  1106. //              the interface pointer of the quota user object for the user.
  1107. //
  1108. //      Returns:
  1109. //          NOERROR             - Success.
  1110. //          E_FAIL              - User not found in volume's quota information.
  1111. //          E_POINTER           - Either pUserSid or ppUser was NULL.
  1112. //          E_OUTOFMEMORY       - Insufficient memory.
  1113. //          DQC_E_INVALID_SID   - SID pointed to by pUserSid is invalid.
  1114. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  1115. //
  1116. //                   >>>>>>>>> IMPORTANT NOTE <<<<<<<<<
  1117. //
  1118. //        This method will return a user object even if there is no quota
  1119. //        record for the user in the quota file.  While that may sound
  1120. //        strange, it is consistent with the idea of automatic user addition
  1121. //        and default quota settings.  If there is currently no quota entry
  1122. //        for the requested user, and the user would be added to the quota
  1123. //        file if they were to request disk space, the returned user object
  1124. //        will have a quota threshold and limit equal to the volume defaults.
  1125. //
  1126. //
  1127. // IDiskQuotaControl::FindUserName --------------------------------------------
  1128. //
  1129. //      Locates a specific entry in the volume's quota information.
  1130. //      The user's domain and account name are used as the search key.  
  1131. //      This method can take some time as it may need to resolve the name to 
  1132. //      a security ID.  See note for FindUserSid (above) concerning behavior
  1133. //      when an entry for the user does not exist.
  1134. //
  1135. //      Arguments:
  1136. //
  1137. //          pszDomain - Address of buffer containing user's domain name string.
  1138. //
  1139. //          pszName - Address of buffer containing user's account name string.
  1140. //
  1141. //          ppUser - Address of IDiskQuotaUser pointer variable to receive
  1142. //              the interface pointer of the quota user object for the user.
  1143. //
  1144. //          fNameResolution - Flag indicating how the user's account information
  1145. //              is to be resolved.  See description in AddUser for details.
  1146. //
  1147. //      Returns:
  1148. //          NOERROR             - Success.
  1149. //          E_FAIL              - User not found in volume's quota information.
  1150. //          E_POINTER           - Either pUserSid or ppUser was NULL.
  1151. //          E_OUTOFMEMORY       - Insufficient memory.
  1152. //          DQC_E_INVALID_SID   - SID pointed to by pUserSid is invalid.
  1153. //          DQC_E_ACCESS_DENIED - No READ access to quota information.
  1154. //          DQC_E_NO_SID_MAPPING- Could not map account name to a security ID.
  1155. //
  1156. //
  1157. // IDiskQuotaControl::DeleteUser ----------------------------------------------
  1158. //
  1159. //      Removes a user entry from the volume's quota information file if the 
  1160. //      user's charged quota amount is 0 bytes.  This function doesn't actually
  1161. //      remove the quota entry from the volume.  It marks the entry for 
  1162. //      deletion.  NTFS performs the actual deletion at a later point in time.
  1163. //      Following a call to DeleteUser, the IDiskQuotaUser interface is still
  1164. //      active.  This function does not delete the user object from memory.
  1165. //      You must still call IUnknown::Release() on the user object to
  1166. //      release it.
  1167. //
  1168. //      Arguments:
  1169. //
  1170. //          pUser - Pointer to IDiskQuotaUser interface of quota user who's
  1171. //              quota record is marked for deletion.
  1172. //
  1173. //      Returns:
  1174. //      
  1175. //          NOERROR              - Success.
  1176. //          E_POINTER            - pUser argument was NULL.
  1177. //          E_FAIL               - Error marking entry for deletion.
  1178. //          DQC_E_USER_HAS_FILES - Couldn't delete.  User still has file(s) on
  1179. //                                 the volume.
  1180. //          DQC_E_ACCESS_DENIED  - Insufficient access.
  1181. //
  1182. //
  1183. // IDiskQuotaControl::CreateEnumUsers -----------------------------------------
  1184. //
  1185. //      Creates an enumerator object for enumerating quota users on the volume.
  1186. //      The object created implements the IEnumDiskQuotaUsers interface.  
  1187. //      The object created supports the standard OLE IEnumXXXX functions.
  1188. //
  1189. //      Arguments:
  1190. //
  1191. //          rgpUserSids - Array of security ID (SID) pointers representing the
  1192. //              user objects to be included in the enumeration.  If this 
  1193. //              value is NULL, all user entries are enumerated.
  1194. //
  1195. //          cpSids - Number of items in the rgpUserSids array.  Ignored if 
  1196. //              rgpUserSids is NULL.
  1197. //
  1198. //
  1199. //          ppEnum - Address of IEnumDiskQuotaUsers pointer variable to receive
  1200. //              the address of the new enumerator.
  1201. //
  1202. //          fNameResolution - Flag indicating how the account information for
  1203. //              enumerated users is to be resolved.  See description in
  1204. //              AddUser for details.
  1205. //
  1206. //      Returns:
  1207. //          NOERROR             - Success.
  1208. //          E_POINTER           - ppEnum argument is NULL.
  1209. //          E_OUTOFMEMORY       - Insufficient memory.
  1210. //          DQC_E_ACCESS_DENIED - Insufficient access rights.
  1211. //
  1212. //
  1213. // IDiskQuotaControl::CreateUserBatch -----------------------------------------
  1214. //
  1215. //      Creates a batching object for optimizing updates to the quota settings
  1216. //      of multiple users simultaneously. See IDiskQuotaUserBatch for details.
  1217. //
  1218. //      Arguments:
  1219. //
  1220. //          ppBatch - Address of IDiskQuotaUserBatch pointer variable to 
  1221. //              receive the IDiskQuotaUserBatch interface pointer.
  1222. //
  1223. //      Returns:
  1224. //
  1225. //        NOERROR             - Success.
  1226. //        E_POINTER           - ppBatch argument is NULL.
  1227. //        E_OUTOFMEMORY       - Insufficient memory to create batch object.
  1228. //        DQC_E_ACCESS_DENIED - Insufficient access rights.
  1229. //
  1230. //
  1231. // IDiskQuotaControl::InvalidateSidNameCache ----------------------------------
  1232. //
  1233. //      Invalidates the contents of the system's SID-Name cache so that 
  1234. //      subsequent requests for new user objects (IEnumDiskQuotaUsers::Next,
  1235. //      IDiskQuotaControl::FindUserSid and IDiskQuotaControl::FindUserName) 
  1236. //      must obtain user names from the network domain controller.  As names 
  1237. //      are obtained, they are again cached.
  1238. //
  1239. //      In general there is no reason to call this method.  It is included to 
  1240. //      provide a method for programmatically refreshing the entire SID-name
  1241. //      cache.
  1242. //
  1243. //      Arguments: None.
  1244. //
  1245. //      Returns:
  1246. //
  1247. //          NOERROR - Success.
  1248. //          E_FAIL  - SID/Name cache not available or couldn't obtain 
  1249. //              exclusive lock on cache.
  1250. //
  1251. //
  1252. // IDiskQuotaControl::GiveUserNameResolutionPriority --------------------------
  1253. //
  1254. //      By default, quota user objects are serviced in the resolution queue in 
  1255. //      the order they were placed into the queue.  This function will promote
  1256. //      a specified user object to the head of the queue so that it is next in 
  1257. //      line for resolution.
  1258. //
  1259. //      Arguments:
  1260. //
  1261. //          pUser - Address of user object's IDiskQuotaUser interface.
  1262. //
  1263. //      Returns:
  1264. //
  1265. //        NOERROR       - Success.
  1266. //        S_FALSE       - Quota user object not in resolver queue.
  1267. //        E_UNEXPECTED  - Unexpected error.  Caught an exception or the 
  1268. //                        Sid-Name resolver hasn't been created.
  1269. //
  1270. //
  1271. // IDiskQuotaControl::ShutdownNameResolution ----------------------------------
  1272. //
  1273. //      The SID-Name resolver runs on a background thread to translate
  1274. //      user security IDs to user names.  When a quota control object is 
  1275. //      destroyed, this thread automatically terminates.  If you have a
  1276. //      situation where you're finished with the quota control object and
  1277. //      it is not be ready to be destroyed (other open ref counts),
  1278. //      this method may be called to shut down the background thread before
  1279. //      the object is destroyed.  Note that asynchronous name resolution will 
  1280. //      also cease once the thread terminates.  A subsequent call to 
  1281. //      CreateEnumUsers, AddUserSid, AddUserName, FindUserSid or FindUserName 
  1282. //      may re-create the resolver thread.
  1283. //      
  1284. //      Arguments: None.
  1285. //
  1286. //      Returns : Only returns NOERROR.
  1287. //
  1288. ///////////////////////////////////////////////////////////////////////////////
  1289. #undef INTERFACE
  1290. #define INTERFACE IDiskQuotaControl
  1291.  
  1292. DECLARE_INTERFACE_(IDiskQuotaControl, IConnectionPointContainer)
  1293. {
  1294.     STDMETHOD(Initialize)(THIS_ 
  1295.         LPCWSTR pszPath, 
  1296.         BOOL bReadWrite) PURE;
  1297.  
  1298.     STDMETHOD(SetQuotaState)(THIS_ 
  1299.         DWORD dwState) PURE;
  1300.  
  1301.     STDMETHOD(GetQuotaState)(THIS_ 
  1302.         LPDWORD pdwState) PURE;
  1303.  
  1304.     STDMETHOD(SetQuotaLogFlags)(THIS_ 
  1305.         DWORD dwFlags) PURE;
  1306.  
  1307.     STDMETHOD(GetQuotaLogFlags)(THIS_ 
  1308.         LPDWORD pdwFlags) PURE;
  1309.  
  1310.     STDMETHOD(SetDefaultQuotaThreshold)(THIS_ 
  1311.         LONGLONG llThreshold) PURE;
  1312.  
  1313.     STDMETHOD(GetDefaultQuotaThreshold)(THIS_ 
  1314.         PLONGLONG pllThreshold) PURE;
  1315.  
  1316.     STDMETHOD(GetDefaultQuotaThresholdText)(THIS_
  1317.         LPWSTR pszText,
  1318.         DWORD cchText) PURE;
  1319.  
  1320.     STDMETHOD(SetDefaultQuotaLimit)(THIS_ 
  1321.         LONGLONG llLimit) PURE;
  1322.  
  1323.     STDMETHOD(GetDefaultQuotaLimit)(THIS_ 
  1324.         PLONGLONG pllLimit) PURE;
  1325.  
  1326.     STDMETHOD(GetDefaultQuotaLimitText)(THIS_
  1327.         LPWSTR pszText,
  1328.         DWORD cchText) PURE;
  1329.  
  1330.     STDMETHOD(AddUserSid)(THIS_ 
  1331.         PSID pUserSid, 
  1332.         DWORD fNameResolution,
  1333.         PDISKQUOTA_USER *ppUser) PURE; 
  1334.  
  1335.     STDMETHOD(AddUserName)(THIS_ 
  1336.         LPWSTR pszDomain,
  1337.         LPWSTR pszName,
  1338.         DWORD fNameResolution,
  1339.         PDISKQUOTA_USER *ppUser) PURE; 
  1340.  
  1341.     STDMETHOD(DeleteUser)(THIS_ 
  1342.         PDISKQUOTA_USER pUser) PURE;
  1343.  
  1344.     STDMETHOD(FindUserSid)(THIS_ 
  1345.         PSID pUserSid, 
  1346.         DWORD fNameResolution,
  1347.         PDISKQUOTA_USER *ppUser) PURE;
  1348.  
  1349.     STDMETHOD(FindUserName)(THIS_ 
  1350.         LPCWSTR pszDomain, 
  1351.         LPCWSTR pszName, 
  1352.         PDISKQUOTA_USER *ppUser) PURE;
  1353.  
  1354.     STDMETHOD(CreateEnumUsers)(THIS_ 
  1355.         PSID *rgpUserSids, 
  1356.         DWORD cpSids, 
  1357.         DWORD fNameResolution,
  1358.         PENUM_DISKQUOTA_USERS *ppEnum) PURE;
  1359.  
  1360.     STDMETHOD(CreateUserBatch)(THIS_ 
  1361.         PDISKQUOTA_USER_BATCH *ppBatch) PURE;
  1362.  
  1363.     STDMETHOD(InvalidateSidNameCache)(THIS) PURE;
  1364.  
  1365.     STDMETHOD(GiveUserNameResolutionPriority)(THIS_ 
  1366.         PDISKQUOTA_USER pUser) PURE;
  1367.  
  1368.     STDMETHOD(ShutdownNameResolution)(THIS_
  1369.         VOID) PURE;
  1370. };
  1371.  
  1372. typedef IDiskQuotaControl DISKQUOTA_CONTROL, *PDISKQUOTA_CONTROL;
  1373.  
  1374.  
  1375.  
  1376. ///////////////////////////////////////////////////////////////////////////////
  1377. // IDiskQuotaEvents interface
  1378. //
  1379. // A client must implement this interface as an OLE event sink in order to
  1380. // receive quota-related event notifications such as asynchronous account
  1381. // name resolution.
  1382. //
  1383. // IDiskQuotaEvents::OnUserNameChanged ----------------------------------------
  1384. //
  1385. //      Notifies client's connection sink whenever a user's SID has been 
  1386. //      asynchronously resolved so that the user's domain, account and full
  1387. //      name strings are available in the quota user object.
  1388. //
  1389. //      Arguments:
  1390. //
  1391. //          pUser - Address of IDiskQuotaUser interface for quota user object.
  1392. //                  It is not necessary to call Release() on this pointer.
  1393. //                  The DiskQuotaControl object controls the lifetime of the
  1394. //                  user object.
  1395. //
  1396. //      Returns:  Return value is ignored.
  1397. //  
  1398. ///////////////////////////////////////////////////////////////////////////////
  1399. #undef  INTERFACE
  1400. #define INTERFACE IDiskQuotaEvents
  1401.  
  1402. DECLARE_INTERFACE_(IDiskQuotaEvents, IUnknown)
  1403. {
  1404.     STDMETHOD(OnUserNameChanged)(THIS_ 
  1405.         PDISKQUOTA_USER pUser) PURE;
  1406. };
  1407.  
  1408. typedef IDiskQuotaEvents DISKQUOTA_EVENTS, *PDISKQUOTA_EVENTS;
  1409.  
  1410.  
  1411. ///////////////////////////////////////////////////////////////////////////////
  1412. // DiskQuotaEventSink
  1413. //
  1414. // Declaration for a class that implements IDiskQuotaEvents.  A client may
  1415. // implement this class as it is declared or create their own class.  The only
  1416. // requirement is that it implement IDiskQuotaEvents as an OLE connection
  1417. // point.  See the SDK documentation for details on OLE connection points and
  1418. // OLE connection point containers.
  1419. //
  1420. ///////////////////////////////////////////////////////////////////////////////
  1421. class DiskQuotaEventSink : public IDiskQuotaEvents
  1422. {
  1423.     private:
  1424.         LONG  m_cRef;       // Interface reference count.
  1425.  
  1426.     public:
  1427.         DWORD m_dwCookie;   // Connection point cookie.
  1428.  
  1429.         DiskQuotaEventSink(VOID);
  1430.         ~DiskQuotaEventSink(VOID);
  1431.  
  1432.         //
  1433.         // IUnknown methods.
  1434.         //
  1435.         STDMETHODIMP QueryInterface(REFIID, LPVOID *);
  1436.         STDMETHODIMP_(ULONG) AddRef(VOID);
  1437.         STDMETHODIMP_(ULONG) Release(VOID);
  1438.  
  1439.         //
  1440.         // IDiskQuotaEvents
  1441.         //
  1442.         STDMETHODIMP OnUserNameChanged(PDISKQUOTA_USER pUser);
  1443. };
  1444.  
  1445.  
  1446. ///////////////////////////////////////////////////////////////////////////////
  1447. // Error codes specific to the public disk quota interfaces.
  1448. // "DQC" = Disk Quota Control
  1449. ///////////////////////////////////////////////////////////////////////////////
  1450. //
  1451. // Security ID for user is invalid.
  1452. //
  1453. #define DQC_E_INVALID_SID          MAKE_HRESULT(SEVERITY_ERROR, \
  1454.                                                 FACILITY_ITF, \
  1455.                                                 ERROR_INVALID_SID)
  1456. //
  1457. // Insufficient memory to complete operation.
  1458. //
  1459. #define DQC_E_INSUFFICIENT_BUFFER  MAKE_HRESULT(SEVERITY_ERROR, \
  1460.                                                 FACILITY_ITF, \
  1461.                                                 ERROR_INSUFFICIENT_BUFFER)
  1462. //
  1463. // An operation/capability is not supported.
  1464. //
  1465. #define DQC_E_NOT_SUPPORTED        MAKE_HRESULT(SEVERITY_ERROR, \
  1466.                                                 FACILITY_ITF, \
  1467.                                                 ERROR_NOT_SUPPORTED)
  1468. //
  1469. // No access to perform the requested operation.
  1470. //
  1471. #define DQC_E_ACCESS_DENIED        MAKE_HRESULT(SEVERITY_ERROR, \
  1472.                                                 FACILITY_ITF, \
  1473.                                                 ERROR_ACCESS_DENIED)
  1474. //
  1475. // Requested file or object not found.
  1476. //
  1477. #define DQC_E_FILE_NOT_FOUND       MAKE_HRESULT(SEVERITY_ERROR, \
  1478.                                                 FACILITY_ITF, \
  1479.                                                 ERROR_FILE_NOT_FOUND)
  1480. //
  1481. // Requested file path not found.
  1482. //
  1483. #define DQC_E_PATH_NOT_FOUND       MAKE_HRESULT(SEVERITY_ERROR, \
  1484.                                                 FACILITY_ITF, \
  1485.                                                 ERROR_PATH_NOT_FOUND)
  1486. //
  1487. // Requested file path is invalid.
  1488. //
  1489. #define DQC_E_INVALID_NAME         MAKE_HRESULT(SEVERITY_ERROR, \
  1490.                                                 FACILITY_ITF, \
  1491.                                                 ERROR_INVALID_NAME)
  1492. //
  1493. // Requested file path is invalid.
  1494. //
  1495. #define DQC_E_BAD_PATHNAME         MAKE_HRESULT(SEVERITY_ERROR, \
  1496.                                                 FACILITY_ITF, \
  1497.                                                 ERROR_BAD_PATHNAME)
  1498. //
  1499. // Failed to obtain exclusive lock on a shared resource.
  1500. //
  1501. #define DQC_E_LOCK_FAILED          MAKE_HRESULT(SEVERITY_ERROR, \
  1502.                                                 FACILITY_ITF, \
  1503.                                                 ERROR_LOCK_FAILED)
  1504. //
  1505. // No mapping available for security ID to user name.
  1506. //
  1507. #define DQC_E_NO_SID_MAPPING       MAKE_HRESULT(SEVERITY_ERROR, \
  1508.                                                 FACILITY_ITF, \
  1509.                                                 ERROR_NONE_MAPPED)
  1510. //
  1511. // No more items in enumeration.
  1512. //
  1513. #define DQC_S_NO_MORE_ITEMS        MAKE_HRESULT(SEVERITY_SUCCESS, \
  1514.                                                 FACILITY_ITF, \
  1515.                                                 ERROR_NO_MORE_ITEMS)
  1516. //
  1517. // User owns files on volume.
  1518. // 
  1519. #define DQC_E_USER_HAS_FILES       MAKE_HRESULT(SEVERITY_ERROR, \
  1520.                                                 FACILITY_ITF, \
  1521.                                                 0x8002)
  1522. //
  1523. // File system doesn't support quotas.
  1524. // Currently, must be NTFS.
  1525. //
  1526. #define DQC_E_NO_QUOTAS_FS         MAKE_HRESULT(SEVERITY_ERROR, \
  1527.                                                 FACILITY_ITF, \
  1528.                                                 0x8003)
  1529. //
  1530. // File system version doesn't support quotas.
  1531. // Currently, must be NTFS 5.0 or greater.
  1532. //
  1533. #define DQC_E_NO_QUOTAS_FSVER      MAKE_HRESULT(SEVERITY_ERROR, \
  1534.                                                 FACILITY_ITF, \
  1535.                                                 0x8004)
  1536. //
  1537. // Object has already been initialized.
  1538. // Multiple initialization is not allowed.
  1539. //
  1540. #define DQC_E_INITIALIZED          MAKE_HRESULT(SEVERITY_ERROR, \
  1541.                                                 FACILITY_ITF, \
  1542.                                                 0x8005)
  1543.  
  1544. //
  1545. // Object has not been initialized.
  1546. // Initialization must be completed before operation can be performed.
  1547. //
  1548. #define DQC_E_NOT_INITIALIZED      MAKE_HRESULT(SEVERITY_ERROR, \
  1549.                                                 FACILITY_ITF, \
  1550.                                                 0x8006)
  1551. //
  1552. // Specified user is unknown.
  1553. //
  1554. #define DQC_E_USER_UNKNOWN         MAKE_HRESULT(SEVERITY_ERROR, \
  1555.                                                 FACILITY_ITF, \
  1556.                                                 0x8007)
  1557.  
  1558. //=============================================================================
  1559. //=============================================================================
  1560. // ActiveX Control Description
  1561. //=============================================================================
  1562. //=============================================================================
  1563. //
  1564. // DSKQUOTA.DLL also provides an ActiveX control that performs much of the
  1565. // functionality found in the vtable interfaces IDiskQuotaControl, 
  1566. // IDiskQuotaUser and IDiskQuotaEvents.
  1567. //
  1568. // The following section describes the properties and methods for each
  1569. // OLE automation interface supported.
  1570. //
  1571. // ActiveX object ProgID = "Microsoft.DiskQuota.1"
  1572. // ActiveX object CLSID  = {7988B571-EC89-11cf-9C00-00AA00A14F56}
  1573. // Type library CLSID    = {7988B57C-EC89-11cf-9C00-00AA00A14F56}
  1574. // 
  1575. // The object supports 3 automation-compatible interfaces:
  1576. //
  1577. //      IID_DIDiskQuotaControl          [default]
  1578. //      IID_DIDiskQuotaUser
  1579. //      IID_DIDiskQuotaControlEvents    [default, source]
  1580. // 
  1581. //
  1582. // ----------------------------------------------------------------------------
  1583. // IID_DIDiskQuotaControl - Disk Quota Controller
  1584. //
  1585. // This interface is the default controlling interface for the DiskQuota
  1586. // ActiveX component.  It implements much the same functionality as 
  1587. // the vtable interface IDiskQuotaControl.
  1588. //
  1589. // Properties:
  1590. //
  1591. //      QuotaState
  1592. //
  1593. //          Desc:   The "state" of NTFS disk quotas on the volume.
  1594. //                  The state can be either "disabled", "tracking quota usage"
  1595. //                  or "enforcing quota limits".  Enforcement implies
  1596. //                  tracking.
  1597. //
  1598. //          Type:   QuotaStateConstants (enumeration)
  1599. //
  1600. //          Domain: dqStateDisable   (0)
  1601. //                  qsStateTrack     (1)
  1602. //                  qsStateEnforce   (2)
  1603. //
  1604. //      QuotaFileIncomplete (read only)
  1605. //
  1606. //          Desc:   Determines if the quota file on the volume is marked
  1607. //                  as "incomplete".  An incomplete volume is usually the
  1608. //                  result of a disabled quota system.
  1609. //
  1610. //          Type:   VARIANT_BOOL
  1611. //
  1612. //          Domain: True/False
  1613. //
  1614. //      QuotaFileRebuilding (read only)
  1615. //
  1616. //          Desc:   Determines if the quota file on the volume is being
  1617. //                  rebuilt.  Rebuilding automatically occurs whenever
  1618. //                  quotas are enabled on the system or when one or more
  1619. //                  user entries are marked for deletion.
  1620. //
  1621. //          Type:   VARIANT_BOOL
  1622. //
  1623. //          Domain: True/False
  1624. //
  1625. //      LogQuotaThreshold
  1626. //
  1627. //          Desc:   Indicates if a system event log entry should be created
  1628. //                  whenever a user exceeds their assigned quota warning
  1629. //                  threshold.
  1630. //
  1631. //          Type:   VARIANT_BOOL
  1632. //
  1633. //          Domain: True/False
  1634. //
  1635. //      LogQuotaLimit
  1636. //
  1637. //          Desc:   Indicates if a system event log entry should be created
  1638. //                  whenever a user exceeds their assigned quota limit.
  1639. //
  1640. //          Type:   VARIANT_BOOL
  1641. //
  1642. //          Domain: True/False
  1643. //
  1644. //      DefaultQuotaThreshold
  1645. //
  1646. //          Desc:   The default warning threshold value assigned to new users
  1647. //                  of the volume.
  1648. //
  1649. //          Type:   double
  1650. //
  1651. //          Domain: Value is expressed in bytes.
  1652. //
  1653. //      DefaultQuotaThresholdText (read only)
  1654. //
  1655. //          Desc:   The default threshold value expressed as a text
  1656. //                  string suitable for display.  The recipient of
  1657. //                  the string is responsible for deleting the string
  1658. //                  using SysFreeString().
  1659. //
  1660. //          Type:   BSTR
  1661. //
  1662. //          Domain: Threshold value formatted as a decimal number
  1663. //                  and appended with a units suffix.
  1664. //
  1665. //                  i.e.:  "10.5 MB"
  1666. //                         "No Limit" if unlimited.
  1667. //
  1668. //      DefaultQuotaLimit
  1669. //
  1670. //          Desc:   The default quota limit value assigned to new users
  1671. //                  of the volume.
  1672. //
  1673. //          Type:   double
  1674. //
  1675. //          Domain: Value is expressed in bytes.
  1676. //                  -1 is special case meaning "no limit".
  1677. //
  1678. //      DefaultQuotaLimitText (read only)
  1679. //
  1680. //          Desc:   The default quota limit value expressed as a text
  1681. //                  string suitable for display.  The recipient of
  1682. //                  the string is responsible for deleting the string
  1683. //                  using SysFreeString().
  1684. //
  1685. //          Type:   BSTR
  1686. //
  1687. //          Domain: Limit value formatted as a decimal number
  1688. //                  and appended with a units suffix.
  1689. //
  1690. //                  i.e.:  "10.5 MB"
  1691. //                         "No Limit" if unlimited.
  1692. //
  1693. //      UserNameResolution
  1694. //
  1695. //          Desc:   Controls the behavior of the security ID-to-Name
  1696. //                  resolution processing.  The process may be bypassed,
  1697. //                  performed synchronously or performed asynchronously.
  1698. //                  If Asynchronous name resolution is chosen, the caller
  1699. //                  must implement the DIDiskQuotaControlEvents dispatch 
  1700. //                  interface to receive notification when the name has
  1701. //                  been resolved.
  1702. //
  1703. //          Type:   UserNameResolutionConstants (enumeration)
  1704. //
  1705. //          Domain: dqResolveNone      (0) - No name information
  1706. //                  dqResolveSync      (1) - Resolve synchronously
  1707. //                  dqResolveAsync     (2) - Resolve asynchronously
  1708. //
  1709. // Methods:
  1710. //
  1711. //      Initialize
  1712. //
  1713. //          Desc:   Initializes a DiskQuota object for a given NTFS volume.
  1714. //                  This method must be called before any other methods.
  1715. //                  If unsuccessful, any other method calls will return
  1716. //                  DQC_E_NOT_INITIALIZED.
  1717. //
  1718. //                        >>>>>>  NOTE  <<<<<<<
  1719. //
  1720. //          Accessing quota information on remote volumes is not 
  1721. //          supported for NT5 Beta 1.  Remote volume support will be
  1722. //          added after Beta 1.
  1723. //
  1724. //
  1725. //          Arguments:
  1726. //              pPath [in] - Contains path of volume to initialize.
  1727. //
  1728. //                  Type:   BSTR
  1729. //
  1730. //                  Domain: To obtain WRITE access, this string must be
  1731. //                          "\\.\X" where 'X' is the drive letter for the 
  1732. //                          volume.  If only READ access is desired, the
  1733. //                          path may be simply "X:\"
  1734. //
  1735. //              bReadWrite [in] - Indicates if "write" access is desired.  
  1736. //
  1737. //                  Type:   VARIANT_BOOL
  1738. //
  1739. //                  Domain: False = Read-only
  1740. //                          True  = Read-Write
  1741. //
  1742. //          Returns: Nothing.
  1743. //
  1744. //          Errors:  See IDiskQuotaControl::Initialize.
  1745. //
  1746. //
  1747. //      AddUser
  1748. //
  1749. //          Desc:   Add a new user entry to the volume's quota file.
  1750. //                  If the user already exists, the object for the existing
  1751. //                  user is returned.
  1752. //
  1753. //          Arguments:
  1754. //              pDomain [in] - User's account domain name.
  1755. //
  1756. //                  Type:   BSTR
  1757. //
  1758. //                  Domain: Windows NT domain names.
  1759. //
  1760. //              pName [in] - User's account name.  If pDomain is a blank string,
  1761. //                  pName is assumed to contain a fully-qualified
  1762. //                  "Domain\Account" combination.
  1763. //
  1764. //                  Type:   BSTR
  1765. //
  1766. //                  Domain: Windows NT user account names.
  1767. //
  1768. //          Returns:
  1769. //              Reference to newly added user object (DIDiskQuotaUser).
  1770. //
  1771. //          Errors:  See IDiskQuotaControl::AddUserName
  1772. //
  1773. //
  1774. //      DeleteUser
  1775. //
  1776. //          Arguments:
  1777. //              pUser [in] - Reference to user object to be marked for deletion.
  1778. //
  1779. //                  Type:   DIDiskQuotaUser
  1780. //
  1781. //                  Domain: Pointer to DIDiskQuotaUser interface.
  1782. //
  1783. //          Returns: Nothing
  1784. //
  1785. //          Errors:  See IDiskQuotaControl::DeleteUser
  1786. //
  1787. //
  1788. //      FindUser
  1789. //
  1790. //          Desc:   Locate user entry in the volume's quota file.
  1791. //
  1792. //          Arguments:
  1793. //              pDomain [in] - User's account domain name.
  1794. //
  1795. //                  Type:   BSTR
  1796. //
  1797. //                  Domain: Windows NT domain names.
  1798. //
  1799. //              pName [in] - User's account name.
  1800. //
  1801. //                  Type:   BSTR
  1802. //
  1803. //                  Domain: Windows NT user account names.
  1804. //
  1805. //          Returns:
  1806. //              Reference to located user object (DIDiskQuotaUser).
  1807. //
  1808. //          Errors:  See IDiskQuotaControl::FindUserName
  1809. //
  1810. //
  1811. //      InvalidateSidNameCache
  1812. //
  1813. //          Desc:   Invalidates the contents of the Security ID-User name
  1814. //                  cache.  Following cache invalidation, subsequent 
  1815. //                  creations of user objects will need resolve and
  1816. //                  re-cache account information.
  1817. //      
  1818. //          Arguments: None
  1819. //
  1820. //          Returns:  Nothing
  1821. //
  1822. //          Errors:  See IDiskQuotaControl::InvalidateSidNameCache
  1823. //
  1824. //
  1825. //      GiveUserNameResolutionPriority
  1826. //
  1827. //          Desc:   When UserNameResolution is dqResolveAsync, 
  1828. //                  user entry objects with unresolved security IDs are
  1829. //                  automatically placed on a queue, waiting to be
  1830. //                  resolved.  The resolution process occurs on a background
  1831. //                  thread.  Normally objects are processed on a FIFO
  1832. //                  basis (queue).  This method moves the specified user
  1833. //                  object to the front of the line so to speak.  This
  1834. //                  can be helpful when a user interface is being
  1835. //                  updated dynamically through IDiskQuotaControlEvent
  1836. //                  notifications.
  1837. //
  1838. //          Arguments:
  1839. //              pUser - Reference to user object to be promoted.
  1840. //
  1841. //          Returns: Nothing.
  1842. //
  1843. //          Errors:  See IDiskQuotaControl::GiveUserNameResolutionPriority
  1844. //
  1845. //
  1846. //      ShutdownNameResolution
  1847. //
  1848. //          Desc:   The SID-Name resolver runs on a background thread to 
  1849. //                  translate user security IDs to user names.  When a quota 
  1850. //                  control object is destroyed, this thread automatically 
  1851. //                  terminates.  In situations where you're finished 
  1852. //                  with the quota control object and it is not be ready to be 
  1853. //                  destroyed (i.e. other open ref counts), this method may be 
  1854. //                  called to shut down the background thread before the object
  1855. //                  is destroyed.  Note that asynchronous name resolution will 
  1856. //                  also cease once the thread terminates.  A subsequent call
  1857. //                  to CreateEnumUsers, AddUserSid, AddUserName, FindUserSid or
  1858. //                  FindUserName may re-create the resolver thread.
  1859. //      
  1860. //          Arguments: None.
  1861. //
  1862. //          Returns : Nothing.
  1863. //
  1864. //          Errors: None.
  1865. //
  1866. //
  1867. // ----------------------------------------------------------------------------
  1868. // IID_DIDiskQuotaUser - Disk Quota user entry object.
  1869. //
  1870. // This interface represents a user entry in a volume's quota information.
  1871. // It implements much the same functionality as the vtable interface 
  1872. // IDiskQuotaUser.  Disk Quota user objects can only be created through
  1873. // a Disk Quota controller object (enumeration, AddUser, FindUser etc).
  1874. //
  1875. // Properties:
  1876. //
  1877. //      DomainName (read only)
  1878. //
  1879. //          Desc:   The domain name for the user's account.
  1880. //
  1881. //          Type:   BSTR
  1882. //
  1883. //          Domain: Windows NT network domain names.
  1884. //
  1885. //      AccountName (read only)
  1886. //
  1887. //          Desc:   The account name for the user's account.
  1888. //
  1889. //          Type:   BSTR
  1890. //
  1891. //          Domain: Windows NT network account names.
  1892. //
  1893. //      Name (read only)
  1894. //
  1895. //          Desc:   The "friendly" name for the user's account.
  1896. //
  1897. //          Type:   BSTR
  1898. //
  1899. //          Domain: Whatever string is assigned to the account.
  1900. //
  1901. //      QuotaThreshold
  1902. //
  1903. //          Desc:   The user's quota warning threshold.
  1904. //
  1905. //          Type:   double
  1906. //
  1907. //          Domain: Value expressed in bytes.
  1908. //
  1909. //      QuotaThresholdText (read only)
  1910. //
  1911. //          Desc:   User's threshold value formatted as a decimal number
  1912. //                  and appended with a units suffix.
  1913. //
  1914. //          Type:   BSTR
  1915. //
  1916. //          Domain: i.e. "10.5 MB"
  1917. //                       "No Limit" if unlimited.
  1918. //
  1919. //      QuotaLimit
  1920. //
  1921. //          Desc:   The user's quota limit.
  1922. //
  1923. //          Type:   double
  1924. //
  1925. //          Domain: Value expressed in bytes.
  1926. //
  1927. //      QuotaLimitText (read only)
  1928. //
  1929. //          Desc:   User's limit value formatted as a decimal number
  1930. //                  and appended with a units suffix.
  1931. //
  1932. //          Type:   BSTR
  1933. //
  1934. //          Domain: i.e. "10.5 MB"
  1935. //                       "No Limit" if unlimited.
  1936. //
  1937. //      AccountStatus (read only)
  1938. //
  1939. //          Desc:   Status of the user's account information.
  1940. //
  1941. //          Type:   AccountStatusConstants (enumeration)
  1942. //
  1943. //          Domain: dqAcctResolved    (0) - Name information available
  1944. //                  dqAcctUnavailable (1) - Can't get name information
  1945. //                  dqAcctDeleted     (2) - Account has been deleted
  1946. //                  dqAcctInvalid     (3) - Account is invalid
  1947. //                  dqAcctUnknown     (4) - Account is not known
  1948. //                  dqAcctUnresolved  (5) - Name information not yet resolved
  1949. //
  1950. // Methods:
  1951. //
  1952. //      Invalidate
  1953. //
  1954. //          Desc:   Invalidates the information cached in the user object.
  1955. //                  Following a call to Invalidate, the next call for 
  1956. //                  a quota-related property refreshes the information from
  1957. //                  the NTFS volume.
  1958. //
  1959. //          Arguments: None.
  1960. //
  1961. //          Returns: Nothing.
  1962. //
  1963. //          Errors: None. Always returns S_OK.
  1964. //
  1965. //
  1966. // ----------------------------------------------------------------------------
  1967. // IID_DIDiskQuotaControlEvents - Disk Quota Controller Events source.
  1968. //
  1969. // This interface is the default source interface for the DiskQuota
  1970. // ActiveX component.  It is not implemented in the DiskQuota object.  It
  1971. // merely describes the interface that must be implemented by clients if they
  1972. // are to receive user-name-update notifications for asynchronous resolution
  1973. // of user object name information.
  1974. //
  1975. // Properties:  None.
  1976. //
  1977. // Methods:
  1978. //
  1979. //      OnUserNameChanged
  1980. //
  1981. //          Desc:   Called by the DiskQuota object whenever an asynchronous
  1982. //                  name resolution operation has completed for a single user
  1983. //                  object.  This notification indicates that the user's
  1984. //                  DomainName, AccountName and Name properties contain
  1985. //                  valid information.
  1986. //                  It is not necessary to call Release() on this pointer.
  1987. //                  The DiskQuotaControl object controls the lifetime of the
  1988. //                  user object.
  1989. //
  1990. //          Arguments:
  1991. //              pUser - Reference to the user object associated with the event.
  1992. //
  1993. //          Returns: Ignored by DiskQuota object.
  1994. //
  1995. //          Errorrs: Ignored by DiskQuota object.
  1996. //
  1997. //
  1998.  
  1999. #endif // __DSKQUOTA_H
  2000.