File indexing completed on 2024-03-24 15:27:25

0001 /*  This file is part of the KDE libraries
0002  *  Copyright (C) 1999 Waldo Bastian <bastian@kde.org>
0003  *                     David Faure   <faure@kde.org>
0004  *
0005  *  This library is free software; you can redistribute it and/or
0006  *  modify it under the terms of the GNU Library General Public
0007  *  License version 2 as published by the Free Software Foundation;
0008  *
0009  *  This library is distributed in the hope that it will be useful,
0010  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
0011  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012  *  Library General Public License for more details.
0013  *
0014  *  You should have received a copy of the GNU Library General Public License
0015  *  along with this library; see the file COPYING.LIB.  If not, write to
0016  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  *  Boston, MA 02110-1301, USA.
0018  **/
0019 
0020 #ifndef __kmimetype_h__
0021 #define __kmimetype_h__
0022 
0023 #include "kdelibs4support_export.h"
0024 
0025 #include <QStringList>
0026 #include <QList>
0027 
0028 #include <ksycocatype.h>
0029 #include <kservicetype.h>
0030 
0031 #include <sys/types.h>
0032 #include <sys/stat.h>
0033 
0034 class QMimeType;
0035 class QUrl;
0036 class KMimeTypePrivate;
0037 
0038 /**
0039  * Represent a mime type, like "text/plain", and the data that is associated
0040  * with it.
0041  *
0042  * The starting point you need is often the static methods.
0043  *
0044  * KMimeType inherits KServiceType because "text/plain" can be used to find
0045  * services (apps and components) "which can open text/plain".
0046  *
0047  * @see KServiceType
0048  * @deprecated use QMimeType, see https://community.kde.org/Frameworks/Porting_Notes#Mime_Types
0049  */
0050 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KMimeType : public QSharedData
0051 {
0052     Q_DECLARE_PRIVATE(KMimeType)
0053 public:
0054     struct Ptr : QExplicitlySharedDataPointer<KMimeType> {
0055         Ptr(KMimeType *ptr = nullptr) : QExplicitlySharedDataPointer<KMimeType>(ptr) {}
0056         bool isNull() const
0057         {
0058             return !constData();
0059         }
0060     };
0061     typedef QList<Ptr> List;
0062 
0063     /**
0064      * Construct a KMimeType from a QMimeType.
0065      * This is mostly useful as a temporary measure during porting.
0066      */
0067     KMimeType(const QMimeType &mime);
0068 
0069     virtual ~KMimeType();
0070 
0071     /**
0072      * @return the name of this entry
0073      */
0074     QString name() const;
0075 
0076     /**
0077      * Return the filename of the icon associated with the mimetype.
0078      * Use KIconLoader::loadMimeTypeIcon to load the icon.
0079      *
0080      * @return The name of the icon associated with this MIME type.
0081      */
0082     QString iconName() const;
0083 
0084     /**
0085      * Return the "favicon" (see http://www.favicon.com) for the given @p url,
0086      * if available. Does NOT attempt to download the favicon, it only returns
0087      * one that is already available.
0088      *
0089      * If unavailable, returns QString().
0090      * @param url the URL of the favicon
0091      * @return the name of the favicon, or QString()
0092      * @deprecated use KIO::favIconForUrl
0093      */
0094     static QString favIconForUrl(const QUrl &url);
0095 
0096     /**
0097      * Return the filename of the icon associated with the mimetype, for a given url.
0098      * Use KIconLoader::loadMimeTypeIcon to load the icon.
0099      * @param url URL for the file
0100      * @param mode the mode of the file. The mode may modify the icon
0101      *              with overlays that show special properties of the
0102      *              icon. Use 0 for default
0103      * @return the name of the icon. The name of a default icon if there is no icon
0104      *         for the mime type
0105      * @deprecated use KIO::iconNameForUrl
0106      */
0107     static QString iconNameForUrl(const QUrl &url, mode_t mode = 0);
0108 
0109     /**
0110      * Returns the descriptive comment associated with the MIME type.
0111      *
0112      * @return The descriptive comment associated with the MIME type, if any.
0113      */
0114     QString comment() const;
0115 
0116     /**
0117      * Retrieve the list of patterns associated with the MIME Type.
0118      * @return a list of file globs that describe the file names
0119      *         (or, usually, the extensions) of files with this mime type
0120      */
0121     QStringList patterns() const;
0122 
0123     // DontResolveAlias was removed for kde 5, there was no use case for it.
0124     enum FindByNameOption { ResolveAliases = 1 };
0125 
0126     /**
0127      * Retrieve a pointer to the mime type @p name
0128      *
0129      * @em Very @em important: Don't store the result in a KMimeType* !
0130      *
0131      * Also note that you get a new KMimeType pointer every time you call this.
0132      * Don't ever write code that compares mimetype pointers, compare names instead.
0133      *
0134      * @param name the name of the mime type
0135      * @param options controls how the mime type is searched for
0136      * @return the pointer to the KMimeType with the given @p name, or
0137      *         0 if not found
0138      * @see KServiceType::serviceType
0139      */
0140     static Ptr mimeType(const QString &name, FindByNameOption options = ResolveAliases);
0141 
0142     /**
0143      * Finds a KMimeType with the given @p url.
0144      * This function looks at mode_t first.
0145      * If that does not help it looks at the extension (and the contents, for local files).
0146      * This method is fine for many protocols like ftp, file, fish, zip etc.,
0147      * but is not for http (e.g. cgi scripts
0148      * make extension-based checking unreliable).
0149      * For HTTP you should use KRun instead (to open the URL, in an app
0150      * or internally), or a KIO::mimetype() job (to find the mimetype without
0151      * downloading), or a KIO::get() job (to find the mimetype and then download).
0152      * In fact KRun is the most complete solution, but deriving from it just
0153      * for this is a bit cumbersome.
0154      *
0155      * If no extension matches, then the file contents will be examined if the URL is a local file, or
0156      * "application/octet-stream" is returned otherwise.
0157      *
0158      * @param url Is the right most URL with a filesystem protocol. It
0159      *        is up to you to find out about that if you have a nested
0160      *        URL.  For example
0161      *        "http://localhost/mist.gz#gzip:/decompress" would have to
0162      *        pass the "http://..." URL part, while
0163      *        "file:/tmp/x.tar#tar:/src/test.gz#gzip:/decompress" would
0164      *        have to pass the "tar:/..." part of the URL, since gzip is
0165      *        a filter protocol and not a filesystem protocol.
0166      * @param mode the mode of the file (used, for example, to identify
0167      *              executables)
0168      * @param is_local_file true if the file is local; false if not, or if you don't know.
0169      * @param fast_mode If set to true no disk access is allowed to
0170      *        find out the mimetype. The result may be suboptimal, but
0171      *        it is @em fast.
0172      * @param accuracy if set, the accuracy of the result, between 0 and 100.
0173      *        For instance, when the extension was used to determine the mimetype,
0174      *        the accuracy is set to 80, as per the shared-mime spec.
0175      *        Some 'magic' rules (used when !fast_mode) have an accuracy > 80
0176      *        (and have priority over the filename, others are < 80).
0177      *
0178      * @return A pointer to the matching mimetype. 0 is never returned.
0179      * @em Very @em Important: Don't store the result in a KMimeType* !
0180      */
0181     static Ptr findByUrl(const QUrl &url, mode_t mode = 0,
0182                          bool is_local_file = false, bool fast_mode = false,
0183                          int *accuracy = nullptr);
0184     /**
0185      * Finds a KMimeType with the given @p url.
0186      * This function looks at mode_t first.
0187      * If that does not help it
0188      * looks at the extension.  This is fine for FTP, FILE, TAR and
0189      * friends, but is not for HTTP ( cgi scripts! ). You should use
0190      * KRun instead, but this function returns immediately while
0191      * KRun is async. If no extension matches, then
0192      * the file contents will be examined if the URL is a local file, or
0193      * "application/octet-stream" is returned otherwise.
0194      *
0195      * Equivalent to
0196      * \code
0197      * KUrl u(path);
0198      * return findByUrl( u, mode, true, fast_mode );
0199      * \endcode
0200      *
0201      * @param path the path to the file (a file name is enough, in fast mode)
0202      * @param mode the mode of the file (used, for example, to identify
0203      *              executables)
0204      * @param fast_mode If set to true no disk access is allowed to
0205      *        find out the mimetype. The result may be suboptimal, but
0206      *        it is @em fast.
0207      * @param accuracy If not a null pointer, *accuracy is set to the
0208      *          accuracy of the match (which is in the range 0..100)
0209      * @return A pointer to the matching mimetype. 0 is never returned.
0210      */
0211     static Ptr findByPath(const QString &path, mode_t mode = 0,
0212                           bool fast_mode = false, int *accuracy = nullptr);
0213 
0214     /**
0215      * Tries to find out the MIME type of a data chunk by looking for
0216      * certain magic numbers and characteristic strings in it.
0217      *
0218      * @param data the data to examine
0219      * @param accuracy If not a null pointer, *accuracy is set to the
0220      *          accuracy of the match (which is in the range 0..100)
0221      * @return a pointer to the KMimeType. "application/octet-stream" is
0222      *          returned if the type can not be found this way.
0223      */
0224     static Ptr findByContent(const QByteArray &data, int *accuracy = nullptr);
0225 
0226     /**
0227      * Tries to find out the MIME type of filename/url and a data chunk.
0228      * Whether to trust the extension or the data depends on the results of both approaches,
0229      * and is determined automatically.
0230      *
0231      * This method is useful for instance in the get() method of kioslaves, and anywhere else
0232      * where a filename is associated with some data which is available immediately.
0233      *
0234      * @param name the filename or url representing this data.
0235      * Only used for the extension, not used as a local filename.
0236      * @param data the data to examine when the extension isn't conclusive in itself
0237      * @param mode the mode of the file (used, for example, to identify executables)
0238      * @param accuracy If not a null pointer, *accuracy is set to the
0239      *          accuracy of the match (which is in the range 0..100)
0240      */
0241     static Ptr findByNameAndContent(const QString &name, const QByteArray &data,
0242                                     mode_t mode = 0, int *accuracy = nullptr);
0243 
0244     /**
0245      * Tries to find out the MIME type of a data chunk by looking for
0246      * certain magic numbers and characteristic strings in it.
0247      *
0248      * @param device the IO device providing the data to examine
0249      * @param accuracy If not a null pointer, *accuracy is set to the
0250      *          accuracy of the match (which is in the range 0..100)
0251      * @return a pointer to the KMimeType. "application/octet-stream" is
0252      *          returned if the type can not be found this way.
0253      * @since 4.4
0254      */
0255     static Ptr findByContent(QIODevice *device, int *accuracy = nullptr);
0256 
0257     /**
0258      * Tries to find out the MIME type of filename/url and a data chunk.
0259      * Whether to trust the extension or the data depends on the results of both approaches,
0260      * and is determined automatically.
0261      *
0262      * This method is useful for instance in the get() method of kioslaves, and anywhere else
0263      * where a filename is associated with some data which is available immediately.
0264      *
0265      * @param name the filename or url representing this data.
0266      * Only used for the extension, not used as a local filename.
0267      * @param device the IO device providing the data to examine when the extension isn't conclusive in itself
0268      * @param mode the mode of the file (used, for example, to identify executables)
0269      * @param accuracy If not a null pointer, *accuracy is set to the
0270      *          accuracy of the match (which is in the range 0..100)
0271      * @return a pointer to the KMimeType. "application/octet-stream" is
0272      *          returned if the type can not be found this way.
0273      * @since 4.4
0274      */
0275     static Ptr findByNameAndContent(const QString &name, QIODevice *device,
0276                                     mode_t mode = 0, int *accuracy = nullptr);
0277 
0278     /**
0279      * Tries to find out the MIME type of a file by looking for
0280      * certain magic numbers and characteristic strings in it.
0281      * This function is similar to the previous one. Note that the
0282      * file name is not used for determining the file type, it is just
0283      * used for loading the file's contents.
0284      *
0285      * @param fileName the path to the file
0286      * @param accuracy If not a null pointer, *accuracy is set to the
0287      *          accuracy of the match (which is in the range 0..100)
0288      * @return a pointer to the KMimeType, or the default mimetype
0289      *         (application/octet-stream) if the file cannot be opened.
0290      */
0291     static Ptr findByFileContent(const QString &fileName, int *accuracy = nullptr);
0292 
0293     /**
0294      * Returns whether a file has an internal format that is not human readable.
0295      * This is much more generic than "not mime->is(text/plain)".
0296      * Many application file formats (like rtf and postscript) are based on text,
0297      * but text that the user should rarely ever see.
0298      */
0299     static bool isBinaryData(const QString &fileName);
0300 
0301     /**
0302      * Returns whether a buffer has an internal format that is not human readable.
0303      * This is much more generic than "not mime->is(text/plain)".
0304      * Many application file formats (like rtf and postscript) are based on text,
0305      * but text that the user should rarely ever see.
0306      */
0307     static bool isBufferBinaryData(const QByteArray &data);
0308 
0309     /**
0310      * Get all the mimetypes.
0311      *
0312      * Useful for showing the list of
0313      * available mimetypes.
0314      * More memory consuming than the ones above, don't use unless
0315      * really necessary.
0316      * @return the list of all existing KMimeTypes
0317      */
0318     static List allMimeTypes();
0319 
0320     /**
0321      * Returns the name of the default mimetype.
0322      * Always application/octet-stream, but this method exists
0323      * for performance purposes.
0324      * @return the name of the default mime type, always
0325      *         "application/octet-stream"
0326      */
0327     static QString defaultMimeType();
0328 
0329     /**
0330      * Returns the default mimetype.
0331      * Always application/octet-stream.
0332      * This can be used to check the result of mimeType(name).
0333      * @return the "application/octet-stream" mimetype pointer.
0334      */
0335     static KMimeType::Ptr defaultMimeTypePtr();
0336 
0337     /// Return true if this mimetype is the default mimetype
0338     bool isDefault() const;
0339 
0340     /**
0341      * If this mimetype is a subclass of another mimetype,
0342      * return the name of the parent.
0343      *
0344      * @return the parent mime type, or QString() if not set
0345      *
0346      * @deprecated this method does not support multiple inheritance,
0347      * which is actually part of the shared-mime-info standard.
0348      * Use is(), parentMimeTypes(), or allParentMimeTypes() instead of parentMimeType()
0349      */
0350 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
0351     KDELIBS4SUPPORT_DEPRECATED QString parentMimeType() const;
0352 #endif
0353 
0354     /**
0355      * If this mimetype is a subclass of one or more other mimetypes,
0356      * return the list of those mimetypes.
0357      *
0358      * For instance a application/javascript is a special kind of text/plain,
0359      * so the definition of application/javascript says
0360      *      sub-class-of type="text/plain"
0361      *
0362      * Another example: application/x-shellscript is a subclass of two other mimetypes,
0363      * application/x-executable and text/plain.
0364      *
0365      * (Note that this notion doesn't map to the servicetype inheritance mechanism,
0366      * since an application that handles the specific type doesn't necessarily handle
0367      * the base type. The opposite is true though.)
0368      *
0369      * @return the list of parent mimetypes
0370      * @since 4.1
0371      */
0372     QStringList parentMimeTypes() const;
0373 
0374     /**
0375      * Return all parent mimetypes of this mimetype, direct or indirect.
0376      * This includes the parent(s) of its parent(s), etc.
0377      * If this mimetype is an alias, the list also contains the canonical
0378      * name for this mimetype.
0379      *
0380      * The usual reason to use this method is to look for a setting which
0381      * is stored per mimetype (like PreviewJob does).
0382      * @since 4.1
0383      */
0384     QStringList allParentMimeTypes() const;
0385 
0386     /**
0387      * Do not use name()=="somename" anymore, to check for a given mimetype.
0388      * For mimetype inheritance to work, use is("somename") instead.
0389      * is() also supports mimetype aliases.
0390      * @deprecated since KF5, use QMimeType::inherits
0391      */
0392     bool is(const QString &mimeTypeName) const;
0393 
0394     /**
0395      * Returns the user-specified icon for this mimetype. This is empty most of the time,
0396      * you probably want to use iconName() instead. This method is for the mimetype editor.
0397      * @since 4.3
0398      */
0399     QString userSpecifiedIconName() const;
0400 
0401     /**
0402      * Return the primary extension associated with this mimetype, if any.
0403      * If patterns() returns (*.jpg, *.jpeg) then mainExtension will return ".jpg".
0404      * Note that the dot is included.
0405      *
0406      * If none of the patterns is in *.foo format (for instance
0407      *   <code>*.jp? or *.* or callgrind.out* </code>)
0408      * then mainExtension() returns an empty string.
0409      *
0410      * @since 4.3
0411      * @deprecated use QMimeType::suffixes(), but note that it doesn't return the leading dot.
0412      */
0413     QString mainExtension() const;
0414 
0415     /**
0416      * Determines the extension from a filename (or full path) using the mimetype database.
0417      * This allows to extract "tar.bz2" for foo.tar.bz2
0418      * but still return "txt" for my.doc.with.dots.txt
0419      *
0420      * @deprecated use QMimeDatabase::suffixForFileName
0421      */
0422     static QString extractKnownExtension(const QString &fileName);
0423 
0424     /**
0425      * Returns true if the given filename matches the given pattern.
0426      * @since 4.6.1
0427      * @deprecated use QRegExp:
0428      * @code
0429      *  QRegExp rx(pattern);
0430      *  rx.setPatternSyntax(QRegExp::Wildcard);
0431      *  return rx.exactMatch(filename);
0432      * @endcode
0433      */
0434     static bool matchFileName(const QString &filename, const QString &pattern);
0435 
0436     /**
0437      * Returns the version of the installed update-mime-database program
0438      * (from freedesktop.org shared-mime-info). This is used by unit tests
0439      * and by the code that writes out icon definitions.
0440      * @since 4.3
0441      * @return -1 on error, otherwise a version number to use like this:
0442      * @code
0443      * if (version >= KDE_MAKE_VERSION(0, 40, 0)) { ... }
0444      * @endcode
0445      */
0446     static int sharedMimeInfoVersion();
0447 
0448 private:
0449     // Forbidden nowadays in KMimeType
0450     int offset() const;
0451     void save(QDataStream &s);
0452 
0453     void loadInternal(QDataStream &_str);
0454     static void buildDefaultType();
0455     static KMimeType::Ptr findByUrlHelper(const QUrl &url, mode_t mode,
0456                                           bool is_local_file, QIODevice *device, int *accuracy);
0457 
0458     KMimeTypePrivate *d_ptr;
0459 };
0460 
0461 #endif