Northern Storage Suite includes a Component Object Model Application Program Interface for the quota component of the solution. Through the Quota Server COM API administrators and developers are able to achieve high-levels of integration between quota policies and existing user management or reporting processes.

This article is written with the assumption that the reader is familiar with programming languages and in working with COM API tools.

The Northern Quota Server COM API consists of a single DLL called QSComApi.dll. This dynamic link-library file is by default installed into the directory Northern\Storage Suite\QS. The Northern Storage Suite installer registers this DLL on any management host where NSS is installed.

If you wish to use the COM API on your local desktop then you must begin by copying and registering the relevant dll files on your local machine. The steps described in KB - 2875 are applicable (taken from the perspective that 'remote machine' is your desktop machine). 

It is assumed that the relevant preparations have been made in your programming tool; referencing the api, adding include directives, etc.

The Northern Quota Server COM API is organized around six user classes:

• QSComApiSession
• QSComApiQuotaItem
• QSComApiTemplateItem
• QSComApiReportItem
• QSComApiQuotaServerItem
• QSComApiPermissionItem

You do not create instances of those classes directly, instead you access them through the following interface Collection classes:

• IQSComApiQuotaItemCollection
• IQSComApiTemplateItemCollection
• IQSComApiReportItemCollection
• IQSComApiQuotaServerItemCollection
• IQSComApiPermissionItemCollection

The session is the starting point of any operation with the Northern Quota Server COM API. From the session, you can connect to a server and get access to any of the collections. In those collections you can then access the individual items. For instance, to get a quota item, you need to create the session, get the quota item collection from the session, and then get the individual item from that collection. (Please note that there is no interface class for theQSComApiSession.)

There is also another class, TTCollection, which is the base class for the collection class and isnot meant to be used on its own. There are also several enums which are used to specify options that can be seen in the Northern Quota Server client.

The starting point of any operations with the Northern Quota Server COMAPI is the session, represented by the QSComApiSession class. Before you can do anything, you need to:

1. Create an instance of the QSComApiSession class
2. Connect that instance to a Northern Quota Server server

Using Visual Basic
' Create a new session object
Dim QSS As New QSCOMAPILib.QSComApiSession

' Set Server
QSS.Server = “my QS server name with no backslash”

Using C++
using namespace QSCOMAPILib;

// Create a new session object and acquire a pointer to it.
IQSComApiSessionPtr * pSessionSmartPtr;
IQSComApiSession * pSession;

// first instantiate the smart pointer, which wraps CoCreateInstance etc.
pSessionSmartPtr = new IQSComApiSessionPtr(__uuidof(QSComApiSession));

// now, let's get a pointer to the interface we want to use.
pSession = pSessionSmartPtr->GetInterfacePtr();

// Set Server
pSession->PutServer( _bstr_t( “my QS server name with no backslash” ) );

Using C#
//Create a new session object
QSCOMAPILib.QSComApiSession session = new QSCOMAPILib.QSComApiSession();

//Set Server
session.Server = "my QS server name with no backslash";

Using Powershell
#Create a new session object
$session = New-Object -ComObject QSComApi.QSComApiSession

#Set Server
$session.server = "my QS server name with no backslash";

Getting a Quota

With the Session instance, described above, you can get or set quotas, templates, reports, and permissions on the server you are connected to. You, however, have to do that through the Collection classes. To get a quota:

1. Get the IQSQuotaItemCollection from the session
2. Get the quota from that collection

Note that Quotas are indexed by 5 values:

• The server name where the quota is.
• The object path on which the quota applies.
• The account on which the quota applies.
• The external quota string, which is reserved for future use and must always be empty.
• A flag specifying if the quota is a template or a real quota.

Using Visual Basic
'…using the session before

' Create an new quota item
Dim tmpQuota As QSCOMAPILib.QSComApiQuotaItem

' Set the new quota item as a copy of the requested quota
' Server_Name is a string with the name of the server we connected to
' Object_Path is a string with the path to the object, like C:\Users
' User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
' ExternalQuota is a string reserved for future use and must be empty
' IsTemplate is a Boolean with whether this quota is a template or not

