// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qt-add-harmonyos-permission.html
\ingroup cmake-commands-qtcore

\title qt_add_harmonyos_permission
\keyword qt6_add_harmonyos_permission

\summary {Adds a HarmonyOS permission to the target executable.}

\include cmake-find-package-core.qdocinc

\cmakecommandsince 6.12
\preliminarycmakecommand
\cmakecommandharmonyosonly

\section1 Synopsis

\badcode
qt_add_harmonyos_permission(target
    NAME <permission-name>
    [REASON <reason>]
    [USED_SCENE_ABILITIES <ability> [<ability>...]]
    [USED_SCENE_WHEN inuse | always]
)
\endcode

\versionlessCMakeCommandsNote qt6_add_harmonyos_permission()

\section1 Description

The command adds a HarmonyOS permission to the \c {target} executable. The
permission is written into the \c {requestPermissions} array of the generated
\c {module.json5} manifest when the HAP package is built. Use this command to
request additional permissions on top of the default permissions contributed
by the Qt modules your application links against.

For the list of available permission names and their requirements, see the
HarmonyOS application permission documentation.

\section1 Arguments

\c NAME is the permission identifier, for example
\c {ohos.permission.CAMERA}. It is the only required argument.

\c REASON is the message shown to the user when the system prompts for a
\c user_grant permission. It accepts either a literal string or a
\c {$string:<name>} resource reference that resolves to a localized string
from the application's resource files. Specifying \c REASON causes a
\c usedScene block to be emitted for the permission.

\c USED_SCENE_ABILITIES is the list of abilities that use the permission. If
omitted while a \c usedScene block is emitted, it defaults to \c QAbility,
which is the single ability that hosts a Qt application.

\c USED_SCENE_WHEN sets when the permission is accessed. The accepted values
are \c inuse (the permission is used only while the application is in the
foreground) and \c always (the permission is also used in the background). If
omitted while a \c usedScene block is emitted, it defaults to \c inuse.

\section1 Example

\snippet cmake-macros/examples.cmake qt_add_harmonyos_permission

\sa {Qt for HarmonyOS CMake API}
*/
