COM API definition and examples

Back to Index

Table of contents

• Understanding the API specifics
• New in WinQuota 2.5
• The WinQuota API reference
  • WinQuotaItem structure
  • WinQuota interface
    • Methods to navigate through quota settings
    • Method to calculate directory sizes
    • Methods to change quota settings
    • Other methods
• Listening quota settings
• Modifying quota settings

Important note: please, read the main principles of WinQuota access paradigm; it will provide you introduction to the technical details and will show the more efficient way to manage WinQuota settings carefully.

Understanding the API specifics

As it works on any type of media, such as hard disk partitions, removable or network files, WinQuota has no central storage of quota settings. All quota settings are stored nearby with data being managed into extended file attributes. So to see quota settings it is necessary to know precisely to which catalogue they were applied.

WinQuota API provides you an efficient way to pick out all quota settings applied to the directory you've chosen; so you don't need to look for all suitable quota settings yourself across directory hierarchy. For example, if you've applied the quota settings to

• ...
• c:\test
• c:\test\john
• c:\test\mary
• c:\test\john\webapps\john-site
• ...

you don't need to analyze this structure yourself; just pick out all quota settings for directory you need this time. For example, the request to c:\test\john\webapps\john-site will cover the hierarchy, and will return the three records:

• c:\test\john\webapps\john-site
• c:\test\john
• c:\test,

So you'll get the directory, the limits, and the account for which quota limits were set.

The API is safe and you are able to apply it to directories placed deeply in the hierarchy; for example, the parameter

• c:\test\john\webapps\john-site\htdocs\winquota\documentation\COM API\

will return the exact result listed above. In other case, the API is able to handle directories without quota limitations; you'll see 0 as the quota limits count and NULL if you'll try to get the item anyway.

New in WinQuota 2.5

The WinQuota API were redesigned a bit (see reference), and now typical calls are

dim api, item, path dim i, j, k, count, qcount set api = CreateObject("WinQuota.API.2") count = api.getPrecachedPathSize() for i = 0 to count - 1     path = api.getPrecachedPathItem(i)     qcount = api.getQuotaListSize(path)     for j = 0 to qcount - 1         set item = api.getQuotaListItem(path, j)         WScript.Echo path & vbTab & item.hardLimit & "K" & vbTab & item.occupied & "K" & vbTab & item.account     next next set api = Nothing set item = Nothing

There is a small example that shows whole list of quota settings at your system (see note about precached folders below).

The following changes in API were made:

• Since version 2.5.1, WinQuota Control Panel was introduced. It has its' own cache of all folders (directories) used for quota limits; all of them are handled to improve performance of WinQuota Control Panel. To make this cache from scratch, please use documentation on WinQuota Control Panel; it is created at the time of looking existing quota settings.
  
  This issue is not mandatory; but you'll find it useful.
  
  
• WinQuota COM API also has a way to enumerate directories from this cache (every change like add/update/remove quota settings through API, through WinQuota Control Panel, or via Windows explorer extensions, also causes cache update to make it consistent). So at the example above you can see the following lines:

  count = api.getPrecachedPathSize() for i = 0 to count - 1     path = api.getPrecachedPathItem(i)

  There is a simple way to enumerate all the directories with quota settings were applied in WinQuota 2.5 (see documentation to retrieve changes made in previous versions). We're not using collections for this case, providing two functions instead.

  qcount = api.getQuotaListSize(path)     for j = 0 to qcount - 1         set item = api.getQuotaListItem(path, j)

  Similar technique is used to enumerate quota settings for dedicated path. Please, read documentation carefully; in case you have settings for certain directory, and for its parent directory, you'll get both settings of parent directory and for this directory while enumerating it.

