COM API definition and examples
Back to Index
Table of contents
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.
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.
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 IDL description of WinQuota COM API is stated below:
/*
Here is the main quota information structure that describes one quota limit item. Usually many items are defined.
*/
library WinQuota
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.
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.
|
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.
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. |
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. |
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.
Parameter |
Type |
Description |
path |
in string |
It is a directory which is under the possible quota limitations. |
index |
in int |
It is a number of quota settings lists you need to modify; negative or out of bounds indexes will lead to ignoring of other parameters. |
item |
in WinQuotaItem |
It is the structure to be modified (NULL is not applicable). |
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. |
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. |
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.
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
|
|