Search

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

Description: Returns a list of items representing the search result of file/folder name (or description) match. Information for each match in the list can be optionally requested. Among the information available are: type, name, location, description, name_href, location_href.

INPUT (via GET or POST)

Mandatory parameters are: sid
Optional parameters are: lookin, fields, namepatt, descpatt, maxmatches, ofmt

sid	session id of the login user. [mandatory]
lookin	Specify which toplevel folder to begin search on. By default, the search will look into ALL user accessible areas. If you want to specify a lookin, currently it only accepts ONE toplevel folder name and it is case sensitive. An error will return if the user does not have access to this folder. Note: No errors is flagged for inability to search subfolders that the user has no rights to list its content. This can happen for subfolders in [Company Share] for example. e.g. `lookin=` Empty lookin will mean to look in all user accessible areas. lookin=Private+HomePage - search only in "Private HomePage" area
fields	= type,name,location,description,name_href,location_href (this is also the default) 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! type is a string 'file' or 'folder' name is the name of the item location is storage path of the folder where the item is in. e.g. [Company Share]/myfolder description is a string entered by owner to describe the item. Can be blank. name_href is the relative url to open the item. If the item is a file it will connect to openfile.cgi, and if it is a folder, it will connect to storage.cgi. It is complete with all necessay arguments and already url encoded. This is meant to be used in the anchor tag around name. (DEPRECATED. Will not be implemented in future.) location_href is the relative url to open up the folder containing the item. This is like name_ref but will always connect to storage.cgi since we are focusing on a folder here. This is meant to be used in the anchor tag around location. (DEPRECATED. Will not be implemented in future.)
namepatt	= pattern to match file or folder name The patten matches the beginning of name. The only wildcard available is . It can be used to match the tail end of name, e.g. .txt A pattern of namepatt=file* is equivalent to just namepatt=file. The match is done case-insensitive. An empty namepatt matches everything, i.e. a don't care.
descpatt	= pattern to match the description of a file or folder Slightly different from namepatt, descpatt matches anywhere in the description. NO wildcard is available in this pattern. The match is done case-insensitive. An empty descpatt matches everything, i.e. a don't care.
maxmatches	= integer to limit the number of matches returned. = 100 (current 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_matches><newline>
<tab separated field values for a match> <newline>
<tab separated field values for a match> <newline>
<tab separated field values for a match> <newline>
:
:

Example: Using arguments namepatt=*jpg, descpatt=, lookin=Company%20Share, fields=name,type,location,description
You may specify fields=... to get the fields you want and in the order you want.

true    3
unrelated-happenings.jpg <tab> file <tab> /Company Share/asdf/ <tab> <newline>
Tulips.jpg <tab> file <tab> /Company Share/asdf/ <tab> <newline>
日本語Chrysanthemum.jpg <tab> file <tab> /Company Share/asdf/ <tab> Español Français 日本語 Русский Tiếng Việt <newline>

The equivalent JSON output is:

{
   "num_of_items" : 3,
   "match_list" : [
      {
         "location" : "/Company Share/asdf/",
         "name" : "unrelated-happenings.jpg",
         "type" : "file",
         "description" : ""
      },
      {
         "location" : "/Company Share/asdf/",
         "name" : "Tulips.jpg",
         "type" : "file",
         "description" : ""
      },
      {
         "location" : "/Company Share/asdf/",
         "name" : "日本語Chrysanthemum.jpg",
         "type" : "file",
         "description" : "Español Français 日本語 Русский Tiếng Việt"
      }
   ],
   "status" : true
}

If there is no match, the number_of_matches = 0 and no other lines follow. Example:

true <tab> 0 <newline>

The equivalent JSON output is:

{
   "num_of_items" : 0,
   "match_list" : [],
   "status" : true
}

Unsuccessful return:

false <tab> <error message> <newline>

Example:

false <TAB> Could not access this location: Company HomePage

The equivalent JSON output is:

{
   "http_status" : "400 Unable to do search",
   "status" : false,
   "errmsg" : "Could not access this location: Company HomePage"
}

HTTP Status Codes

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.