Directory Listing

Retrieves a listing of a directory in the Backendless file storage:

Blocking API

Get a directory listing for the specified path with a pattern matching all files excluding all subdirectories.

public List<FileInfo> listing( String path )

Get a directory listing for the specified path and pattern. Subdirectory inclusion is controlled by the recursive argument.

public List<FileInfo> listing( String path, String pattern, boolean recursive)

public List<FileInfo> listing( String path, 
                                  String pattern, 
                                  boolean recursive, 
                                  int pagesize, 
                                  int offset)

Non-Blocking API

Get a directory listing for the specified path with a pattern matching all files excluding all subdirectories.

public void listing( String path, 
                     AsyncCallback<List<FileInfo>> responder)

Get a directory listing for the specified path and pattern. Subdirectory inclusion is controlled by the recursive argument.

public void listing( String path, 
                     String pattern, 
                     boolean recursive, 
                     int pagesize,
                     int offset,
                     AsyncCallback<List<FileInfo>> responder)

where:

Argument	Description
path	Path of a directory to get a listing of. The path must start with the root directory identified by forward slash, for example: "/web".
pattern	A pattern which the returned files and directories must match. The pattern can include wildcard characters. Asterisk (*) matches a substring of any length. Question mark (?) matches only one character in the file/directory name.
recursive	An optional parameter. If present and is true, requests that the listing must be retrieved recursively for all directories contained within .
pagesize	An optional parameter. If present, identifies how many items should be returned in the response.
offset	An optional parameter. If present, indicates the index of item in the response from which to get the <pagesize> items.
responder	A responder object which receives a callback when the method successfully completes or if an error occurs. Applies to the asynchronous method only.

Return value

A collection of files and directories matching the specified pattern. The returned collection may not include all files and directories as the size of the number of returned entries is limited for paging purposes. To get the next set of file/directory entries, an additional request must be made with a different offset value. The total count of all files/directories in the listing use the Get File Count API.

Each element in the collection contains the following properties:

• name - name of the file or directory without any path information
• public URL - absolute URL of the file or directory
• URL - relative URL of the file or directory starting from the root of the file storage
• created on - a timestamp indicating when the file or directory were created

Example

The example below describes how to get a listing of all HTML files from the /web directory and all subdirectories.

Backendless.Files.listing( "/web", "*.html", true, 
                  new AsyncCallback<List<FileInfo>>()
{
  @Override
  public void handleResponse( List<FileInfo> response )
  {
    Iterator<FileInfo> filesIterator = response.iterator();
    while( filesIterator.hasNext() )
    {
      FileInfo file = filesIterator.next();
      String URL = file.getURL();
      String publicURL = file.getPublicUrl();
      Date createdOn = new Date( file.getCreatedOn() );
      String name = file.getName();
     }
   }

   @Override
   public void handleFault( BackendlessFault fault )
   {
   }
 });

Errors

The server may return the following errors:

Error Code	Error message	Notes
6000	File or directory cannot be found.	Occurs when the source file/directory cannot be found.
6006	Path contains prohibited symbols: {path name}
6007	The specified resource was not found	Occurs when the API requests to rename a non-existent file or a directory.
6029	Specified resource must be a directory	Occurs when the path to get a listing for is not a directory

Codeless Reference

where:

Argument	Description
path	Path of a directory to get a listing of. The path must start with the root directory identified by forward slash, for example: "/web".
pattern	An optional parameter. A pattern which the returned files and directories must match.
include subdirectories	An optional parameter. A boolean value of true or false. If it is true, requests that the listing must be retrieved recursively for all directories contained withinpath.
page size	An optional parameter. Identifies how many items should be returned in the response.
page offset	An optional parameter. Indicates the index of item in the response from which to get the page size items.

Returns a list containing objects representing files and folders stored in the requested directory.

Consider the following files stored in the days directory:

The example below retrieves a list containing all file names, as well as other related details. Files are retrieved from "days" directory.

The result of this operation will look as shown below after the Codeless logic runs.

Consider the following files stored in the misc directory.

The example below uses the pattern argument to retrieve only those pictures whose file extension is .jpg.

As you can see, the operation has retrieved a list containing file names matching the pattern argument.