dskquota.h

vc6.0完整版

// IDiskQuotaControl::AddUserSid ----------------------------------------------
// IDiskQuotaControl::AddUserName ---------------------------------------------
//
//      Adds a new quota entry on the volume for a given user.  Note that 
//      NTFS automatically creates a user quota entry when a user first writes
//      to the volume.  Automatically created user entries are assigned the
//      volume's default threshold and limit values.  This function allows
//      you to create a user quota entry before a user has written information
//      to the volume.  One reason for doing this might be to pre-assign
//      a threshold or limit value different than the volume defaults.
//
//      Arguments:
//
//          pUserSid - Address of buffer containing user's security ID (SID).
//
//          pszDomain - Address of user's domain name string.
//
//          pszName - Address of user's account name string.
//              If pszDomain points to a blank string, it is assumed that
//              pszName points to a fully-qualified "Domain\Account" string.
//
//          fNameResolution - Flag indicating how the user's account information
//              is to be obtained.  The volume's quota information contains
//              only security IDs for identifying users.  The user's account 
//              information such as domain name, account name and full user 
//              name must be obtained from the network domain controller, or 
//              the local machine if the machine is not networked.  This 
//              information may be obtained synchronously, asynchronously or 
//              not at all.
//              Specify one of the following values in this argument:
//
//              DISKQUOTA_USERNAME_RESOLVE_NONE - Do not resolve user account
//                  information.
//
//              DISKQUOTA_USERNAME_RESOLVE_SYNC - Resolve user account 
//                  information synchronously.  AddUser will not return until 
//                  the information has been resolved.  If the information
//                  is present in the disk quota SID cache, the return of
//                  information will be immediate.  If not cached, the
//                  function can take a considerable amount of time to 
//                  locate the user's information.  This period is dependent
//                  upon many network-related factors.  It can be on the
//                  order of several seconds.
//
//              DISKQUOTA_USERNAME_RESOLVE_ASYNC - Resolve user account 
//                  information asynchronously.  AddUser will return 
//                  immediately.  The caller must implement 
//                  IDiskQuotaUserEvents to receive notification when the 
//                  account information is available.  This option causes
//                  the user object to be placed on a queue.  This queue
//                  is serviced by a thread dedicated to obtaining account
//                  information for disk quota users on the volume. If the 
//                  information has been cached from a previous request,
//                  the notification occurs as soon as the object is serviced.
//                  If the information is not cached, the thread obtains
//                  the information from the network domain controller and
//                  then notifies IDiskQuotaUserEvents that the operation
//                  is complete.
//
//          ppUser - Address of IDiskQuotaUser pointer variable to receive
//              the interface pointer of the newly created quota user object.
//
//
//      Returns:
//
//          SUCCESS            - Success.
//          E_OUTOFMEMORY      - Insufficient memory.
//          S_FALSE            - User already exists.  Not added.
//          E_POINTER          - Pointer argument was NULL.
//          DQC_E_USER_UNKNOWN - User name provided is unknown.
//
//
// IDiskQuotaControl::FindUserSid ---------------------------------------------
//
//      Locates a specific user entry in the volume's quota information.
//      The user's security ID (SID) is used as the search key.
//
//      Arguments:
//
//          pUserSid - Address of buffer containing user's security ID (SID).
//
//          fNameResolution - Flag indicating how the user's account information
//              is to be resolved.  See description in AddUser for details.
//
//          ppUser - Address of IDiskQuotaUser pointer variable to receive
//              the interface pointer of the quota user object for the user.
//
//      Returns:
//          NOERROR             - Success.
//          E_FAIL              - User not found in volume's quota information.
//          E_POINTER           - Either pUserSid or ppUser was NULL.
//          E_OUTOFMEMORY       - Insufficient memory.
//          DQC_E_INVALID_SID   - SID pointed to by pUserSid is invalid.
//          DQC_E_ACCESS_DENIED - No READ access to quota information.
//
//                   >>>>>>>>> IMPORTANT NOTE <<<<<<<<<
//
//        This method will return a user object even if there is no quota
//        record for the user in the quota file.  While that may sound
//        strange, it is consistent with the idea of automatic user addition
//        and default quota settings.  If there is currently no quota entry
//        for the requested user, and the user would be added to the quota
//        file if they were to request disk space, the returned user object
//        will have a quota threshold and limit equal to the volume defaults.
//
//
// IDiskQuotaControl::FindUserName --------------------------------------------
//
//      Locates a specific entry in the volume's quota information.
//      The user's domain and account name are used as the search key.  
//      This method can take some time as it may need to resolve the name to 
//      a security ID.  See note for FindUserSid (above) concerning behavior
//      when an entry for the user does not exist.
//
//      Arguments:
//
//          pszDomain - Address of buffer containing user's domain name string.
//
//          pszName - Address of buffer containing user's account name string.
//
//          ppUser - Address of IDiskQuotaUser pointer variable to receive
//              the interface pointer of the quota user object for the user.
//
//          fNameResolution - Flag indicating how the user's account information
//              is to be resolved.  See description in AddUser for details.
//
//      Returns:
//          NOERROR             - Success.
//          E_FAIL              - User not found in volume's quota information.
//          E_POINTER           - Either pUserSid or ppUser was NULL.
//          E_OUTOFMEMORY       - Insufficient memory.
//          DQC_E_INVALID_SID   - SID pointed to by pUserSid is invalid.
//          DQC_E_ACCESS_DENIED - No READ access to quota information.
//          DQC_E_NO_SID_MAPPING- Could not map account name to a security ID.
//
//
// IDiskQuotaControl::DeleteUser ----------------------------------------------
//
//      Removes a user entry from the volume's quota information file if the 
//      user's charged quota amount is 0 bytes.  This function doesn't actually
//      remove the quota entry from the volume.  It marks the entry for 
//      deletion.  NTFS performs the actual deletion at a later point in time.
//      Following a call to DeleteUser, the IDiskQuotaUser interface is still
//      active.  This function does not delete the user object from memory.
//      You must still call IUnknown::Release() on the user object to
//      release it.
//
//      Arguments:
//
//          pUser - Pointer to IDiskQuotaUser interface of quota user who's
//              quota record is marked for deletion.
//
//      Returns:
//      
//          NOERROR              - Success.
//          E_POINTER            - pUser argument was NULL.
//          E_FAIL               - Error marking entry for deletion.
//          DQC_E_USER_HAS_FILES - Couldn't delete.  User still has file(s) on
//                                 the volume.
//          DQC_E_ACCESS_DENIED  - Insufficient access.
//
//
// IDiskQuotaControl::CreateEnumUsers -----------------------------------------
//
//      Creates an enumerator object for enumerating quota users on the volume.
//      The object created implements the IEnumDiskQuotaUsers interface.  
//      The object created supports the standard OLE IEnumXXXX functions.
//
//      Arguments:
//
//          rgpUserSids - Array of security ID (SID) pointers representing the
//              user objects to be included in the enumeration.  If this 
//              value is NULL, all user entries are enumerated.
//
//          cpSids - Number of items in the rgpUserSids array.  Ignored if 
//              rgpUserSids is NULL.
//
//
//          ppEnum - Address of IEnumDiskQuotaUsers pointer variable to receive
//              the address of the new enumerator.
//
//          fNameResolution - Flag indicating how the account information for
//              enumerated users is to be resolved.  See description in
//              AddUser for details.
//
//      Returns:
//          NOERROR             - Success.
//          E_POINTER           - ppEnum argument is NULL.
//          E_OUTOFMEMORY       - Insufficient memory.
//          DQC_E_ACCESS_DENIED - Insufficient access rights.
//
//
// IDiskQuotaControl::CreateUserBatch -----------------------------------------
//
//      Creates a batching object for optimizing updates to the quota settings
//      of multiple users simultaneously. See IDiskQuotaUserBatch for details.
//
//      Arguments:
//
//          ppBatch - Address of IDiskQuotaUserBatch pointer variable to 
//              receive the IDiskQuotaUserBatch interface pointer.
//
//      Returns:
//
//        NOERROR             - Success.
//        E_POINTER           - ppBatch argument is NULL.
//        E_OUTOFMEMORY       - Insufficient memory to create batch object.
//        DQC_E_ACCESS_DENIED - Insufficient access rights.
//
//
// IDiskQuotaControl::InvalidateSidNameCache ----------------------------------
//
//      Invalidates the contents of the system's SID-Name cache so that 
//      subsequent requests for new user objects (IEnumDiskQuotaUsers::Next,
//      IDiskQuotaControl::FindUserSid and IDiskQuotaControl::FindUserName) 
//      must obtain user names from the network domain controller.  As names 
//      are obtained, they are again cached.
//
//      In general there is no reason to call this method.  It is included to 
//      provide a method for programmatically refreshing the entire SID-name
//      cache.
//
//      Arguments: None.
//
//      Returns:
//
//          NOERROR - Success.
//          E_FAIL  - SID/Name cache not available or couldn't obtain 
//              exclusive lock on cache.
//
//
// IDiskQuotaControl::GiveUserNameResolutionPriority --------------------------
//
//      By default, quota user objects are serviced in the resolution queue in 
//      the order they were placed into the queue.  This function will promote
//      a specified user object to the head of the queue so that it is next in 
//      line for resolution.
//
//      Arguments:
//
//          pUser - Address of user object's IDiskQuotaUser interface.
//
//      Returns:
//
//        NOERROR       - Success.
//        S_FALSE       - Quota user object not in resolver queue.
//        E_UNEXPECTED  - Unexpected error.  Caught an exception or the 
//                        Sid-Name resolver hasn't been created.
//
//
// IDiskQuotaControl::ShutdownNameResolution ----------------------------------
//
//      The SID-Name resolver runs on a background thread to translate
//      user security IDs to user names.  When a quota control object is 
//      destroyed, this thread automatically terminates.  If you have a
//      situation where you're finished with the quota control object and
//      it is not be ready to be destroyed (other open ref counts),
//      this method may be called to shut down the background thread before
//      the object is destroyed.  Note that asynchronous name resolution will 
//      also cease once the thread terminates.  A subsequent call to 
//      CreateEnumUsers, AddUserSid, AddUserName, FindUserSid or FindUserName 
//      may re-create the resolver thread.
//      
//      Arguments: None.
//
//      Returns : Only returns NOERROR.
//
///////////////////////////////////////////////////////////////////////////////
#undef INTERFACE
#define INTERFACE IDiskQuotaControl

