GetDir

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

Description: Returns a list of items representing the directory listing of the given folder. Information for each item in the list can be optionally requested. Among the information available are: name, date, mtime, size, type, owner, company, lock status, description, checksum. Sorting of the list by selected fields and simple filtering of names is possible.

Mandatory parameters are: sid, path
Optional parameters are: fields, filter, sortby, sorthow, ofmt

Session id of the login user. [mandatory]

Path to a folder. [mandatory]
Please refer to How to specify a path.

Path must point to an existing folder. E.g.:

• path=/Private/subdir - list item under subdir in the “Private” area
• path=/Company Share - list items in “Company Share”
• path=/ - list the toplevel folders available to the user.

= name,date,mtime,size,type,owner,company,lock,description, checksum
= name,date,size,type (this is default if no fields are provided)

The field names may be any order and the returned field values will follow that order. Separate the field names with commas but do not include any spaces. Fields obmitted will not be returned. Returned value for a field can be empty strings. If a field does not exist in the item's information record, an empty field is returned. WARNING: a misspelled field name will be quietly ignored, i.e. returned empty value!

• name is the name of the item
• date is in 14-digit form, corrected to user's localtime using the user's timezone info from his profile. e.g. 20010130052533
• dategmt is in 14-digit form, GMT time. e.g. 20010129212533 is the GMT equivalent to the date example.
• mtime is the number of non-leap seconds since 1 Jan 1970 GMT. mtime is in GMT.
• size is the file size. Integer, no commas. For folders, it is the total size of all files and subfolder under it, BUT it can be -1 or “blank” if the folder size is not available yet.
• type is a string 'file' or 'folder'
• owner is the owner of the item, taking the form of <name>.<group> e.g. userone.abc or dotcomguy ( Update 2013: the [.<group>] part is deprecated.)
• company is the organization of owner, taking the form of [<group>.]<host> e.g. abc.afteroffice.net or dotcom.com ( Update 2013: the [<group>.] part is deprecated.)
• lock is the lock status of the item. Value is 'yes' if locked and 'no' otherwise. (Actually derived from lock_owner not= empty)
• description is a string entered by owner to describe the item.
• checksum is the 128-bit MD5 checksum of the file represented as lowercased 32 hex digits. This only applies to files. WARNING: For folders, the value returned will be empty/null, without any errors being flagged.
• lock_owner is the lock owner for a lock placed on the item. Value is in the form of and “email” e.g. name@host that identifies a user account, but does not necessarily mean a valid email address. Only applicable to files and NOT folders. For folders, this value is always empty. The (legacy) lock value above is “yes” if this value is not empty.

= pattern(s) to match
List only items with name matching pattern using wild cards, *, ? and []
The match is done case-insensitive. Example:

• *.txt - list all text files (.txt .TXT …)
• a* - begining with letter “a” or “A”
• file*.? - filenames ending with a single letter extension
• * * - filenames with at least a space in them.
• *[ho] - list filename ending with either “h” or “o”

Multiple patterns are specified with comma separating them, example, *.jpeg,*.jpg

name | size | date | mtime
= name (sort by name is the default)

The listing will be sorted by the field specified. Since 'date' and 'mtime' comes from the same property, they produce the same sorting order.

= ascend | descend
= ascend (sort by ascending manner by default)

= 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.