Afteroffice.com

Home > Developer

Storage API : DiskUsage & DiskQuota

DiskUsage & DiskQuota

Script path: /storage/bin/api/diskusage.cgi

Description: Returns the diskusage and diskquota of various different "area" of Storage.

INPUT (via GET or POST)

Mandatory parameters are: sid, type
Optional parameters are: path, ignore_cache

sid session id of the login user. [mandatory]
type one of   public | company | user | folder | network

            public, means to get the usage and quota for /Public Share  (Public area)
            company, means to get usage and quota for /Company Share and /Company HomePage  (Company area)
            user, means to get usage and quota for /Private and /Private HomePage  (Private area)

            folder, the diskusage returned is that for the folder alone, but the diskquota value is NOT
              returned because folder quota is not implemented yet.
              (In future, when folder quota is implemented, a value would be returned.)

            network, there must be a specified path (or spath) that begins with /Network Share/<valid-sharename>
              This means to get the diskusage and quota of the user who shared this folder out.
              (i.e. That other user's Private area)


            If type is not specified, it will be implicitly derived by from the given path (or spath).
            The first component of path (or spath) will determine the type (or area) read diskusage / quota
               Public Share means type = public
               Company Share or Company HomePage means  type = company
               Private or Private HomePage means  type = user
               Network Share means  type = network

            (Note that there is NO implicit derivation of type=folder for any path)

            (Please IGNORE the type=network option here, for now. It is now not well defined.)
path path to a file [optional]

path is needed only for type = folder | network

Please refer to [How to specify a path].

          specifies the storage path, e.g. /Private/so/subdir,  /Network Share/shared_folder/subdir, /Company Share/sales_docs/abc
            for type = folder, any path that specifies a folder will do.
            for type = network, the path must begin with /Network Share/<valid-sharename>

            path input is ignored for type = public | company | user.

            Alternatively, type input above can be implicitly determined by a given path here. (see above).
spath

 synonym for the path parameter
This actually take precedence over path if both are given. To avoid confusion, just use either path or spath.
ignore_cache = 0 | 1  (defaults to 0, i.e. do not ignore cache)

By default a cached diskusage value is return, if available.
If you wish to guarantee actual discovery of diskusage, set this to 1.
But do NOT repeatedly use ignore_cache=1 in a tight loop, it can increase server load.

(This parameter is deprecated.)
was_from_cache_or_not

 = 0 | 1  (default is 0 do not return this info)
 If set to 1, another info will be returned by the API.
 This info tells if the diskusage value returned was from actual discovery or from a cached value.

(This parameter is deprecated.)

 

OUTPUT (content-type: text/plain)

Successful return:

true <TAB> <diskusage in bytes> [ <TAB> <diskquota in bytes> ]

Example return value
      true <TAB>  13122111 <TAB> 52428800

Example return value for case when type = folder
      true <TAB>  455632

If the diskusage (in bytes) returns with a value of -1, it means that the diskusage could not be immediately determined. Display-wise you may let the user know that it is currently unknown. In most cases, if the API is called again after one minute, a proper value will be returned. This happens because diskusage calculation is done asynchronously and the values for various folders and areas are cached.

(Please ignore the following two examples for now.)
Example return value, with was_from_cache_or_not = 1
      true <TAB>  13122111 <TAB> 1 <TAB> 52428800

Example return value for case when type = folder, with was_from_cache_or_not = 1
      true <TAB>  455632 <TAB> 1

Unsuccessful return:

false <tab> <error message> <newline>

e.g.

false <TAB> Invalid user profile.


# Notes:
#
#      "\n" trails each output line.
#
#      Using type=user returns all usage by one user for /Private  and  /Private HomePage, if any.
#      The diskquota returned is for the all private areas accessible by the user.
#      If you just want to know the usage for a user's /Private folder, use type=folder, path=/Private.
#      But as explained above, there is no quota on folder yet, so there will no diskquota value returned.
#      If /Private is the ONLY private folder for a user, then both methods would yield the same values
#      for diskusage, but only type=user will give the diskquota that you may be looking for.
#
#      Diskusage and Diskquota concepts here are linked to "areas" of storage rather than to a particular
#      top-level storage folder. Storage areas are "public", "company", "user", "network".
#      There can be a number of top-level storage folders in one storage area. Example, the "user" area
#      consists of /Private   and   /Private HomePage  top-level folders. So, taking the diskusage of a
#      top-level storage folder is not the same as the diskusage of a storage area.
#