Branch data Line data Source code
1 : : /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
2 : : *
3 : : * Copyright © 2025 GNOME Foundation, Inc.
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General Public
18 : : * License along with this library; if not, write to the Free Software
19 : : * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 : : *
21 : : * Authors:
22 : : * - Philip Withnall <pwithnall@gnome.org>
23 : : */
24 : :
25 : : #pragma once
26 : :
27 : : #include <gio/gio.h>
28 : : #include <glib.h>
29 : : #include <glib-object.h>
30 : :
31 : : G_BEGIN_DECLS
32 : :
33 : : /**
34 : : * MctWebFilterType:
35 : : * @MCT_WEB_FILTER_TYPE_NONE: The user’s web access is not filtered.
36 : : * @MCT_WEB_FILTER_TYPE_BLOCKLIST: Websites are allowed by default unless
37 : : * they’re listed in one of the block lists or the custom block list. The
38 : : * allow lists and custom allow list override the block lists.
39 : : * @MCT_WEB_FILTER_TYPE_ALLOWLIST: Websites are blocked by default unless
40 : : * they’re listed in one of the allow lists or the custom allow list. The
41 : : * block lists are ignored.
42 : : *
43 : : * Types of web filtering which can be imposed on an account. Additional types
44 : : * may be added in future.
45 : : *
46 : : * Since: 0.14.0
47 : : */
48 : : typedef enum
49 : : {
50 : : /* these values are used in the org.freedesktop.Malcontent.WebFilter
51 : : * D-Bus interface, so must not be changed */
52 : : MCT_WEB_FILTER_TYPE_NONE = 0,
53 : : MCT_WEB_FILTER_TYPE_BLOCKLIST = 1,
54 : : MCT_WEB_FILTER_TYPE_ALLOWLIST = 2,
55 : : } MctWebFilterType;
56 : :
57 : : /**
58 : : * MctWebFilter:
59 : : *
60 : : * [struct@Malcontent.WebFilter] is an opaque, immutable structure which
61 : : * contains a snapshot of the web filter settings for a user at a given time.
62 : : *
63 : : * This includes whether web access is being filtered, and the filter lists
64 : : * which are being applied — for example, the domains to block or allow.
65 : : *
66 : : * Typically, web filter settings can only be changed by the administrator,
67 : : * and are read-only for non-administrative users. The precise policy is set
68 : : * using polkit.
69 : : *
70 : : * To construct a new [struct@Malcontent.WebFilter], use
71 : : * [struct@Malcontent.WebFilterBuilder].
72 : : *
73 : : * ## Filter format
74 : : *
75 : : * A web filter contains various high-level options about web filter, such as
76 : : * whether to block domains by default or to allow them by default; and whether
77 : : * to force popular websites to use their ‘safe search’ variants (for example,
78 : : * Google Safe Search or YouTube Restricted Mode).
79 : : *
80 : : * A web filter can contain zero or more filter lists, as well as custom filter
81 : : * entries. Each list or entry will block or allow the hostnames it lists.
82 : : *
83 : : * The intention is that the user uses one or more subject-specific filter lists
84 : : * sourced online, such as those from [EasyList](https://easylist.to/). Custom
85 : : * filter entries can then be used to add a small number of additional filters
86 : : * to customise the generic filter lists.
87 : : *
88 : : * Each filter list is a mapping from an ID to a URI which contains the list.
89 : : * The ID is needed so user interfaces can consistently refer to the same list
90 : : * in the UI even if its URI changes over time. IDs must be non-empty UTF-8
91 : : * strings.
92 : : *
93 : : * The filter list downloaded from the URI must be a list of hostnames,
94 : : * separated by newlines (`\n`). Comments start with `#` and continue to the
95 : : * next newline (`\n`). Each entry in the list must be a plain hostname — globs,
96 : : * wildcards and regexps are not supported. Hostnames do not have to have a
97 : : * trailing dot (`.`) as in DNS records.
98 : : *
99 : : * This is essentially the same format as `/etc/hosts`, as malcontent is
100 : : * designed to consume general purpose filter lists produced for use in
101 : : * `/etc/hosts`.
102 : : *
103 : : * Custom filter entries must follow the same format: they must be a plain
104 : : * hostname — globs, wildcards and regexps are not supported.
105 : : *
106 : : * Since: 0.14.0
107 : : */
108 : : typedef struct _MctWebFilter MctWebFilter;
109 : : GType mct_web_filter_get_type (void);
110 : : #define MCT_TYPE_WEB_FILTER mct_web_filter_get_type ()
111 : :
112 : : MctWebFilter *mct_web_filter_ref (MctWebFilter *filter);
113 : : void mct_web_filter_unref (MctWebFilter *filter);
114 : :
115 [ + + ]: 50 : G_DEFINE_AUTOPTR_CLEANUP_FUNC (MctWebFilter, mct_web_filter_unref)
116 : :
117 : : uid_t mct_web_filter_get_user_id (MctWebFilter *filter);
118 : :
119 : : gboolean mct_web_filter_is_enabled (MctWebFilter *filter);
120 : :
121 : : MctWebFilterType mct_web_filter_get_filter_type (MctWebFilter *filter);
122 : :
123 : : GHashTable *mct_web_filter_get_block_lists (MctWebFilter *filter);
124 : : const char * const *mct_web_filter_get_custom_block_list (MctWebFilter *filter,
125 : : size_t *out_len);
126 : :
127 : : GHashTable *mct_web_filter_get_allow_lists (MctWebFilter *filter);
128 : : const char * const *mct_web_filter_get_custom_allow_list (MctWebFilter *filter,
129 : : size_t *out_len);
130 : :
131 : : gboolean mct_web_filter_get_force_safe_search (MctWebFilter *filter);
132 : :
133 : : GVariant *mct_web_filter_serialize (MctWebFilter *filter);
134 : : MctWebFilter *mct_web_filter_deserialize (GVariant *variant,
135 : : uid_t user_id,
136 : : GError **error);
137 : :
138 : : gboolean mct_web_filter_equal (MctWebFilter *a,
139 : : MctWebFilter *b);
140 : :
141 : : gboolean mct_web_filter_validate_filter_id (const char *id);
142 : : gboolean mct_web_filter_validate_hostname (const char *hostname);
143 : : gboolean mct_web_filter_validate_hostname_len (const char *hostname,
144 : : size_t max_len);
145 : :
146 : : /**
147 : : * MctWebFilterBuilder:
148 : : *
149 : : * [struct@Malcontent.WebFilterBuilder] is a stack-allocated mutable structure
150 : : * used to build a [struct@Malcontent.WebFilter] instance.
151 : : *
152 : : * Use [method@Malcontent.WebFilterBuilder.init], various method calls to set
153 : : * properties of the web filter, and then
154 : : * [method@Malcontent.WebFilterBuilder.end], to construct a
155 : : * [struct@Malcontent.WebFilter].
156 : : *
157 : : * Since: 0.14.0
158 : : */
159 : : typedef struct
160 : : {
161 : : /*< private >*/
162 : : int i0;
163 : : void *p0;
164 : : void *p1;
165 : : void *p2;
166 : : void *p3;
167 : : gboolean b0;
168 : : gpointer p4[10];
169 : : } MctWebFilterBuilder;
170 : :
171 : : GType mct_web_filter_builder_get_type (void);
172 : :
173 : : /**
174 : : * MCT_WEB_FILTER_BUILDER_INIT:
175 : : *
176 : : * Initialise a stack-allocated #MctWebFilterBuilder instance at declaration
177 : : * time.
178 : : *
179 : : * This is typically used with g_auto():
180 : : * |[
181 : : * g_auto(MctWebFilterBuilder) builder = MCT_WEB_FILTER_BUILDER_INIT ();
182 : : * ]|
183 : : *
184 : : * Since: 0.14.0
185 : : */
186 : : #define MCT_WEB_FILTER_BUILDER_INIT() \
187 : : { \
188 : : 0, /* MCT_WEB_FILTER_TYPE_NONE */ \
189 : : NULL, \
190 : : NULL, \
191 : : NULL, \
192 : : NULL, \
193 : : FALSE, \
194 : : /* padding: */ \
195 : : { NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL } \
196 : : }
197 : :
198 : : void mct_web_filter_builder_init (MctWebFilterBuilder *builder);
199 : : void mct_web_filter_builder_clear (MctWebFilterBuilder *builder);
200 : :
201 : 3 : G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC (MctWebFilterBuilder,
202 : : mct_web_filter_builder_clear)
203 : :
204 : : MctWebFilterBuilder *mct_web_filter_builder_new (void);
205 : : MctWebFilterBuilder *mct_web_filter_builder_copy (MctWebFilterBuilder *builder);
206 : : void mct_web_filter_builder_free (MctWebFilterBuilder *builder);
207 : :
208 [ # # ]: 0 : G_DEFINE_AUTOPTR_CLEANUP_FUNC (MctWebFilterBuilder, mct_web_filter_builder_free)
209 : :
210 : : MctWebFilter *mct_web_filter_builder_end (MctWebFilterBuilder *builder);
211 : :
212 : : void mct_web_filter_builder_set_filter_type (MctWebFilterBuilder *builder,
213 : : MctWebFilterType filter_type);
214 : :
215 : : void mct_web_filter_builder_add_block_list (MctWebFilterBuilder *builder,
216 : : const char *id,
217 : : const char *filter_uri);
218 : : void mct_web_filter_builder_add_custom_block_list_entry (MctWebFilterBuilder *builder,
219 : : const char *hostname);
220 : :
221 : : void mct_web_filter_builder_add_allow_list (MctWebFilterBuilder *builder,
222 : : const char *id,
223 : : const char *filter_uri);
224 : : void mct_web_filter_builder_add_custom_allow_list_entry (MctWebFilterBuilder *builder,
225 : : const char *hostname);
226 : :
227 : : void mct_web_filter_builder_set_force_safe_search (MctWebFilterBuilder *builder,
228 : : gboolean force_safe_search);
229 : :
230 : : G_END_DECLS
|
