// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// Copyright (C) 2018 Pelagicore AG
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page appman-controller.html
\title Controller
\brief A command-line utility to remote control the application manager on a target device.
\ingroup qtappman-tools

The \c{appman-controller} is a command-line utility that can be used by the developer, or
indirectly by other tools, on the target device to control the application manager without
communicating directly with its D-Bus interface.

\note In order to use this tool, the application manager has to be connected to either a session- or
system-bus; don't run it with \c{--dbus none}.

If you are running multiple application manager instances in the same system, you need to tell the
controller which instance you are addressing.
The default id for any system-ui is \c appman, but you can \l{instance-id}{assign custom instance-ids}.
In addition, a unique number is appended to this configured id to make it possible to disambiguate
between instances with the same id.

A list of all currently running instances can be obtained with the \c list-instances command.

\note The appman-controller has to be run under the same user id as the application manager.
      Otherwise the D-Bus connection will fail. For a possible solution, see the
      \l{Why does the appman-controller not see any of my appman instances?}{troubleshooting guide}.

The \c --instance-id option lets you choose which of the running appman instances you want to
address. This gives you 3 possibilities:
\list
    \li You do not specify \c --instance-id at all: if only one appman instance is running, then it
        will be addressed (ignoring its instance-id). If there are more instances, the tool will
        stop with an error.
    \li You only specify the base id without the disambiguating number (e.g. \c appman):  if only
        one appman instance using the given base id is running, then it will be addressed. If there
        are more instances, the tool will stop with an error.
    \li You specify the full id with the disambiguating number (e.g. appman-1): Only the given
        appman instance will be addressed.
\endlist

The following commands are available:

\table
\header
    \li Command
    \li Arguments
    \li Description
\row
    \li \span {style="white-space: nowrap"} {\c start-application}
    \li \c{<application-id>}

        \c{[document-url]}
    \li Starts the application with \c application-id within the application manager.
\row
    \li \span {style="white-space: nowrap"} {\c debug-application}
    \li \c{<debug-wrapper-specification>}

        \c{<application-id>}

        \c{[document-url]}
    \li Starts the application with \c application-id within the application manager using
        a debug-wrapper. For more information, see \l{DebugWrappers}.
\row
    \li \span {style="white-space: nowrap"} {\c stop-application}
    \li \c{<application-id>}
    \li Stops the application with \c application-id.
\row
    \li \span {style="white-space: nowrap"} {\c stop-all-applications}
    \li (none)
    \li Stops all applications that are running within the application manager.
\row
    \li \span {style="white-space: nowrap"} {\c list-applications}
    \li (none)
    \li Outputs all available application IDs on the console, one per line.
\row
    \li \span {style="white-space: nowrap"} {\c show-application}
    \li \c{<application-id>}
    \li Shows the current metadata for the given application in YAML format. Alternatively, use
        \c{--json} to get the metadata in JSON format instead.
\row
    \li \span {style="white-space: nowrap"} {\c list-packages}
    \li (none)
    \li Outputs all available package IDs on the console, one per line.
\row
    \li \span {style="white-space: nowrap"} {\c show-package}
    \li \c{<package-id>}
    \li Shows the current metadata for the given package in YAML format. Alternatively, use
        \c{--json} to get the metadata in JSON format instead.
\row
    \li \span {style="white-space: nowrap"} {\c install-package}
    \li \c{<package>}
    \li Installs the package given on the command-line. If the package file is specified as \c{-},
        the tool tries to read the package from \c stdin. The following options are supported:

        \c{-a, --acknowledge}: Automatically acknowledge the installation, instead of relying on
        the System UI's logic.
\row
    \li \span {style="white-space: nowrap"} {\c remove-package}
    \li \c{<package-id>}
    \li Removes the package, specified with \c package-id. The following options are
        supported:

        \c{-f, --force}: Force removal of package.

        \c{-k, --keep-documents}: Keep the document folder of the package.
\row
    \li \span {style="white-space: nowrap"} {\c list-installation-tasks}
    \li (none)
    \li Lists all active installation tasks.
\row
    \li \span {style="white-space: nowrap"} {\c cancel-installation-task}
    \li \c{<task-id>}
    \li Cancels an active installation task, specified with \c task-id.
\row
    \li \span {style="white-space: nowrap"} {\c list-installation-locations}
    \li (none)
    \li Lists all installaton locations.
\row
    \li \span {style="white-space: nowrap"} {\c show-installation-location}
    \li \c{<installation-location>}
    \li Shows details for the specified \c installation-location in YAML format. Alternatively, use
        \c{--json} to get the location details in JSON format instead.
\row
    \li \span {style="white-space: nowrap"} {\c list-instances}
    \li (none)
    \li Lists the unique \l{instance-id}{ instance ids} of all currently running application manager
        instances.
\row
    \li \span {style="white-space: nowrap"} {\c inject-intent-request}
    \li \c{<intent-id>}

        \c{[parameters as json string]}
    \li Injects an intent request into the application manager for testing or debugging purposes.
        This only works, if the application manager is running in \l{development-mode}{developmentMode}.

        The parameters have to be supplied as a single argument JSON string - make sure to correctly
        escape any quotation marks when running from a shell.

        By default, the injected intent request will have a requesting application id of \c{:sysui:}
        (the System UI) and no handling application id. You can use the following command line
        options to change this behavior:

        \c{--requesting-application-id} Fake the requesting application id.

        \c{--application-id} Specify the handling application id to prevent disambiguation.

        \c{--broadcast} Instead of a directed request, create a broadcast.

        Please note that \c{--application-id} and \c{--broadcast} are mutually exclusive.

        For successful non-broadcast requests, the result will be printed to the console as JSON.
\row
    \li \span {style="white-space: nowrap"} {\c set-developer-certificate}
    \li \c{<certificate>}
    \li Sets the developer certificate to be used when \e{development mode} is set to \e
        application. The certificate contains the package ids the developer is allowed to work with
        and the application manager will restict access accordingly.
        The certificate has to be provided as a PKCS#12 file. If it is specified as \c{-}, the tool
        tries to read the package from \c stdin.

        If a password for the PKCS#12 certificate is required, it can be supplied via the
        \c{-p} / \c{--password} option. The same password mechanisms as in the OpenSSL command-line
        tool are supported.

        \list
            \li \b{pass:}\e{passwd}\br
                The password is set as \e passwd. Use this format only when security is not a
                concern, because this method exposes the password to system utilities.
            \li \b{env:}\e{var}\br
                The password is taken from the environment variable \e var. As with the \b{pass:}
                mechanism above, the password is visible to system utilities.
            \li \b{file:}\e{path}\br
                The password is read from the file at \e path. Reading stops at the first newline
                character.
            \li \b{fd:}\e{number}\br
                The password is read from the file descriptor specified by \e number in the same
                way as specified for \b file above. Please note, that this option is not supported
                on Windows.
            \li \b{stdin}\br
                The password is read from standard input in the same way as specified for \b file
                above. If possible, this will directly access the console and disable echoing for
                better security.
        \endlist

        Clearing the currently set developer certificate can be done by not specifying any
        certificate, but just using the option \c{--clear}.

        \b{See also} \l{Package Installation}
\row
    \li \span {style="white-space: nowrap"} {\c show-development-mode}
    \li (none)
    \li Shows the current development mode and set developer certificate of the application manager
        in YAML format. Alternatively, use \c{--json} to get the output in JSON format instead.
\endtable

The \c{appman-controller} naturally supports the standard Unix \c{--help} command-line option.
*/