Set tmpQuota = QSS.Quotas.Get(Server_Name, Object_Path, User_Account, ExternalQuota, IsTemplate)

Using C++
// …get the session before

// Get QuotaItemCollection Pointer
IQSComApiQuotaItemCollection* pQICollection = NULL;

// Get quotas from collection
pQICollection = pSession->GetQuotas();

// Server_Name is a string with the name of the server we connected to
// Object_Path is a string with the path to the object, like C:\Users
// User_Account is a string with the name of the account the quota apply to, or EVERYONE
// ExternalQuota is a string reserved for future use and must be empty
// IsTemplate is a Boolean with whether this quota is a template or not
IQSComApiQuotaItem* pItem = pQICollection->Get(Server_Name,Object_Path,User_Account, ExternalQuota, IsTemplate );

Using C#
…using the session before

// Set the new quota item as a copy of the requested quota
// Server_Name is a string with the name of the server we connected to
// Object_Path is a string with the path to the object, like C:\Users
// User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
// ExternalQuota is a string reserved for future use and must be empty
// IsTemplate is a Boolean with whether this quota is a template or not
QSCOMAPILib.IQSComApiQuotaItem quota = session.Quotas.Get(Server_Name, Object_Path, User_Account, ExternalQuota, IsTemplate);

Using Powershell
…using the session before

# Set the new quota item as a copy of the requested quota
# Server_Name is a string with the name of the server we connected to
# Object_Path is a string with the path to the object, like C:\Users
# User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
# ExternalQuota is a string reserved for future use and must be empty
# IsTemplate is a Boolean with whether this quota is a template or not

$server_name = "Same as session.server"
$Object_Path = "C:\files\test..."
$User_Account = "user or group"
$quota = $session.Quotas.Get($Server_Name,$Object_Path, $User_Account, $ExternalQuota, $False )

Setting a Quota

The setting of a quota is slightly different from the getting of a quota. To set a quota:

1. Get the IQSQuotaItemCollection from the session
2. Create a quota item
3. Set the quota item in the collection

Since items are identified by 5 keys or properties (server name, object path, account, external quota, and template flag), you need to set at least those 5 properties in the quota item, using the following 5 methods:

• IQSComApiQuotaItem::PutServer ( string )
• IQSComApiQuotaItem::PutObject ( string )
• IQSComApiQuotaItem::PutAccount ( string )
• IQSComApiQuotaItem::PutExternalQuota ( string )
• IQSComApiQuotaItem::PutIsTemplate(boolean)

Again, account is EVERYONE, if the quota is not tied to a specific user. External Quota is reserved for future use, and must always be empty.

Using Visual Basic
' …get the session before

' Create a new quota item
Dim tmpQuota As QSCOMAPILib.QSComApiQuotaItem

' Set the items values
tmpQuota.QuotaSize = 128000
tmpQuota.Server = “MyServer”
tmpQuota.Object = ”\\MyServer\Users\john”
tmpQuota.Account = “Everyone”
tmpQuota.ExternalQuota = “”
tmpQuota.IsTemplate = False

' Set the quota in the collection
QSS.Quotas.Set tmpQuota

Using C++
// …get the session before

// Get QuotaItemCollection Pointer
IQSComApiQuotaItemCollection*pQICollection = NULL;

// Get quotas from collectionpQI
Collection = pSession->GetQuotas();
IQSComApiQuotaItemPtr*pItemSmartPtr;
IQSComApiQuotaItem* pItem;

// instantiate a pointer to the interface
spItem = new IQSComApiQuotaItemPtr(__uuidof(QSComApiQuotaItem));

// access the item in the interface
pItem = spItem->GetInterfacePtr();