• The structure WinQuotaItem was replaced with OLE Automation object with the same properties and with the name CWinQuotaItem (and appropriate interface being defined in type library). It was reached due to VBScript cannot operate with 64 bit long values (marked as __int64); and we made two kind of properties named:

  • hardLimit64, softLimit64, occupied64 - as 64bit long
  • hardLimit, softLimit, occupied - as long.
  
  

  The major differences are:

  • values with suffix '64' works with bytes, and limited to 64TB.
  • values without suffix '64' works with kilobytes, and limited to 2TB.

  The values with '64' suffix are applicable through C++, C#, J# and other programming languages; and if it is possible we suggest using these exact values.

  But for VBScript and JScript, you should use values without suffix instead. In this case you'll see the granularity of kilobytes (for all operations, including update), but it mostly useful for maintenance and quick reports.

The WinQuota API reference

The IDL description of WinQuota COM API is stated below:

    interface IWinQuotaItem : IDispatch
    {
        [propput] HRESULT account([in] BSTR bs);
        [propget] HRESULT account([out, retval] BSTR* bs);
        [propput] HRESULT path([in] BSTR bs);
        [propget] HRESULT path([out, retval] BSTR* bs);
        [propput] HRESULT hardLimit([in] long bs);
        [propget] HRESULT hardLimit([out, retval] long* bs);
        [propput] HRESULT softLimit([in] long bs);
        [propget] HRESULT softLimit([out, retval] long* bs);
        [propput] HRESULT occupied([in] long bs);
        [propget] HRESULT occupied([out, retval] long* bs);
        [propput] HRESULT hardLimit64([in] __int64 bs);
        [propget] HRESULT hardLimit64([out, retval] __int64* bs);
        [propput] HRESULT softLimit64([in] __int64 bs);
        [propget] HRESULT softLimit64([out, retval] __int64* bs);
        [propput] HRESULT occupied64([in] __int64 bs);
        [propget] HRESULT occupied64([out, retval] __int64* bs);
    };

There is the main data structure, formerly known as tagWinQuotaItem structure in previous versions of API.

For causal usage, you have hardLimit64, softLimit64, occupied64 fields; all of them are read write. It provides high density in bytes since 1 byte to 64TB. Unfortunately, these fields are not available in scripts; so you have the “mirrors” if these fields to long values; the hardLimit, softLimit, occupied fields are operational in kilobytes and assumes values from 1K to 2TB.

• hardLimit64, softLimit64, occupied64 - as 64bit long
• hardLimit, softLimit, occupied - as long.

The major differences are:

• values with suffix '64' works with bytes, and limited to 64TB.
• values without suffix '64' works with kilobytes, and limited to 2TB.

All these fields are available as properties, so you are able to operate them like:

WScript.Echo path & vbTab & item.hardLimit & "K" & vbTab & item.occupied & "K" & vbTab & item.account

The WinQuotaItem structure describes the main WinQuota structure with all important values to be managed; all operations are carried out through this structure. It is rather simple. It contains only strings belonging to quota limitations, and counters.

The new interface is available through new name “WinQuota.API.2” and contains the following methods:

    interface IWinQuota : IDispatch
    {
        HRESULT createEmptyItem([out, retval] IWinQuotaItem** item);
        HRESULT getPrecachedPathSize([out, retval] int* count);
        HRESULT getPrecachedPathItem([in] int index, [out, retval, string] BSTR* path);
        HRESULT getQuotaListSize([in, string] BSTR path, [out, retval] int* count);
        HRESULT getQuotaListItem([in, string] BSTR path, [in] int index, [out, retval] IWinQuotaItem** item);
        HRESULT getQuotaListIndex([in, string] BSTR path, [in] IWinQuotaItem* item, [out, retval] int* index);
        HRESULT setQuotaItem([in, string] BSTR path, [in] int index, [in] IWinQuotaItem* item);
        HRESULT dropQuotaItem([in, string] BSTR path, [in] int index);
        HRESULT addQuotaItem([in, string] BSTR path, [in] IWinQuotaItem* item);
        HRESULT removeQuotaList([in, string] BSTR path);
        HRESULT getRealSize([in, string] BSTR path, [out, retval] __int64* blength);
    }

