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.
44 : : *
45 : : * Additional types may be added in future.
46 : : *
47 : : * Since: 0.14.0
48 : : */
49 : : typedef enum
50 : : {
51 : : /* these values are used in the org.freedesktop.Malcontent.WebFilter
52 : : * D-Bus interface, so must not be changed */
53 : : MCT_WEB_FILTER_TYPE_NONE = 0,
54 : : MCT_WEB_FILTER_TYPE_BLOCKLIST = 1,
55 : : MCT_WEB_FILTER_TYPE_ALLOWLIST = 2,
56 : : } MctWebFilterType;
57 : :
58 : : /**
59 : : * MctWebFilter:
60 : : *
61 : : * [struct@Malcontent.WebFilter] is an opaque, immutable structure which
62 : : * contains a snapshot of the web filter settings for a user at a given time.
63 : : *
64 : : * This includes whether web access is being filtered, and the filter lists
65 : : * which are being applied — for example, the domains to block or allow.
66 : : *
67 : : * Typically, web filter settings can only be changed by the administrator,
68 : : * and are read-only for non-administrative users. The precise policy is set
69 : : * using polkit.
70 : : *
71 : : * To construct a new [struct@Malcontent.WebFilter], use
72 : : * [struct@Malcontent.WebFilterBuilder].
73 : : *
74 : : * ## Filter format
75 : : *
76 : : * A web filter contains various high-level options about web filter, such as
77 : : * whether to block domains by default or to allow them by default; and whether
78 : : * to force popular websites to use their ‘safe search’ variants (for example,
79 : : * Google Safe Search or YouTube Restricted Mode).
80 : : *
81 : : * A web filter can contain zero or more filter lists, as well as custom filter
82 : : * entries. Each list or entry will block or allow the hostnames it lists.
83 : : *
84 : : * The intention is that the user uses one or more subject-specific filter lists
85 : : * sourced online, such as those from [EasyList](https://easylist.to/). Custom
86 : : * filter entries can then be used to add a small number of additional filters
87 : : * to customise the generic filter lists.
88 : : *
89 : : * Each filter list is a mapping from an ID to a URI which contains the list.
90 : : * The ID is needed so user interfaces can consistently refer to the same list
91 : : * in the UI even if its URI changes over time. IDs must be non-empty UTF-8
92 : : * strings.
93 : : *
94 : : * The filter list downloaded from the URI must be a list of hostnames,
95 : : * separated by newlines (`\n`). Comments start with `#` and continue to the
96 : : * next newline (`\n`). Each entry in the list must be a plain hostname — globs,
97 : : * wildcards and regexps are not supported. Hostnames do not have to have a
98 : : * trailing dot (`.`) as in DNS records.
99 : : *
100 : : * This is essentially the same format as `/etc/hosts`, as malcontent is
101 : : * designed to consume general purpose filter lists produced for use in
102 : : * `/etc/hosts`.
103 : : *
104 : : * Custom filter entries must follow the same format: they must be a plain
105 : : * hostname — globs, wildcards and regexps are not supported.
106 : : *
107 : : * Since: 0.14.0
108 : : */
109 : : typedef struct _MctWebFilter MctWebFilter;
110 : : GType mct_web_filter_get_type (void);
111 : : #define MCT_TYPE_WEB_FILTER mct_web_filter_get_type ()
112 : :
113 : : MctWebFilter *mct_web_filter_ref (MctWebFilter *filter);
114 : : void mct_web_filter_unref (MctWebFilter *filter);
115 : :
116 [ + + ]: 50 : G_DEFINE_AUTOPTR_CLEANUP_FUNC (MctWebFilter, mct_web_filter_unref)
117 : :
118 : : uid_t mct_web_filter_get_user_id (MctWebFilter *filter);
119 : :
120 : : gboolean mct_web_filter_is_enabled (MctWebFilter *filter);
121 : :
122 : : MctWebFilterType mct_web_filter_get_filter_type (MctWebFilter *filter);
123 : :
124 : : GHashTable *mct_web_filter_get_block_lists (MctWebFilter *filter);
125 : : const char * const *mct_web_filter_get_custom_block_list (MctWebFilter *filter,
126 : : size_t *out_len);
127 : :
128 : : GHashTable *mct_web_filter_get_allow_lists (MctWebFilter *filter);
129 : : const char * const *mct_web_filter_get_custom_allow_list (MctWebFilter *filter,
130 : : size_t *out_len);
131 : :
132 : : gboolean mct_web_filter_get_force_safe_search (MctWebFilter *filter);
133 : :
134 : : GVariant *mct_web_filter_serialize (MctWebFilter *filter);
135 : : MctWebFilter *mct_web_filter_deserialize (GVariant *variant,
136 : : uid_t user_id,
137 : : GError **error);
138 : :
139 : : gboolean mct_web_filter_equal (MctWebFilter *a,
140 : : MctWebFilter *b);
141 : :
142 : : gboolean mct_web_filter_validate_filter_id (const char *id);
143 : : gboolean mct_web_filter_validate_hostname (const char *hostname);
144 : : gboolean mct_web_filter_validate_hostname_len (const char *hostname,
145 : : size_t max_len);
146 : : gboolean mct_web_filter_validate_domain_name (const char *domain_name);
147 : : gboolean mct_web_filter_validate_domain_name_len (const char *domain_name,
148 : : size_t max_len);
149 : :
150 : : /**
151 : : * MctWebFilterBuilder:
152 : : *
153 : : * [struct@Malcontent.WebFilterBuilder] is a stack-allocated mutable structure
154 : : * used to build a [struct@Malcontent.WebFilter] instance.
155 : : *
156 : : * Use [method@Malcontent.WebFilterBuilder.init], various method calls to set
157 : : * properties of the web filter, and then
158 : : * [method@Malcontent.WebFilterBuilder.end], to construct a
159 : : * [struct@Malcontent.WebFilter].
160 : : *
161 : : * Since: 0.14.0
162 : : */
163 : : typedef struct
164 : : {
165 : : /*< private >*/
166 : : int i0;
167 : : void *p0;
168 : : void *p1;
169 : : void *p2;
170 : : void *p3;
171 : : gboolean b0;
172 : : gpointer p4[10];
173 : : } MctWebFilterBuilder;
174 : :
175 : : GType mct_web_filter_builder_get_type (void);
176 : :
177 : : /**
178 : : * MCT_WEB_FILTER_BUILDER_INIT:
179 : : *
180 : : * Initialise a stack-allocated [struct@Malcontent.WebFilterBuilder] instance at
181 : : * declaration time.
182 : : *
183 : : * This is typically used with `g_auto()`:
184 : : * ```c
185 : : * g_auto(MctWebFilterBuilder) builder = MCT_WEB_FILTER_BUILDER_INIT ();
186 : : * ```
187 : : *
188 : : * Since: 0.14.0
189 : : */
190 : : #define MCT_WEB_FILTER_BUILDER_INIT() \
191 : : { \
192 : : 0, /* MCT_WEB_FILTER_TYPE_NONE */ \
193 : : NULL, \
194 : : NULL, \
195 : : NULL, \
196 : : NULL, \
197 : : FALSE, \
198 : : /* padding: */ \
199 : : { NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL } \
200 : : }
201 : :
202 : : void mct_web_filter_builder_init (MctWebFilterBuilder *builder);
203 : : void mct_web_filter_builder_clear (MctWebFilterBuilder *builder);
204 : :
205 : 3 : G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC (MctWebFilterBuilder,
206 : : mct_web_filter_builder_clear)
207 : :
208 : : MctWebFilterBuilder *mct_web_filter_builder_new (void);
209 : : MctWebFilterBuilder *mct_web_filter_builder_copy (MctWebFilterBuilder *builder);
210 : : void mct_web_filter_builder_free (MctWebFilterBuilder *builder);
211 : :
212 [ # # ]: 0 : G_DEFINE_AUTOPTR_CLEANUP_FUNC (MctWebFilterBuilder, mct_web_filter_builder_free)
213 : :
214 : : MctWebFilter *mct_web_filter_builder_end (MctWebFilterBuilder *builder);
215 : :
216 : : void mct_web_filter_builder_set_filter_type (MctWebFilterBuilder *builder,
217 : : MctWebFilterType filter_type);
218 : :
219 : : void mct_web_filter_builder_add_block_list (MctWebFilterBuilder *builder,
220 : : const char *id,
221 : : const char *filter_uri);
222 : : void mct_web_filter_builder_add_custom_block_list_entry (MctWebFilterBuilder *builder,
223 : : const char *hostname);
224 : :
225 : : void mct_web_filter_builder_add_allow_list (MctWebFilterBuilder *builder,
226 : : const char *id,
227 : : const char *filter_uri);
228 : : void mct_web_filter_builder_add_custom_allow_list_entry (MctWebFilterBuilder *builder,
229 : : const char *hostname);
230 : :
231 : : void mct_web_filter_builder_set_force_safe_search (MctWebFilterBuilder *builder,
232 : : gboolean force_safe_search);
233 : :
234 : : G_END_DECLS
|