// set the quota value
pItem->PutServer(_T(“MyServer”));
pItem->PutObject(_T(“\\\\MyServer\\Users\john”));
pItem->PutAccount(_T(“Everyone”));
pItem->PutExternalQuota(_T(“”);
pItem->PutIsTemplate(FALSE);
pItem->PutQuotaSize(128000);

// set the quota in the collection
IQSComApiQuotaItem*pItem = pQICollection->Set(pItem);

Using C#
…using the session before

// Set the new quota item as a copy of the requested quota
// Server_Name is a string with the name of the server we connected to
// Object_Path is a string with the path to the object, like C:\Users
// User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
// ExternalQuota is a string reserved for future use and must be empty
// IsTemplate is a Boolean with whether this quota is a template or not
//Create an new quota item
QSCOMAPILib.QSComApiQuotaItem quota = new QSCOMAPILib.QSComApiQuotaItem();

//Set the items values
quota.Server = Server_Name;
quota.Object = Object_Path;
quota.Account = User_Account;
quota.ExternalQuota = ExternalQuota,
quota.IsTemplate =IsTemplate;

//Set the quota
session.Quotas.Set(quota);

Using Powershell
…using the session before

# Set the new quota item as a copy of the requested quota
# Server_Name is a string with the name of the server we connected to
# Object_Path is a string with the path to the object, like C:\Users
# User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
# ExternalQuota is a string reserved for future use and must be empty
# IsTemplate is a Boolean with whether this quota is a template or not
#Create a new quota item
$quota = New-Object -ComObject  QSComApi.QSComApiQuotaItem

#Set the items values
$quota.Server = $Server_Name
$quota.Object = $Object_Path
$quota.Account = $User_Account
$quota.ExternalQuota = $ExternalQuota
$quota.isTemplate = $False

#Set the quota
$session.Quotas.Set($quota)

Enumerating Quotas

To enumerate all the quotas on a server follow these steps:

1. Get the IQSQuotaItemCollection from the session
2. Go through the collection with the enumerator

Using VisualBasic
' …get the session before

' Dimension a counter
Dim lQuota as Long

' Create a new quota item
Dim tmpQuota As QSCOMAPILib.QSComApiQuotaItem

'Enumerate the quotas
For lQuota = 1 To QSS.Quotas.Count
TmpQuota = QSS.Quotas.Item(lQuota)

' Do something with the quota item
Next

Using C++
In C++ the code is not perhaps as orderly as one would hope, but this is of course due to the type of manipulations required by COM.

// …get the session before

// Get QuotaItemCollection Pointer
IQSComApiQuotaItemCollectionPtrpQICollection = NULL;

// Get quotas from collectionp
QICollection = pSession->GetQuotas();

// get pointer to IUnknown for enumerator object
IunknownPtr pQ = pQICollection->Get_NewEnum();
IEnumVARIANT* pEnum;

// query for the IEnumVARIANT interfacep
Q->QueryInterface( IID_IEnumVARIANT, (void**)&pEnum);

// release IUnknown pointer herepQ->Release();
HRESULT hr;

// okay, let's enumerate all quotas
// start by resetting the enumerator object
hr = pEnum->Reset();do {VARIANT var;

// get next quota object from the collection
hr = pEnum->Next(1, &var, NULL);
if (S_OK == hr) {
IQSComApiQuotaItemPtr*pItemSmartPtr;
QSComApiQuotaItem* pItem;

// okay, let's build ourselves a smart pointer here
pItemSmartPtr = new IQSComApiQuotaItemPtr(var.punkVal);
pItem = pItemSmartPtr->GetInterfacePtr();

// Do something with the quota item
DoSomething( pItem );
pItem->Release();
delete pItemSmartPtr;
}
} while (S_OK == hr);

Using C#
…using the session before

foreach (QSCOMAPILib.QSComApiQuotaItem quota in session.Quotas)
{
//Do something with the quota
}

Using Powershell
…using the session before

ForEach($quota in $session.Quotas)
{
#Do something with the quota
}

Deleting a Quota

The deletion of a quota is quite straightforward. To delete a quota:

1. Get the IQSQuotaItemCollection from the session.
2. Get or create the quota.
3. Delete the quota.

Using Visual Basic
' …get the session before

' Create a new quota item
Dim tmpQuota As QSCOMAPILib.QSComApiQuotaItem

' Since items are identified by 5 keys (server name, object path, account, external quota and template flag), you need to set those 5 properties in the quota item with the following 5 methods:

' Set the items values
tmpQuota.QuotaSize = 128000
tmpQuota.Server = “MyServer”
tmpQuota.Object = ”\\MyServer\Users\john”
tmpQuota.Account = “Everyone”
tmpQuota.ExternalQuota = “”
tmpQuota.IsTemplate = False

' Delete the quota
QSS.Quotas.Delete tmpQuota

Using C++
// …get the session before

// Get QuotaItemCollection Pointer
IQSComApiQuotaItemCollectionPtrpQICollection = NULL;

// Get quotas from collection
pQICollection = pSession->GetQuotas();
if( enumerate == false ) {
// instantiate a pointer to the interface
pItemSmartPtr = new IQSComApiQuotaItemPtr(__uuidof(QSComApiQuotaItem));
// access the item in the interfacepItem = pItemSmartPtr->GetInterfacePtr();
// set the quota values
// Since items are identified by 5 keys (server name, object path, account, external quota and template flag), you need to set at those 5 properties in the quota item with the following 5 setters
pItem->PutServer(_T(“MyServer”));
pItem->PutObject(_T(“\\\\MyServer\\Users\john”));
pItem->PutAccount(_T(“Everyone”));
pItem->PutExternalQuota(_T(“”);
pItem->PutIsTemplate(FALSE);

// delete the quota in the collection
pQICollection->Delete(pItem);
} else {
// get pointer to IUnknown for enumerator objectIunknownPtr pQ = pQICollection->Get_NewEnum();
IEnumVARIANT* pEnum;

// query for the IEnumVARIANT interface
pQ->QueryInterface( IID_IEnumVARIANT, (void**)&pEnum);

// release IUnknown pointer here
pQ->Release();
HRESULT hr;

// okay, let's enumerate all quotas
// start by resetting the enumerator object
hr = pEnum->Reset();
do {
VARIANT var;

// get next quota object from the collection
hr = pEnum->Next(1, &var, NULL);
if (S_OK == hr) {
IQSComApiQuotaItemPtr*pItemSmartPtr;
IQSComApiQuotaItem* pItem;

// okay, let's build ourselves a smart pointer here
pItemSmartPtr = new IQSComApiQuotaItemPtr(var.punkVal);
pItem = pItemSmartPtr->GetInterfacePtr();

// Do something with the quota item
pQICollection->Delete( pItem );
pItem->Release();
delete pItemSmartPtr;
}
} while (S_OK == hr);

Using C#
…using the session before

// Set the new quota item as a copy of the requested quota
// Server_Name is a string with the name of the server we connected to
// Object_Path is a string with the path to the object, like C:\Users
// User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
// ExternalQuota is a string reserved for future use and must be empty
// IsTemplate is a Boolean with whether this quota is a template or not
//Create a new quota item
QSCOMAPILib.QSComApiQuotaItem quota = new QSCOMAPILib.QSComApiQuotaItem();

//Set the items values
quota.Server = Server_Name;
quota.Object = Object_Path;
quota.Account = User_Account;
quota.ExternalQuota = ExternalQuota;
quota.IsTemplate = IsTemplate;

//Delete the quota
session.Quotas.Delete(quota);

Using Powershell
…using the session before

# Set the new quota item as a copy of the requested quota
# Server_Name is a string with the name of the server we connected to
# Object_Path is a string with the path to the object, like C:\Users
# User_Account is a string with the name of the account the quota apply to,‘ or EVERYONE
# ExternalQuota is a string reserved for future use and must be empty
# IsTemplate is a Boolean with whether this quota is a template or not
#Create a new quota item
$quota = New-Object -ComObject  QSComApi.QSComApiQuotaItem

#Set the items values
$quota.Server = $Server_Name
$quota.Object = $Object_Path
$quota.Account = $User_Account
$quota.ExternalQuota = $ExternalQuota
$quota.isTemplate = $False

#Delete the quota
$session.Quotas.Delete($quota)

Receiving Further Assistance

It is of course possible to receive direct assistance in the use of the Northern Quota Server COM API from Northern personnel. However support of this advanced usage, in terms of guidance and further code examples, is not covered by the normal terms of a Support and Maintenance agreement; it is reliant on the availability of purchased Professional Services hours. Please contact your Northern Account Manager if you require further assistance in the use of this COM API.