These methods are available as the following prototypes in your scripts and programs:

	IWinQuotaItem createEmptyItem()
	int getPrecachedPathSize()
	string getPrecachedPathItem(int index)
	int getQuotaListSize(string path)
	IWinQuotaItem getQuotaListItem(string path, int index)
	int getQuotaListIndex(string path, IWinQuotaItem whatSearch)
	setQuotaItem(string path, int index, IWinQuotaItem whatUpdate)
	dropQuotaItem(string path, int index)
	removeQuotaList(string path)
	__int64 getRealSize(string path)

Here is the brief legend of COM API types:

Abbreviation	Description
BSTR	Usual string
__int64	64bit unsigned integer
int	32bit signed integer

Please, apply for your language reference to understand how to operate with these values safely.

IWinQuotaItem

    interface IWinQuotaItem : IDispatch
    {
        // Account owns quota limitations. Maybe user, group name or "Anyone".
        [propput] HRESULT account([in] BSTR bs);
        [propget] HRESULT account([out, retval] BSTR* bs);
        // path where quota settings were defined
        [propput] HRESULT path([in] BSTR bs);
        [propget] HRESULT path([out, retval] BSTR* bs);
        // quota hard limit
        [propput] HRESULT hardLimit([in] long bs);
        [propget] HRESULT hardLimit([out, retval] long* bs);
        [propput] HRESULT hardLimit64([in] __int64 bs);
        [propget] HRESULT hardLimit64([out, retval] __int64* bs);
        // quota soft limit
        [propput] HRESULT softLimit([in] long bs);
        [propget] HRESULT softLimit([out, retval] long* bs);
        [propput] HRESULT softLimit64([in] __int64 bs);
        [propget] HRESULT softLimit64([out, retval] __int64* bs);
        // real size were eaten by account 
        [propput] HRESULT occupied([in] long bs);
        [propget] HRESULT occupied([out, retval] long* bs);
        [propput] HRESULT occupied64([in] __int64 bs);
        [propget] HRESULT occupied64([out, retval] __int64* bs);
    };

The WinQuotaItem structure contains the next fields:

Field name	Type	Description
account	BSTR	It is the subject quota limits were set to. It may be “Anyone” (or NULL; what is the same) to specify quota limits for all users. For setQuotaItem and addQuotaItem functions this field is used for specifying users or groups quotas will be set to. To be sure that all names will be recognized correctly, please, specify them in full form, e.g. DOMAIN\user or DOMAIN\group. For local groups and names you can use computer name as domain name, or just use the brief form.
path	BSTR	It is the exact path to quota limitations; you can use it to find the path that was used to specify quota settings, for example. For setXXX routines you need to keep this path the same as you received it by getXXX functions; otherwise your request will be declined.
hardLimit hardLimit64	long __int64	It is the hard quota limit, in bytes. The large integer type allows you to manage any 64bit values.
softLimit softLimit64	long __int64	It is the soft quota limit, in bytes. The large integer type allows you to manage any 64bit values. For setQuotaItem and addQuotaItem functions hard limit settings should be higher or equal to soft limits. Otherwise, the hard limit will be set by default to the soft limit value. Specify the soft limit value equal to the hard limit if you don't need to see notifications for this directory.
occupied occupied64	long __int64	This counter indicates how much space (in bytes) is occupied. Any file operation in an appropriate directory, including file removal, file renaming and other, may lead to changing of this value For setXXX functions this value is unused and is ignored.

