kservice.h

Go to the documentation of this file.

/* This file is part of the KDE project
   Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
   Copyright     1999-2006  David Faure <faure@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef KSERVICE_H
#define KSERVICE_H

#include "kserviceaction.h"
#include <QtCore/QStringList>
#include <QtCore/QVariant>
#ifndef KDE_NO_DEPRECATED
#include <klibloader.h>
#endif
#include <kpluginfactory.h>
#include <kpluginloader.h>
#include <ksycocaentry.h>
#include <klocale.h>

class KServiceType;
class QDataStream;
class KDesktopFile;
class QWidget;

class KServicePrivate;

class KDECORE_EXPORT KService : public KSycocaEntry // TODO KDE5: inherit kshared, but move KSycocaEntry to Private
{
public:
    typedef KSharedPtr<KService> Ptr;
    typedef QList<Ptr> List;

    KService(const QString & name, const QString &exec, const QString &icon);

    explicit KService( const QString & fullpath );

    explicit KService( const KDesktopFile *config );

    KService( QDataStream& str, int offset );

    virtual ~KService();

    // TODO KDE5: add mimeTypes() accessor

    bool isApplication() const;

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED QString type() const;
#endif

    QString exec() const;
    QString library() const;

    QString icon() const;
    bool terminal() const;

    QString terminalOptions() const;
    bool substituteUid() const;
    QString username() const;

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED QString desktopEntryPath() const;
#endif

    QString desktopEntryName() const;

    QString menuId() const;

    QString storageId() const;

    enum DBusStartupType { DBusNone = 0, DBusUnique, DBusMulti, DBusWait };

    DBusStartupType dbusStartupType() const;

    QString path() const;

    QString comment() const;

    QString genericName() const;

    QString untranslatedGenericName() const;

    QStringList keywords() const;

    QStringList categories() const;

    QStringList serviceTypes() const;

    bool hasServiceType( const QString& serviceTypePtr ) const;

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED bool hasMimeType( const KServiceType* mimeTypePtr ) const;
#endif

    bool hasMimeType( const QString& mimeType ) const;

    bool allowAsDefault() const;

    QList<KServiceAction> actions() const;

    bool allowMultipleFiles() const;

    int initialPreference() const;

    bool noDisplay() const;

    bool showInKDE() const;

    QString parentApp() const;

    QString pluginKeyword() const;

    QString docPath() const;

    QVariant property( const QString& _name, QVariant::Type t ) const;

    using KSycocaEntry::property;

    QString locateLocal() const;

    void setMenuId(const QString &menuId);
    void setTerminal(bool b);
    void setTerminalOptions(const QString &options);

#ifndef KDE_NO_DEPRECATED
    static Ptr serviceByName( const QString& _name ); // KDE5: remove
#endif

    static Ptr serviceByDesktopPath( const QString& _path );

    static Ptr serviceByDesktopName( const QString& _name );

    static Ptr serviceByMenuId( const QString& _menuId );

    static Ptr serviceByStorageId( const QString& _storageId );

    static List allServices();

    static QString newServicePath(bool showInMenu, const QString &suggestedName,
                                  QString *menuId = 0,
                                  const QStringList *reservedMenuIds = 0);

    template <class T>
    T *createInstance(QObject *parent = 0,
            const QVariantList &args = QVariantList(), QString *error = 0) const
    {
        return createInstance<T>(0, parent, args, error);
    }

    template <class T>
    T *createInstance(QWidget *parentWidget, QObject *parent,
            const QVariantList &args = QVariantList(), QString *error = 0) const
    {
        KPluginLoader pluginLoader(*this);
        KPluginFactory *factory = pluginLoader.factory();
        if (factory) {
            T *o = factory->template create<T>(parentWidget, parent, pluginKeyword(), args);
            if (!o && error)
                *error = i18n("The service '%1' does not provide an interface '%2' with keyword '%3'",
                              name(), QString::fromLatin1(T::staticMetaObject.className()), pluginKeyword());
            return o;
        }
        else if (error) {
            *error = pluginLoader.errorString();
            pluginLoader.unload();
        }
        return 0;
    }

#ifndef KDE_NO_DEPRECATED
    template <class T>
    static KDE_DEPRECATED T *createInstance(const KService::Ptr &service, QObject *parent = 0,
            const QVariantList &args = QVariantList(), QString *error = 0)
    {
        return service->createInstance<T>(parent, args, error);
    }
#endif

#ifndef KDE_NO_DEPRECATED
    template <class T>
    static KDE_DEPRECATED T *createInstance( const KService::Ptr &service,
                              QObject *parent,
                              const QStringList &args,
                              int *error = 0 )
    {
        const QString library = service->library();
        if ( library.isEmpty() ) {
            if ( error )
                *error = KLibLoader::ErrServiceProvidesNoLibrary;
            return 0;
        }

        return KLibLoader::createInstance<T>( library, parent, args, error );
    }
#endif

#ifndef KDE_NO_DEPRECATED
    template <class T, class ServiceIterator>
    static KDE_DEPRECATED T *createInstance(ServiceIterator begin, ServiceIterator end, QObject *parent = 0,
            const QVariantList &args = QVariantList(), QString *error = 0)
    {
        for (; begin != end; ++begin) {
            KService::Ptr service = *begin;
            if (error) {
                error->clear();
            }

            T *component = createInstance<T>(service, parent, args, error);
            if (component) {
                return component;
            }
        }
        if (error) {
            *error = KLibLoader::errorString(KLibLoader::ErrNoServiceFound);
        }
        return 0;
    }
#endif

#ifndef KDE_NO_DEPRECATED
    template <class T, class ServiceIterator>
    static KDE_DEPRECATED T *createInstance( ServiceIterator begin, ServiceIterator end,
                              QObject *parent,
                              const QStringList &args,
                              int *error = 0 )
    {
        for (; begin != end; ++begin ) {
            KService::Ptr service = *begin;
            if ( error )
                *error = 0;

            T *component = createInstance<T>( service, parent, args, error );
            if ( component )
                return component;
        }
        if ( error )
            *error = KLibLoader::ErrNoServiceFound;
        return 0;
    }
#endif

protected:
    friend class KMimeAssociations;
    friend class KBuildServiceFactory;

    struct ServiceTypeAndPreference
    {
        ServiceTypeAndPreference()
            : preference(-1), serviceType() {}
        ServiceTypeAndPreference(int pref, const QString& servType)
            : preference(pref), serviceType(servType) {}
        int preference;
        QString serviceType; // or mimetype
    };
    QVector<ServiceTypeAndPreference>& _k_accessServiceTypes();

    friend QDataStream& operator>>( QDataStream&, ServiceTypeAndPreference& );
    friend QDataStream& operator<<( QDataStream&, const ServiceTypeAndPreference& );
private:
    Q_DECLARE_PRIVATE(KService)
};
#endif