[Up]: 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 and also for specific folder.

INPUT (via GET or POST)

Mandatory parameters are: sid
Optional parameters are: type, path, spath, ofmt

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 total usage and quota for /Company Share and /Company HomePage  (Company area)

            user,
                means to get total usage and quota for /Private and /Private HomePage  (Private area)

            folder,

                means to get the total diskusage for a specific folder alone,
                AND the diskquota value returned is that of the Public area, Company area, or Private area
                where the folder resides.

                For folder type, the path (or spath) must specify the folder to query on.

                IF the path does not exist, the diskusage returned is 0 (zero) - NO ERROR returned!
                IF the path is to an existing FILE, the diskusage is that file's size.

           network,
 
              There MUST be a specified path (or spath) that begins with /Network Share/<valid-sharename>
               together with this parameter of type = network.
               This means to get the diskusage and quota of the user who shared this folder out.
               (i.e. The 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):
                  /Public Share/... means type = public
                  /Company Share/... or /Company HomePage/... means  type = company
                  /Private or /Private HomePage/... means  type = user
                  /Network Share/<sharename>/... means  type = network
              (Note that there type = folder will NOT be implicitly derived from any given path.)
path path to a folder or file

         This parameter is IGNORED if given type = public | company | user
         However, path must be specified for type = folder | network

         Examples of paths:
            /Private/so/subdir, 
            /Network Share/shared_folder/subdir,
            /Company Share/sales_docs/abc

            for type = folder, any path that specifies a folder (or file) will do, with the following EXCEPTIONS:

                 diskusage for folder path="/" is NOT defined (error return)
                 diskusage for folder path="/Network Share" is NOT defined (error return)
                 diskusage for folder path="/Network Share/<sharename>" that does not exist is NOT defined (error return)

        Please refer to [How to specify a path].

 
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.
ofmt
 = null | json | jsonp
   null is the default, and the legacy "flat" output format is returned.
   json means the output format is in JSON format
   jsonp is like json, but in "pretty" form for easier human readability.
 

 

OUTPUT (content-type: text/plain)

Successful return:

	true <TAB> <diskusage in bytes> <TAB> <diskquota in bytes>
        Example return value

	true <TAB>  13122111 <TAB> 52428800

        Equivalent JSON output would look like the following:

	{
	   "diskquota" : "52428800",
	   "diskusage" : "13122111",
	   "status" : true
	}

If the diskusage (in bytes) returns with a value of -1 or empty, 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.


Unsuccessful return:

	false <tab> <error message> <newline>

         e.g. 

	false <TAB> Invalid user profile.

        Equivalent JSON output would look like the following:
	{
	   "http_status" : "401 Invalid user profile",
	   "status" : false,
	   "errmsg" : "Invalid user profile."
	}

       In both legacy "flat" output and also JSON output, appropriate HTTP header status codes are also returned e.g. 200 OK, 401 Invalid user profile, etc.


 Additional Notes:
      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".  
      And each storage area has a separate storage quota.

      "folder", on the other hand, is part of a storage area. 
      "network" is a folder that was shared to the user by others, so it is also part of a storage area.
      This API returns the diskusage of just that folder or "network" folder specified, but the diskquota 
      returned is that of the storage area the folder or "network" folder belong to.

      Usually there are multiple top-level storage folders in one storage area. Example, the "user" area
      consists of "/Private" and "/Private HomePage". When requesting for "user" diskusage (type=user), 
      the API will return all usage for all the top-level folders. So, taking the diskusage of a top-level 
      storage folder (type=folder) is not necessarily the same as taking the diskusage of a storage 
      area (type=user|company|public). It would be the same, IF "user" area has just that ONE top-level folder.