KDELibs4Support

kmimetype.h
1 /* This file is part of the KDE libraries
2  * Copyright (C) 1999 Waldo Bastian <[email protected]>
3  * David Faure <[email protected]>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Library General Public
7  * License version 2 as published by the Free Software Foundation;
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public License
15  * along with this library; see the file COPYING.LIB. If not, write to
16  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  **/
19 
20 #ifndef __kmimetype_h__
21 #define __kmimetype_h__
22 
23 #include "kdelibs4support_export.h"
24 
25 #include <QStringList>
26 #include <QList>
27 
28 #include <ksycocatype.h>
29 #include <kservicetype.h>
30 
31 #include <sys/types.h>
32 #include <sys/stat.h>
33 
34 class QMimeType;
35 class QUrl;
36 class KMimeTypePrivate;
37 
38 /**
39  * Represent a mime type, like "text/plain", and the data that is associated
40  * with it.
41  *
42  * The starting point you need is often the static methods.
43  *
44  * KMimeType inherits KServiceType because "text/plain" can be used to find
45  * services (apps and components) "which can open text/plain".
46  *
47  * @see KServiceType
48  * @deprecated use QMimeType, see https://community.kde.org/Frameworks/Porting_Notes#Mime_Types
49  */
50 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KMimeType : public QSharedData
51 {
52  Q_DECLARE_PRIVATE(KMimeType)
53 public:
54  struct Ptr : QExplicitlySharedDataPointer<KMimeType> {
55  Ptr(KMimeType *ptr = nullptr) : QExplicitlySharedDataPointer<KMimeType>(ptr) {}
56  bool isNull() const
57  {
58  return !constData();
59  }
60  };
61  typedef QList<Ptr> List;
62 
63  /**
64  * Construct a KMimeType from a QMimeType.
65  * This is mostly useful as a temporary measure during porting.
66  */
67  KMimeType(const QMimeType &mime);
68 
69  virtual ~KMimeType();
70 
71  /**
72  * @return the name of this entry
73  */
74  QString name() const;
75 
76  /**
77  * Return the filename of the icon associated with the mimetype.
78  * Use KIconLoader::loadMimeTypeIcon to load the icon.
79  *
80  * @return The name of the icon associated with this MIME type.
81  */
82  QString iconName() const;
83 
84  /**
85  * Return the "favicon" (see http://www.favicon.com) for the given @p url,
86  * if available. Does NOT attempt to download the favicon, it only returns
87  * one that is already available.
88  *
89  * If unavailable, returns QString().
90  * @param url the URL of the favicon
91  * @return the name of the favicon, or QString()
92  * @deprecated use KIO::favIconForUrl
93  */
94  static QString favIconForUrl(const QUrl &url);
95 
96  /**
97  * Return the filename of the icon associated with the mimetype, for a given url.
98  * Use KIconLoader::loadMimeTypeIcon to load the icon.
99  * @param url URL for the file
100  * @param mode the mode of the file. The mode may modify the icon
101  * with overlays that show special properties of the
102  * icon. Use 0 for default
103  * @return the name of the icon. The name of a default icon if there is no icon
104  * for the mime type
105  * @deprecated use KIO::iconNameForUrl
106  */
107  static QString iconNameForUrl(const QUrl &url, mode_t mode = 0);
108 
109  /**
110  * Returns the descriptive comment associated with the MIME type.
111  *
112  * @return The descriptive comment associated with the MIME type, if any.
113  */
114  QString comment() const;
115 
116  /**
117  * Retrieve the list of patterns associated with the MIME Type.
118  * @return a list of file globs that describe the file names
119  * (or, usually, the extensions) of files with this mime type
120  */
121  QStringList patterns() const;
122 
123  // DontResolveAlias was removed for kde 5, there was no use case for it.
124  enum FindByNameOption { ResolveAliases = 1 };
125 
126  /**
127  * Retrieve a pointer to the mime type @p name
128  *
129  * @em Very @em important: Don't store the result in a KMimeType* !
130  *
131  * Also note that you get a new KMimeType pointer every time you call this.
132  * Don't ever write code that compares mimetype pointers, compare names instead.
133  *
134  * @param name the name of the mime type
135  * @param options controls how the mime type is searched for
136  * @return the pointer to the KMimeType with the given @p name, or
137  * 0 if not found
138  * @see KServiceType::serviceType
139  */
140  static Ptr mimeType(const QString &name, FindByNameOption options = ResolveAliases);
141 
142  /**
143  * Finds a KMimeType with the given @p url.
144  * This function looks at mode_t first.
145  * If that does not help it looks at the extension (and the contents, for local files).
146  * This method is fine for many protocols like ftp, file, fish, zip etc.,
147  * but is not for http (e.g. cgi scripts
148  * make extension-based checking unreliable).
149  * For HTTP you should use KRun instead (to open the URL, in an app
150  * or internally), or a KIO::mimetype() job (to find the mimetype without
151  * downloading), or a KIO::get() job (to find the mimetype and then download).
152  * In fact KRun is the most complete solution, but deriving from it just
153  * for this is a bit cumbersome.
154  *
155  * If no extension matches, then the file contents will be examined if the URL is a local file, or
156  * "application/octet-stream" is returned otherwise.
157  *
158  * @param url Is the right most URL with a filesystem protocol. It
159  * is up to you to find out about that if you have a nested
160  * URL. For example
161  * "http://localhost/mist.gz#gzip:/decompress" would have to
162  * pass the "http://..." URL part, while
163  * "file:/tmp/x.tar#tar:/src/test.gz#gzip:/decompress" would
164  * have to pass the "tar:/..." part of the URL, since gzip is
165  * a filter protocol and not a filesystem protocol.
166  * @param mode the mode of the file (used, for example, to identify
167  * executables)
168  * @param is_local_file true if the file is local; false if not, or if you don't know.
169  * @param fast_mode If set to true no disk access is allowed to
170  * find out the mimetype. The result may be suboptimal, but
171  * it is @em fast.
172  * @param accuracy if set, the accuracy of the result, between 0 and 100.
173  * For instance, when the extension was used to determine the mimetype,
174  * the accuracy is set to 80, as per the shared-mime spec.
175  * Some 'magic' rules (used when !fast_mode) have an accuracy > 80
176  * (and have priority over the filename, others are < 80).
177  *
178  * @return A pointer to the matching mimetype. 0 is never returned.
179  * @em Very @em Important: Don't store the result in a KMimeType* !
180  */
181  static Ptr findByUrl(const QUrl &url, mode_t mode = 0,
182  bool is_local_file = false, bool fast_mode = false,
183  int *accuracy = nullptr);
184  /**
185  * Finds a KMimeType with the given @p url.
186  * This function looks at mode_t first.
187  * If that does not help it
188  * looks at the extension. This is fine for FTP, FILE, TAR and
189  * friends, but is not for HTTP ( cgi scripts! ). You should use
190  * KRun instead, but this function returns immediately while
191  * KRun is async. If no extension matches, then
192  * the file contents will be examined if the URL is a local file, or
193  * "application/octet-stream" is returned otherwise.
194  *
195  * Equivalent to
196  * \code
197  * KUrl u(path);
198  * return findByUrl( u, mode, true, fast_mode );
199  * \endcode
200  *
201  * @param path the path to the file (a file name is enough, in fast mode)
202  * @param mode the mode of the file (used, for example, to identify
203  * executables)
204  * @param fast_mode If set to true no disk access is allowed to
205  * find out the mimetype. The result may be suboptimal, but
206  * it is @em fast.
207  * @param accuracy If not a null pointer, *accuracy is set to the
208  * accuracy of the match (which is in the range 0..100)
209  * @return A pointer to the matching mimetype. 0 is never returned.
210  */
211  static Ptr findByPath(const QString &path, mode_t mode = 0,
212  bool fast_mode = false, int *accuracy = nullptr);
213 
214  /**
215  * Tries to find out the MIME type of a data chunk by looking for
216  * certain magic numbers and characteristic strings in it.
217  *
218  * @param data the data to examine
219  * @param accuracy If not a null pointer, *accuracy is set to the
220  * accuracy of the match (which is in the range 0..100)
221  * @return a pointer to the KMimeType. "application/octet-stream" is
222  * returned if the type can not be found this way.
223  */
224  static Ptr findByContent(const QByteArray &data, int *accuracy = nullptr);
225 
226  /**
227  * Tries to find out the MIME type of filename/url and a data chunk.
228  * Whether to trust the extension or the data depends on the results of both approaches,
229  * and is determined automatically.
230  *
231  * This method is useful for instance in the get() method of kioslaves, and anywhere else
232  * where a filename is associated with some data which is available immediately.
233  *
234  * @param name the filename or url representing this data.
235  * Only used for the extension, not used as a local filename.
236  * @param data the data to examine when the extension isn't conclusive in itself
237  * @param mode the mode of the file (used, for example, to identify executables)
238  * @param accuracy If not a null pointer, *accuracy is set to the
239  * accuracy of the match (which is in the range 0..100)
240  */
241  static Ptr findByNameAndContent(const QString &name, const QByteArray &data,
242  mode_t mode = 0, int *accuracy = nullptr);
243 
244  /**
245  * Tries to find out the MIME type of a data chunk by looking for
246  * certain magic numbers and characteristic strings in it.
247  *
248  * @param device the IO device providing the data to examine
249  * @param accuracy If not a null pointer, *accuracy is set to the
250  * accuracy of the match (which is in the range 0..100)
251  * @return a pointer to the KMimeType. "application/octet-stream" is
252  * returned if the type can not be found this way.
253  * @since 4.4
254  */
255  static Ptr findByContent(QIODevice *device, int *accuracy = nullptr);
256 
257  /**
258  * Tries to find out the MIME type of filename/url and a data chunk.
259  * Whether to trust the extension or the data depends on the results of both approaches,
260  * and is determined automatically.
261  *
262  * This method is useful for instance in the get() method of kioslaves, and anywhere else
263  * where a filename is associated with some data which is available immediately.
264  *
265  * @param name the filename or url representing this data.
266  * Only used for the extension, not used as a local filename.
267  * @param device the IO device providing the data to examine when the extension isn't conclusive in itself
268  * @param mode the mode of the file (used, for example, to identify executables)
269  * @param accuracy If not a null pointer, *accuracy is set to the
270  * accuracy of the match (which is in the range 0..100)
271  * @return a pointer to the KMimeType. "application/octet-stream" is
272  * returned if the type can not be found this way.
273  * @since 4.4
274  */
275  static Ptr findByNameAndContent(const QString &name, QIODevice *device,
276  mode_t mode = 0, int *accuracy = nullptr);
277 
278  /**
279  * Tries to find out the MIME type of a file by looking for
280  * certain magic numbers and characteristic strings in it.
281  * This function is similar to the previous one. Note that the
282  * file name is not used for determining the file type, it is just
283  * used for loading the file's contents.
284  *
285  * @param fileName the path to the file
286  * @param accuracy If not a null pointer, *accuracy is set to the
287  * accuracy of the match (which is in the range 0..100)
288  * @return a pointer to the KMimeType, or the default mimetype
289  * (application/octet-stream) if the file cannot be opened.
290  */
291  static Ptr findByFileContent(const QString &fileName, int *accuracy = nullptr);
292 
293  /**
294  * Returns whether a file has an internal format that is not human readable.
295  * This is much more generic than "not mime->is(text/plain)".
296  * Many application file formats (like rtf and postscript) are based on text,
297  * but text that the user should rarely ever see.
298  */
299  static bool isBinaryData(const QString &fileName);
300 
301  /**
302  * Returns whether a buffer has an internal format that is not human readable.
303  * This is much more generic than "not mime->is(text/plain)".
304  * Many application file formats (like rtf and postscript) are based on text,
305  * but text that the user should rarely ever see.
306  */
307  static bool isBufferBinaryData(const QByteArray &data);
308 
309  /**
310  * Get all the mimetypes.
311  *
312  * Useful for showing the list of
313  * available mimetypes.
314  * More memory consuming than the ones above, don't use unless
315  * really necessary.
316  * @return the list of all existing KMimeTypes
317  */
318  static List allMimeTypes();
319 
320  /**
321  * Returns the name of the default mimetype.
322  * Always application/octet-stream, but this method exists
323  * for performance purposes.
324  * @return the name of the default mime type, always
325  * "application/octet-stream"
326  */
327  static QString defaultMimeType();
328 
329  /**
330  * Returns the default mimetype.
331  * Always application/octet-stream.
332  * This can be used to check the result of mimeType(name).
333  * @return the "application/octet-stream" mimetype pointer.
334  */
335  static KMimeType::Ptr defaultMimeTypePtr();
336 
337  /// Return true if this mimetype is the default mimetype
338  bool isDefault() const;
339 
340  /**
341  * If this mimetype is a subclass of another mimetype,
342  * return the name of the parent.
343  *
344  * @return the parent mime type, or QString() if not set
345  *
346  * @deprecated this method does not support multiple inheritance,
347  * which is actually part of the shared-mime-info standard.
348  * Use is(), parentMimeTypes(), or allParentMimeTypes() instead of parentMimeType()
349  */
350 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
351  KDELIBS4SUPPORT_DEPRECATED QString parentMimeType() const;
352 #endif
353 
354  /**
355  * If this mimetype is a subclass of one or more other mimetypes,
356  * return the list of those mimetypes.
357  *
358  * For instance a application/javascript is a special kind of text/plain,
359  * so the definition of application/javascript says
360  * sub-class-of type="text/plain"
361  *
362  * Another example: application/x-shellscript is a subclass of two other mimetypes,
363  * application/x-executable and text/plain.
364  *
365  * (Note that this notion doesn't map to the servicetype inheritance mechanism,
366  * since an application that handles the specific type doesn't necessarily handle
367  * the base type. The opposite is true though.)
368  *
369  * @return the list of parent mimetypes
370  * @since 4.1
371  */
372  QStringList parentMimeTypes() const;
373 
374  /**
375  * Return all parent mimetypes of this mimetype, direct or indirect.
376  * This includes the parent(s) of its parent(s), etc.
377  * If this mimetype is an alias, the list also contains the canonical
378  * name for this mimetype.
379  *
380  * The usual reason to use this method is to look for a setting which
381  * is stored per mimetype (like PreviewJob does).
382  * @since 4.1
383  */
384  QStringList allParentMimeTypes() const;
385 
386  /**
387  * Do not use name()=="somename" anymore, to check for a given mimetype.
388  * For mimetype inheritance to work, use is("somename") instead.
389  * is() also supports mimetype aliases.
390  * @deprecated since KF5, use QMimeType::inherits
391  */
392  bool is(const QString &mimeTypeName) const;
393 
394  /**
395  * Returns the user-specified icon for this mimetype. This is empty most of the time,
396  * you probably want to use iconName() instead. This method is for the mimetype editor.
397  * @since 4.3
398  */
399  QString userSpecifiedIconName() const;
400 
401  /**
402  * Return the primary extension associated with this mimetype, if any.
403  * If patterns() returns (*.jpg, *.jpeg) then mainExtension will return ".jpg".
404  * Note that the dot is included.
405  *
406  * If none of the patterns is in *.foo format (for instance
407  * <code>*.jp? or *.* or callgrind.out* </code>)
408  * then mainExtension() returns an empty string.
409  *
410  * @since 4.3
411  * @deprecated use QMimeType::suffixes(), but note that it doesn't return the leading dot.
412  */
413  QString mainExtension() const;
414 
415  /**
416  * Determines the extension from a filename (or full path) using the mimetype database.
417  * This allows to extract "tar.bz2" for foo.tar.bz2
418  * but still return "txt" for my.doc.with.dots.txt
419  *
420  * @deprecated use QMimeDatabase::suffixForFileName
421  */
422  static QString extractKnownExtension(const QString &fileName);
423 
424  /**
425  * Returns true if the given filename matches the given pattern.
426  * @since 4.6.1
427  * @deprecated use QRegExp:
428  * @code
429  * QRegExp rx(pattern);
430  * rx.setPatternSyntax(QRegExp::Wildcard);
431  * return rx.exactMatch(filename);
432  * @endcode
433  */
434  static bool matchFileName(const QString &filename, const QString &pattern);
435 
436  /**
437  * Returns the version of the installed update-mime-database program
438  * (from freedesktop.org shared-mime-info). This is used by unit tests
439  * and by the code that writes out icon definitions.
440  * @since 4.3
441  * @return -1 on error, otherwise a version number to use like this:
442  * @code
443  * if (version >= KDE_MAKE_VERSION(0, 40, 0)) { ... }
444  * @endcode
445  */
446  static int sharedMimeInfoVersion();
447 
448 private:
449  // Forbidden nowadays in KMimeType
450  int offset() const;
451  void save(QDataStream &s);
452 
453  void loadInternal(QDataStream &_str);
454  static void buildDefaultType();
455  static KMimeType::Ptr findByUrlHelper(const QUrl &url, mode_t mode,
456  bool is_local_file, QIODevice *device, int *accuracy);
457 
458  KMimeTypePrivate *d_ptr;
459 };
460 
461 #endif
Represent a mime type, like "text/plain", and the data that is associated with it.
Definition: kmimetype.h:50
const QLatin1String name
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 23:00:13 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.