WinQuota interface

    interface IWinQuota : IDispatch
    {
        HRESULT createEmptyItem([out, retval] IWinQuotaItem** item);
        HRESULT getPrecachedPathSize([out, retval] int* count);
        HRESULT getPrecachedPathItem([in] int index, [out, retval, string] BSTR* path);
        HRESULT getQuotaListSize([in, string] BSTR path, [out, retval] int* count);
        HRESULT getQuotaListItem([in, string] BSTR path, [in] int index, [out, retval] IWinQuotaItem** item);
        HRESULT getQuotaListIndex([in, string] BSTR path, [in] IWinQuotaItem* item, [out, retval] int* index);
        HRESULT setQuotaItem([in, string] BSTR path, [in] int index, [in] IWinQuotaItem* item);
        HRESULT dropQuotaItem([in, string] BSTR path, [in] int index);
        HRESULT addQuotaItem([in, string] BSTR path, [in] IWinQuotaItem* item);
        HRESULT removeQuotaList([in, string] BSTR path);
        HRESULT getRealSize([in, string] BSTR path, [out, retval] __int64* blength);
    }

Every WinQuota API function is totally COM+ compliant and returns standard error codes.

Methods to navigate quota settings

HRESULT getQuotaListSize(in string path,out int count)

It is a safe and fast way to determine how many quota settings are set for specified directory (see explanations above).

Parameter	Type	Description
path	in string	It is the path to the directory to which the method will be applied.
count	out int	The number of quota settings items found as the result of method execution.

HRESULT getQuotaListIndex(in string path, in IWinQuotaItem* whatSearch, out int index)

It is a safe and fast way to find appropriate index by existing quota settings in specified directory (see explanations above).

Parameter	Type	Description
path	in string	It is the path to the directory to which the method will be applied.
item	in IWinQuotaItem*	The quota settings items to be found.
index	out int	The index in quota settings list as result of method execution. It returns values from 0..getQuotaListSize(path) as valid index, or -1 otherwise.

HRESULT getQuotaListItem(in string path, in int index, inout WinQuotaItem)

It is the generalized way to get quota list referred to directory you requested at “path”. This function collects all quota items for specified directory and for parent directories upper hierarchic until the top level.

Parameter	Type	Description
path	in string	It is the path to the directory to which the method will be applied.
index	in int	It is an index in the WinQuota items array. The value limits are from 0 inclusive to the number the previous function returned exclusive.
item	inout WinQuotaItem	It is the resulting structure. If request can not be processed due to various reasons the result will be NULL.

Methods to calculate directory sizes

HRESULT getRealSize(in string path, out __int64 length)

It is the utility function to calculate the whole size of the specified directory including sub-directories. So, if you'll specify directory 'c:\test', the complete directory size will be returned. If an incorrect directory is specified or any other error caused, zero will be returned with an appropriate error code.

Note: The processing of this function may take several minutes.

Parameter	Type	Description
path	in string	It is the directory which size you need to calculate.
length	out __int64	It is the size of a directory with all files inside that is occupied. The returning value is 64bit.

Methods to change quota settings

HRESULT setQuotaItem (in string path, in int index, in WinQuotaItem) It is the generalized way to update quota settings list referred to directory you requested by "path". Incorrect values not referring to an appropriate getQuotaListItem call will fail as well as out of range indexes. Please, use other functions to add new or remove existing quota settings. The updates will be applied immediately if setQuotaItem succeeds.

HRESULT addQuotaItem(in string path, in WinQuotaItem)

It is the generalized way to add new items to the quota list referred to the directory you requested at "path". The path specified in this function matches the exact directory being used to store quota settings; the appropriate path in WinQuotaItem structure must be the same as the path specified as the first parameter. Incorrect values not referred to an appropriate getQuotaListItem call will fail as well as out of range indexes. The updates will be applied immediately if addQuotaItem succeeds.

Parameter	Type	Description
path	in string	It is a directory which indicates the exact path to a new quota item
item	in WinQuotaItem	It is the structure to be added (NULL is not applicable). All limitations for setQuotaItem() are also applicable to this function.

HRESULT dropQuotaItem(in string path, in int index)

It is the way to remove an item from the numerous quota list referred to directory you requested at "path". The out of range indexes will fail. The updates will be applied immediately as dropQuotaItem succeeds.

