[Up]: Storage API : 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
INPUT (via GET or POST)
Mandatory parameters are: sid, path
Optional parameters are: fields, filter,
sortby, sorthow, ofmt
| sid | session id of the login user. [mandatory] |
| path | path to a folder [mandatory] Please refer to [How to specify a path]. path must point to an existing folder. e.g. |
| fields | = 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
|
| filter | = 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 |
| sortby | = 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. |
| sorthow | = ascend | descend = ascend (sort by ascending manner by default) |
| 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> <number_of_item_in_list> <newline>
<tab separated field values for the item> <newline>
<tab separated field values for the item> <newline>
<tab separated field values for the item> <newline>
:
:
If there is nothing to list, (empty directory, or
as a result of filtering) the number_of_item_in_list = 0 and no
other lines follow.
Examples:
true <TAB> 6
00file.h <TAB> 200009121233 <TAB> 3 <TAB> file
abc.gif <TAB> 200009121917 <TAB> 1454 <TAB> file
bug.GIF <TAB> 200009162256 <TAB> 1454 <TAB> file
newfolder <TAB> 200102061801 <TAB> 0 <TAB> folder
Small Folder <TAB> 200008201826 <TAB> 869 <TAB>folder
TextDocument.txt <TAB> 200003051641 <TAB> 3245 <TAB> file
The equivalent JSON output is:
{
"num_of_items" : 6,
"status" : true,
"dir_list" : [
{
"date" : "200009121233",
"name" : "00file.h",
"type" : "file",
"size" : "3"
},
{
"date" : "200009121917",
"name" : "abc.gif",
"type" : "file",
"size" : "1454"
},
{
"date" : "200009162256",
"name" : "bug.GIF",
"type" : "file",
"size" : "1454"
},
{
"date" : "200102061801",
"name" : "newfolder",
"type" : "folder",
"size" : "0"
},
{
"date" : "200008201826",
"name" : "Small Folder",
"type" : "folder",
"size" : "0"
},
{
"date" : "200003051641",
"name" : "TextDocument.txt",
"type" : "file",
"size" : "3245"
}
]
}
Unsuccessful return:
false <tab> <error message> <newline>
Example:
false <TAB> Item does not exist.The equivalent JSON output is:
{
"http_status" : "400 Unable to get folder listing",
"status" : false,
"errmsg" : "Item does not exist."
}
HTTP Status Codes