/*
 * Copyright (C) 2017 ~ 2019 Deepin Technology Co., Ltd.
 *
 * Author:     Chris Xiong <chirs241097@gmail.com>
 *
 * Maintainer: Chris Xiong <chirs241097@gmail.com>
 *
 * GNU Free Documentation License Usage
 * Alternatively, this file may be used under the terms of the GNU Free
 * Documentation License version 1.3 as published by the Free Software
 * Foundation and appearing in the file included in the packaging of
 * this file. Please review the following information to ensure
 * the GNU Free Documentation License version 1.3 requirements
 * will be met: https://www.gnu.org/licenses/fdl-1.3.html.
 */

/*!
    \page dfmroot-scheme.html
    \title DFMRoot Scheme

    The DFMRoot scheme is primarily designed to be used by the new Computer View. It is essentially an enhanced version of the computer scheme found in Gvfs.

    The scheme deals with 3 types of locations: user directories, local disks / loop devices handled by UDisks2, and network locations mounted by Gvfs.

    \section1 Scheme Structure

    All locations handled by DFMRoot are virtual entries located directly under the root directory. They are distinguished by different suffices.

    \list
    \li suffix "userdir"

    Entries with this suffix have one of the following basenames:
    \c desktop, \c videos, \c music, \c pictures, \c documents, \c downloads

    They all refer to the corresponding directory in the current user's home directory.
    If a location is explicitly disabled by the user-dirs.dir file, it will be treated as if it doesn't exist.

    \li suffix "localdisk"

    Entries with this suffix has the name of a block device as its basename.
    
    Note: for encrypted block devices, the cleartext device is never be used to construct the URL of this
    scheme. The controller doesn't acknowledge the existence of such devices either. In such case, block
    device containing the encrypted data should be used instead.

    \li suffix "gvfsmp"

    Entries with this suffix has percent-encoded path of mount point as its basename.
    This could be confusing: path of gvfs-managed mount point may already contain percent-encoded or
    sometimes even double percent-encoded components.
    In any case, a single decode pass should always result in the correct mount point path.
    Please note that this scheme only handles GVolume that has a mount point, i.e. already mounted.
    \endlist

    \section2 Sample URLs

    \list
    \li dfmroot:///desktop.userdir
    \li dfmroot:///sda2.localdisk
    \li dfmroot:///mmcblk0p1.localdisk
    \li dfmroot:///nvme0n1p3.localdisk
    \li dfmroot:///sr0.localdisk
    \li dfmroot:///%2Frun%2Fuser%2F1000%2Fgvfs%2Fsmb-share%3Aserver%3D10.0.12.150%2Cshare%3Dshare.gvfsmp
    \li dfmroot:///%2Frun%2Fuser%2F1000%2Fgvfs%2Farchive%3Ahost%3Dfile%25253A%25252F%25252F%25252Fhome%25252Fc%25252Fdevel%25252Ftest.iso.gvfsmp
    \endlist

    \section1 FileInfo Usage
    Entries using this scheme can always be redirected. Use \c redirectedFileUrl() to obtain its
    location in the local file hierarchy.

    You can determine the type of an entry by calling \c fileType(). The returned value has the type \c DFMRootFileInfo::ItemType.

    Extra properties returned for FileInfo of this type:
    \table
    \header
      \li prop/suffix
      \li gvfsmp
      \li localdisk
    \row
      \li fsUsed
      \li {2, 1} (quint64) Used size of the volume, in bytes.
    \row
      \li fsSize
      \li {2, 1} (quint64) Total size of the volume, in bytes.
    \row
      \li fsType
      \li {2, 1} (QString) Filesystem name of the volume.
    \row
      \li rooturi
      \li (QString) Root URI of the mount, e.g. smb://127.0.0.1/share
      \li -
    \row
      \li encrypted
      \li -
      \li (bool) whether the block device is encrypted
    \row
      \li unlocked
      \li -
      \li (bool) false if the device is encrypted and locked. True otherwise.
    \row
      \li udisksblk
      \li -
      \li (QString) DBus path of the block device. If the device is encrypted
      and unlocked, this will refer to the cleartext device instead.
    \row
      \li mounted
      \li {2, 1} (bool) Whether the volume is mounted.
    \endtable
    User directories do not have any extra properties.

    
    \section1 Controller Usage
    \section2 Re-labelling a filesystem
    Only items controlled by udisks can be re-labeled. Call renameFile with an event with following parameters to change the label of a filesystem:
    \list
    \li fromUrl: the URL of the item to be re-labeled.
    \li toUrl: a URL whose path section is the desired filesystem label.
    \endlist
    The user will be prompted for their (or the administrator's) password if necessary.

    \section2 If you want to mount/unmount a filesystem...
    You have to make calls to udisks manually, or check out if anything in AppController satisfy your needs.

    \section1 Dodging slippery behaviors of Gio/Gvfs

    \list
    \li Gvfs volumes that has one of the following URI schemes are automatically mounted when detected (while fetching content of DFMRoot or have a file watcher actively watching its changes): mtp, afc, gphoto2.
    \li 'GMount's of the following class are ignored: GUnixMount.
    \li 'GMount's originated from a udisks mount are ignored.
    \li 'GMount's that correspond to a blank writable optical disc are ignored.
    \endlist


*/