Parameter	Type	Description
path	in string	It is the path to the directory to which the method will be applied.
index	in int	It is a number of quota settings items you need to modify; negative or out of bounds indexes will lead to ignoring of other parameters.

HRESULT removeQuotaList(in string path)

It is a way to remove the whole quota list at the specified directory. Unlike the other functions, removeQuotaList() operates with an exact path specified. Please, use getQuotaListItem() to get the exact knowledge of quota list location. No operation will be executed if the path specified contains no quota settings items. The updates will be applied immediately as removeQuotaList succeeds.

Parameter	Type	Description
path	in string	It is the path to the directory to which the method will be applied.

Other methods

HRESULT createEmptyItem(out IWinQuotaItem** item)

It is the utility function to create empty IWinQuotaItem objects. Sometimes you'll need these objects for search and for add operations.

Parameter	Type	Description
item	out IWinQuotaItem**	The newly created object.

Listening quota settings

The typical example is described below:

' There is sample script to cover all quota limits ' (C) 2006 WinQuota LLC ' There are demonstrational materials and you can use it at your own risk. ' Defining variables to be used dim api, item, path dim i, j, k, count, qcount ' Attaching to WinQuota API version 2 set api = CreateObject("WinQuota.API.2") ' Enumerating all folders were used to specify quota settings ' (may not be up to date! Full scan on your file system is more ' accurate but time consuming operation) count = api.getPrecachedPathSize() ' For each path we discovered we looking for quota settings for i = 0 to count - 1     path = api.getPrecachedPathItem(i) ' For each path with settings we discovering all settings step by step     qcount = api.getQuotaListSize(path)     for j = 0 to qcount - 1 ' Set clause is required as OLE object will be returned         set item = api.getQuotaListItem(path, j) ' Printing an item. ' Important issue: all counters are seein in kilobytes         WScript.Echo path & vbTab & item.hardLimit & "K" & vbTab & item.occupied & "K" & vbTab & item.account     next next ' Marking all resources to be unused set api = Nothing set item = Nothing

This way is applicable since WinQuota 2.5. With old style, such functions are not available and you need to specify exact directory with the settings yourself.

' There is sample script to cover all limits in a particular directory ' (C) 2008 WinQuota LLC ' These are demonstrational materials and you can use it at your own risk. ' Defining variables to be used dim api, item, path dim j, qcount ' Attaching to WinQuota API version 2 set api = CreateObject("WinQuota.API.2") ' Choosing directory to be used path = "C:\Foo" ' For path we discovering all settings step by step qcount = api.getQuotaListSize(path) for j = 0 to qcount - 1 ' Set clause is required as OLE objkect will be returned     set item = api.getQuotaListItem(path, j) ' Printing an item. ' Important issue: all counters are seein in kilobytes     WScript.Echo path & vbTab & item.hardLimit & "K" & vbTab & item.occupied & "K" & vbTab & item.account next ' Marking all resources to be unused set api = Nothing set item = Nothing

These examples are well-documented and easy to understand.

Modifying quota settings

The way is quite similar to examples above; so now we demonstrate a way to add new settings.

' There is a sample script to add new quota limit to a specific directory ' (C) 2008 WinQuota LLC ' These are demonstrational materials and you can use it at your own risk. ' Defining variables to be used dim api, item, path dim j, qcount ' Attaching to WinQuota API version 2 and creating empty WinQuotaItem object set api = CreateObject("WinQuota.API.2") set item = api.createEmptyItem() ' Filling with specific data we need item.account = "Anyone" item.hardLimit = 10240 ' 10 MB; all values are operated in kilobytes. item.softLimit = 10240 ' 10 MB; se hardLimit64 if you need exact values in bytes item.occupied = 0 ' it will be unused item.path = "c:\test" ' We should specify the same folder in item.path and here; ' otherwise runtime error will be raised. api.addQuotaItem("c:\test", item) ' Marking all resources to be unused set api = Nothing set item = Nothing