CBFS Connect 2020 .NET Edition

Questions / Feedback?

QueryQuotas Event

Fires when the OS needs to read quota information.

Syntax

public event OnQueryQuotasHandler OnQueryQuotas;

public delegate void OnQueryQuotasHandler(object sender, CbfsQueryQuotasEventArgs e);

public class CbfsQueryQuotasEventArgs : EventArgs {
  public IntPtr SID { get; }
  public int SIDLength { get; }
  public int Index { get; }
  public bool QuotaFound { get; set; }
  public long QuotaUsed { get; set; }
  public long QuotaThreshold { get; set; }
  public long QuotaLimit { get; set; }
  public IntPtr SIDOut { get; }
  public int SIDOutLength { get; }
  public IntPtr EnumerationContext { get; set; }
  public int ResultCode { get; set; }
}
Public Event OnQueryQuotas As OnQueryQuotasHandler

Public Delegate Sub OnQueryQuotasHandler(sender As Object, e As CbfsQueryQuotasEventArgs)

Public Class CbfsQueryQuotasEventArgs Inherits EventArgs
  Public ReadOnly Property SID As IntPtr
  Public ReadOnly Property SIDLength As Integer
  Public ReadOnly Property Index As Integer
  Public Property QuotaFound As Boolean
  Public Property QuotaUsed As Long
  Public Property QuotaThreshold As Long
  Public Property QuotaLimit As Long
  Public ReadOnly Property SIDOut As IntPtr
  Public ReadOnly Property SIDOutLength As Integer
  Public Property EnumerationContext As IntPtr
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the OS needs to read quota information, set during earlier SetQuotas events, for one or more security identifiers (SIDs).

This event only needs to be handled if the UseDiskQuotas property is enabled. Quota information is read by the OS in one of two ways; to handle this event properly, applications must be able to handle both kinds of requests by doing the following:

  1. When the OS needs a specific SID's quota information, SID will point to a memory buffer which contains that SID (in binary form, with length SIDLength).
    • If the application has a quota stored for the specified SID, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit.
    • If the application does not have quota information stored for the SID, set QuotaFound to false and leave the other parameters unchanged.
    • For such requests, Index is always -1, no SIDOut buffer is available, and SIDOutLength is 0.
  2. When the OS needs all of the quota information the application has stored, this event fires with Index set to 0 first, then continues to fire with increasing indices until all quotas have been returned.
    • For each quota the application has stored, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit. Return the SID associated with the quota by copying it, in binary form, to the memory buffer pointed to by SIDOut. The capacity of the SIDOut buffer is specified by SIDOutLength.
    • If there are more quotas to return, set QuotaFound to false and leave the other parameters unchanged.
    • For such requests, no SID buffer is available, and SIDLength is 0.

Both this event and SetQuotas cause a quota enumeration to be started; the CloseQuotasEnumeration event will fire when the OS has finished reading quota information (this applies for both of the cases described above).

Descriptions of the QuotaUsed, QuotaThreshold, and QuotaLimit parameters can be found in the Windows API's DISKQUOTA_USER_INFORMATION structure documentation.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 .NET Edition - Version 20.0 [Build 8348]