1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
4 SPDX-FileCopyrightText: 1998, 1999 Waldo Bastian <bastian@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KURLAUTHORIZED_H
10#define KURLAUTHORIZED_H
11
12#include "kiocore_export.h"
13
14#include <KAuthorized>
15
16class QUrl;
17class QString;
18
19/*!
20 * \namespace KUrlAuthorized
21 * \inmodule KIOCore
22 *
23 * \brief The functions in this namespace allow actions to be restricted based
24 * on the URL they operate on (see the KAuthorized namespace in
25 * KConfig).
26 *
27 * As with KAuthorized functions, the relevant settings are read from
28 * the application's KSharedConfig instance, so actions can be disabled
29 * on a per-application or global basis (by using the kdeglobals file).
30 *
31 * URLs can be matched based on protocol, host and path, and the
32 * referring URL can be taken into account.
33 *
34 * URL-based restrictions are recorded using this syntax:
35 * \badcode
36 * [KDE URL Restrictions]
37 * rule_count=<N>
38 * rule_1=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
39 * ...
40 * rule_N=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
41 * \endcode
42 *
43 * The following standard actions are defined:
44 * \list
45 * \li redirect: A common example is a web page redirecting to another web
46 * page. By default, internet protocols are not permitted
47 * to redirect to the "file" protocol, but you could
48 * override this for a specific host, for example:
49 * \code
50 * [KDE URL Restrictions]
51 * rule_count=1
52 * rule_1=redirect,http,myhost.example.com,,file,,,true
53 * \endcode
54 * \li list: Determines whether a URL can be browsed, in an "open" or
55 * "save" dialog, for example. If a user should only be
56 * able to browse files under home directory one could use:
57 * \code
58 * [KDE URL Restrictions]
59 * rule_count=2
60 * rule_1=list,,,,file,,,false
61 * rule_2=list,,,,file,,$HOME,true
62 * \endcode
63 * The first rule disables browsing any directories on the
64 * local filesystem. The second rule then enables browsing
65 * the users home directory.
66 * \li open: This controls which files can be opened by the user in
67 * sapplications. It also affects where users can save files.
68 * To only allow a user to open the files in his own home
69 * directory one could use:
70 * \code
71 * [KDE URL Restrictions]
72 * rule_count=3
73 * rule_1=open,,,,file,,,false
74 * rule_2=open,,,,file,,$HOME,true
75 * rule_3=open,,,,file,,$TMP,true
76 * \endcode
77 * Note that with the above, users would still be able to
78 * open files from the internet. Note also that the user is
79 * also given access to $TMP in order to ensure correct
80 * operation of KDE applications. $TMP is replaced with the
81 * temporary directory that KDE uses for this user.
82 * \li link: Determines whether a URL can be linked to.
83 * \endlist
84 *
85 * Some remarks:
86 * \list
87 * \li empty entries match everything
88 * \li host names may start with a wildcard, e.g. "*.acme.com"
89 * \li a protocol also matches similar protocols that start with the same name,
90 * e.g. "http" matches both http and https. You can use "http!" if you only want to
91 * match http (and not https)
92 * \li specifying a path matches all URLs that start with the same path. For better results
93 * you should not include a trailing slash. If you want to specify one specific path, you can
94 * add an exclamation mark. E.g. "/srv" matches both "/srv" and "/srv/www" but "/srv!" only
95 * matches "/srv" and not "/srv/www".
96 * \endlist
97 */
98namespace KUrlAuthorized
99{
100/*!
101 * Returns whether a certain URL related action is authorized.
102 *
103 * \a action The name of the action, typically one of "list",
104 * "link", "open" or "redirect".
105 * \a baseUrl The url where the action originates from.
106 *
107 * \a destUrl The object of the action.
108 *
109 * Returns \c true if the action is authorized, \c false
110 * otherwise.
111 *
112 * \sa allowUrlAction()
113 * \since 5.0
114 */
115KIOCORE_EXPORT bool authorizeUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
116
117/*!
118 * Override Kiosk restrictions to allow a given URL action.
119 *
120 * This can be useful if your application needs to ensure access to an
121 * application-specific directory that may otherwise be subject to Kiosk
122 * restrictions.
123 *
124 * \a action The name of the action.
125 *
126 * \a baseUrl The url where the action originates from.
127 *
128 * \a destUrl The object of the action.
129 *
130 * \sa authorizeUrlAction()
131 * \since 5.0
132 */
133KIOCORE_EXPORT void allowUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
134
135}
136
137#endif
138

source code of kio/src/core/kurlauthorized.h