DECLARE_INTERFACE_(IDiskQuotaControl, IConnectionPointContainer)
{
    STDMETHOD(Initialize)(THIS_ 
        LPCWSTR pszPath, 
        BOOL bReadWrite) PURE;

    STDMETHOD(SetQuotaState)(THIS_ 
        DWORD dwState) PURE;

    STDMETHOD(GetQuotaState)(THIS_ 
        LPDWORD pdwState) PURE;

    STDMETHOD(SetQuotaLogFlags)(THIS_ 
        DWORD dwFlags) PURE;

    STDMETHOD(GetQuotaLogFlags)(THIS_ 
        LPDWORD pdwFlags) PURE;

    STDMETHOD(SetDefaultQuotaThreshold)(THIS_ 
        LONGLONG llThreshold) PURE;

    STDMETHOD(GetDefaultQuotaThreshold)(THIS_ 
        PLONGLONG pllThreshold) PURE;

    STDMETHOD(GetDefaultQuotaThresholdText)(THIS_
        LPWSTR pszText,
        DWORD cchText) PURE;

    STDMETHOD(SetDefaultQuotaLimit)(THIS_ 
        LONGLONG llLimit) PURE;

    STDMETHOD(GetDefaultQuotaLimit)(THIS_ 
        PLONGLONG pllLimit) PURE;

    STDMETHOD(GetDefaultQuotaLimitText)(THIS_
        LPWSTR pszText,
        DWORD cchText) PURE;

    STDMETHOD(AddUserSid)(THIS_ 
        PSID pUserSid, 
        DWORD fNameResolution,
        PDISKQUOTA_USER *ppUser) PURE; 

    STDMETHOD(AddUserName)(THIS_ 
        LPWSTR pszDomain,
        LPWSTR pszName,
        DWORD fNameResolution,
        PDISKQUOTA_USER *ppUser) PURE; 

    STDMETHOD(DeleteUser)(THIS_ 
        PDISKQUOTA_USER pUser) PURE;

    STDMETHOD(FindUserSid)(THIS_ 
        PSID pUserSid, 
        DWORD fNameResolution,
        PDISKQUOTA_USER *ppUser) PURE;

    STDMETHOD(FindUserName)(THIS_ 
        LPCWSTR pszDomain, 
        LPCWSTR pszName, 
        PDISKQUOTA_USER *ppUser) PURE;

    STDMETHOD(CreateEnumUsers)(THIS_ 
        PSID *rgpUserSids, 
        DWORD cpSids, 
        DWORD fNameResolution,
        PENUM_DISKQUOTA_USERS *ppEnum) PURE;

    STDMETHOD(CreateUserBatch)(THIS_