We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - Restore::directory_listing
Skip to end of metadata
Go to start of metadata

Description

This function lists all of the backup files and directories in the user's home directory.

Important:

In cPanel & WHM version 84 and later, when you disable the File Storage role, the system disables this function.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsessXXXXXXXXXXXX/execute/Restore/directory_listing?path=%2Fpublic_html%2F


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// get a directory listing of all backups for user
$DAV = $cpanel->uapi(
    'Restore', 'directory_listing',
    array(
        'path'  => '/public_html/',
    )
 );


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# get a directory listing of all backups for user
my $disable_shared_global_addressbook = $cpliveapi->uapi(
    'Restore', 'directory_listing',
    {
        'path'  => '/public_html/',
    }
 );


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=example1 Restore directory_listing path=/public_html/


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
   "messages":null,
   "metadata":{
      "transformed":1
   },
   "errors":null,
   "status":1,
   "data":[
      {
         "type":"dir",
         "onDiskType":"dir",
         "name":"testdir",
         "conflict":0,
         "exists":1
      }
   ]
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
pathstring

Required.

A path to a subdirectory within the user's home directory,or any level below it.

Note:

The value of this parameter must begin and end with a forward slash (/) for security purposes.

A path relative to the home directory.

/public_html/


Returns

ReturnTypeDescriptionPossible valuesExample

hashA hash that contains information about a specific item stored in the backup.This hash contains the conflict, exists, name, onDiskType, and type returns.

conflict

Boolean

Whether a difference exists between the type and onDiskType returns.

The function returns this value in the unnamed hash.

  • 1 — Conflict exists.
  • 0 — No conflict exists.
0

exists

Boolean

Whether the file exists in the user's directory or only in the backup.

The function returns this value in the unnamed hash.

  • 1 — File exists in the user's directory.
  • 0 — File exists only in the backup.

1

name

string

The name of the file or directory.

The function returns this value in the unnamed hash.

A file or directory name.public_html

onDiskType

string

The item type stored on the disk.

The function returns this value in the unnamed hash.

  • dir — A directory.
  • file — A file.
  • symlink — A symlink.
  • unknown — An unknown file type.
file

type

string

The item type stored in the backup.

The function returns this value in the unnamed hash.

  • dir — A directory.
  • file — A file.
  • symlink — A symlink.
  • unknown — An unknown file type.
file