Branch data Line data Source code
1 : : /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 : :
3 : : /* GIO - GLib Input, Output and Streaming Library
4 : : *
5 : : * Copyright (C) 2006-2007 Red Hat, Inc.
6 : : *
7 : : * SPDX-License-Identifier: LGPL-2.1-or-later
8 : : *
9 : : * This library is free software; you can redistribute it and/or
10 : : * modify it under the terms of the GNU Lesser General Public
11 : : * License as published by the Free Software Foundation; either
12 : : * version 2.1 of the License, or (at your option) any later version.
13 : : *
14 : : * This library is distributed in the hope that it will be useful,
15 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 : : * Lesser General Public License for more details.
18 : : *
19 : : * You should have received a copy of the GNU Lesser General
20 : : * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
21 : : *
22 : : * Author: Alexander Larsson <alexl@redhat.com>
23 : : */
24 : :
25 : : #include "config.h"
26 : : #include "gcontenttypeprivate.h"
27 : : #include "gfile.h"
28 : :
29 : :
30 : : /**
31 : : * GContentType:
32 : : *
33 : : * A content type is a platform specific string that defines the type
34 : : * of a file. On UNIX it is a
35 : : * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type)
36 : : * like `text/plain` or `image/png`.
37 : : * On Win32 it is an extension string like `.doc`, `.txt` or a perceived
38 : : * string like `audio`. Such strings can be looked up in the registry at
39 : : * `HKEY_CLASSES_ROOT`.
40 : : * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier)
41 : : * such as `com.apple.application`.
42 : : **/
43 : :
44 : : /**
45 : : * g_content_type_set_mime_dirs:
46 : : * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of
47 : : * directories to load MIME data from, including any `mime/` subdirectory,
48 : : * and with the first directory to try listed first
49 : : *
50 : : * Set the list of directories used by GIO to load the MIME database.
51 : : * If @dirs is %NULL, the directories used are the default:
52 : : *
53 : : * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME`
54 : : * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS`
55 : : *
56 : : * This function is intended to be used when writing tests that depend on
57 : : * information stored in the MIME database, in order to control the data.
58 : : *
59 : : * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they
60 : : * depend on the system’s MIME database, you should call this function
61 : : * with @dirs set to %NULL before calling g_test_init(), for instance:
62 : : *
63 : : * |[<!-- language="C" -->
64 : : * // Load MIME data from the system
65 : : * g_content_type_set_mime_dirs (NULL);
66 : : * // Isolate the environment
67 : : * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);
68 : : *
69 : : * …
70 : : *
71 : : * return g_test_run ();
72 : : * ]|
73 : : *
74 : : * Since: 2.60
75 : : */
76 : : void
77 : 1 : g_content_type_set_mime_dirs (const gchar * const *dirs)
78 : : {
79 : 1 : g_content_type_set_mime_dirs_impl (dirs);
80 : 1 : }
81 : :
82 : : /**
83 : : * g_content_type_get_mime_dirs:
84 : : *
85 : : * Get the list of directories which MIME data is loaded from. See
86 : : * g_content_type_set_mime_dirs() for details.
87 : : *
88 : : * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of
89 : : * directories to load MIME data from, including any `mime/` subdirectory,
90 : : * and with the first directory to try listed first
91 : : * Since: 2.60
92 : : */
93 : : const gchar * const *
94 : 3 : g_content_type_get_mime_dirs (void)
95 : : {
96 : 3 : return g_content_type_get_mime_dirs_impl ();
97 : : }
98 : :
99 : : /**
100 : : * g_content_type_equals:
101 : : * @type1: a content type string
102 : : * @type2: a content type string
103 : : *
104 : : * Compares two content types for equality.
105 : : *
106 : : * Returns: %TRUE if the two strings are identical or equivalent,
107 : : * %FALSE otherwise.
108 : : */
109 : : gboolean
110 : 370 : g_content_type_equals (const gchar *type1,
111 : : const gchar *type2)
112 : : {
113 : 370 : g_return_val_if_fail (type1 != NULL, FALSE);
114 : 370 : g_return_val_if_fail (type2 != NULL, FALSE);
115 : :
116 : 370 : return g_content_type_equals_impl (type1, type2);
117 : : }
118 : :
119 : : /**
120 : : * g_content_type_is_a:
121 : : * @type: a content type string
122 : : * @supertype: a content type string
123 : : *
124 : : * Determines if @type is a subset of @supertype.
125 : : *
126 : : * Returns: %TRUE if @type is a kind of @supertype,
127 : : * %FALSE otherwise.
128 : : */
129 : : gboolean
130 : 10 : g_content_type_is_a (const gchar *type,
131 : : const gchar *supertype)
132 : : {
133 : 10 : g_return_val_if_fail (type != NULL, FALSE);
134 : 10 : g_return_val_if_fail (supertype != NULL, FALSE);
135 : :
136 : 10 : return g_content_type_is_a_impl (type, supertype);
137 : : }
138 : :
139 : : /**
140 : : * g_content_type_is_mime_type:
141 : : * @type: a content type string
142 : : * @mime_type: a mime type string
143 : : *
144 : : * Determines if @type is a subset of @mime_type.
145 : : * Convenience wrapper around g_content_type_is_a().
146 : : *
147 : : * Returns: %TRUE if @type is a kind of @mime_type,
148 : : * %FALSE otherwise.
149 : : *
150 : : * Since: 2.52
151 : : */
152 : : gboolean
153 : 1 : g_content_type_is_mime_type (const gchar *type,
154 : : const gchar *mime_type)
155 : : {
156 : 1 : g_return_val_if_fail (type != NULL, FALSE);
157 : 1 : g_return_val_if_fail (mime_type != NULL, FALSE);
158 : :
159 : 1 : return g_content_type_is_mime_type_impl (type, mime_type);
160 : : }
161 : :
162 : : /**
163 : : * g_content_type_is_unknown:
164 : : * @type: a content type string
165 : : *
166 : : * Checks if the content type is the generic "unknown" type.
167 : : * On UNIX this is the "application/octet-stream" mimetype,
168 : : * while on win32 it is "*" and on OSX it is a dynamic type
169 : : * or octet-stream.
170 : : *
171 : : * Returns: %TRUE if the type is the unknown type.
172 : : */
173 : : gboolean
174 : 1 : g_content_type_is_unknown (const gchar *type)
175 : : {
176 : 1 : g_return_val_if_fail (type != NULL, FALSE);
177 : :
178 : 1 : return g_content_type_is_unknown_impl (type);
179 : : }
180 : :
181 : : /**
182 : : * g_content_type_get_description:
183 : : * @type: a content type string
184 : : *
185 : : * Gets the human readable description of the content type.
186 : : *
187 : : * Returns: a short description of the content type @type. Free the
188 : : * returned string with g_free()
189 : : */
190 : : gchar *
191 : 1 : g_content_type_get_description (const gchar *type)
192 : : {
193 : 1 : g_return_val_if_fail (type != NULL, NULL);
194 : :
195 : 1 : return g_content_type_get_description_impl (type);
196 : : }
197 : :
198 : : /**
199 : : * g_content_type_get_mime_type:
200 : : * @type: a content type string
201 : : *
202 : : * Gets the mime type for the content type, if one is registered.
203 : : *
204 : : * Returns: (nullable) (transfer full): the registered mime type for the
205 : : * given @type, or %NULL if unknown; free with g_free().
206 : : */
207 : : char *
208 : 2 : g_content_type_get_mime_type (const char *type)
209 : : {
210 : 2 : g_return_val_if_fail (type != NULL, NULL);
211 : :
212 : 2 : return g_content_type_get_mime_type_impl (type);
213 : : }
214 : :
215 : : /**
216 : : * g_content_type_get_icon:
217 : : * @type: a content type string
218 : : *
219 : : * Gets the icon for a content type.
220 : : *
221 : : * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
222 : : * object with g_object_unref()
223 : : */
224 : : GIcon *
225 : 78 : g_content_type_get_icon (const gchar *type)
226 : : {
227 : 78 : g_return_val_if_fail (type != NULL, NULL);
228 : :
229 : 78 : return g_content_type_get_icon_impl (type);
230 : : }
231 : :
232 : : /**
233 : : * g_content_type_get_symbolic_icon:
234 : : * @type: a content type string
235 : : *
236 : : * Gets the symbolic icon for a content type.
237 : : *
238 : : * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
239 : : * Free the returned object with g_object_unref()
240 : : *
241 : : * Since: 2.34
242 : : */
243 : : GIcon *
244 : 78 : g_content_type_get_symbolic_icon (const gchar *type)
245 : : {
246 : 78 : g_return_val_if_fail (type != NULL, NULL);
247 : :
248 : 78 : return g_content_type_get_symbolic_icon_impl (type);
249 : : }
250 : :
251 : : /**
252 : : * g_content_type_get_generic_icon_name:
253 : : * @type: a content type string
254 : : *
255 : : * Gets the generic icon name for a content type.
256 : : *
257 : : * See the
258 : : * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
259 : : * specification for more on the generic icon name.
260 : : *
261 : : * Returns: (nullable): the registered generic icon name for the given @type,
262 : : * or %NULL if unknown. Free with g_free()
263 : : *
264 : : * Since: 2.34
265 : : */
266 : : gchar *
267 : 156 : g_content_type_get_generic_icon_name (const gchar *type)
268 : : {
269 : 156 : g_return_val_if_fail (type != NULL, NULL);
270 : :
271 : 156 : return g_content_type_get_generic_icon_name_impl (type);
272 : : }
273 : :
274 : : /**
275 : : * g_content_type_can_be_executable:
276 : : * @type: a content type string
277 : : *
278 : : * Checks if a content type can be executable. Note that for instance
279 : : * things like text files can be executables (i.e. scripts and batch files).
280 : : *
281 : : * Returns: %TRUE if the file type corresponds to a type that
282 : : * can be executable, %FALSE otherwise.
283 : : */
284 : : gboolean
285 : 3 : g_content_type_can_be_executable (const gchar *type)
286 : : {
287 : 3 : g_return_val_if_fail (type != NULL, FALSE);
288 : :
289 : 3 : return g_content_type_can_be_executable_impl (type);
290 : : }
291 : :
292 : : /**
293 : : * g_content_type_from_mime_type:
294 : : * @mime_type: a mime type string
295 : : *
296 : : * Tries to find a content type based on the mime type name.
297 : : *
298 : : * Returns: (nullable): Newly allocated string with content type or
299 : : * %NULL. Free with g_free()
300 : : *
301 : : * Since: 2.18
302 : : **/
303 : : gchar *
304 : 167 : g_content_type_from_mime_type (const gchar *mime_type)
305 : : {
306 : 167 : g_return_val_if_fail (mime_type != NULL, NULL);
307 : :
308 : 167 : return g_content_type_from_mime_type_impl (mime_type);
309 : : }
310 : :
311 : : /**
312 : : * g_content_type_guess:
313 : : * @filename: (nullable) (type filename): a path, or %NULL
314 : : * @data: (nullable) (array length=data_size): a stream of data, or %NULL
315 : : * @data_size: the size of @data
316 : : * @result_uncertain: (out) (optional): return location for the certainty
317 : : * of the result, or %NULL
318 : : *
319 : : * Guesses the content type based on example data. If the function is
320 : : * uncertain, @result_uncertain will be set to %TRUE. Either @filename
321 : : * or @data may be %NULL, in which case the guess will be based solely
322 : : * on the other argument.
323 : : *
324 : : * Returns: a string indicating a guessed content type for the
325 : : * given data. Free with g_free()
326 : : */
327 : : gchar *
328 : 50 : g_content_type_guess (const gchar *filename,
329 : : const guchar *data,
330 : : gsize data_size,
331 : : gboolean *result_uncertain)
332 : : {
333 : 50 : return g_content_type_guess_impl (filename, data, data_size, result_uncertain);
334 : : }
335 : :
336 : : /**
337 : : * g_content_types_get_registered:
338 : : *
339 : : * Gets a list of strings containing all the registered content types
340 : : * known to the system. The list and its data should be freed using
341 : : * `g_list_free_full (list, g_free)`.
342 : : *
343 : : * Returns: (element-type utf8) (transfer full): list of the registered
344 : : * content types
345 : : */
346 : : GList *
347 : 1 : g_content_types_get_registered (void)
348 : : {
349 : 1 : return g_content_types_get_registered_impl ();
350 : : }
351 : :
352 : : /**
353 : : * g_content_type_guess_for_tree:
354 : : * @root: the root of the tree to guess a type for
355 : : *
356 : : * Tries to guess the type of the tree with root @root, by
357 : : * looking at the files it contains. The result is an array
358 : : * of content types, with the best guess coming first.
359 : : *
360 : : * The types returned all have the form x-content/foo, e.g.
361 : : * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
362 : : * (for a camera memory card). See the
363 : : * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
364 : : * specification for more on x-content types.
365 : : *
366 : : * This function is useful in the implementation of
367 : : * g_mount_guess_content_type().
368 : : *
369 : : * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
370 : : * array of zero or more content types. Free with g_strfreev()
371 : : *
372 : : * Since: 2.18
373 : : */
374 : : gchar **
375 : 4 : g_content_type_guess_for_tree (GFile *root)
376 : : {
377 : 4 : g_return_val_if_fail (G_IS_FILE (root), NULL);
378 : :
379 : 4 : return g_content_type_guess_for_tree_impl (root);
380 : : }
|
