kio Library API Documentation

kfilemetainfo.h

00001 /*
00002  *  This file is part of the KDE libraries
00003  *  Copyright (C) 2001-2002 Rolf Magnus <ramagnus@kde.org>
00004  *  Copyright (C) 2001-2002 Carsten Pfeiffer <pfeiffer@kde.org>
00005  *
00006  *  This library is free software; you can redistribute it and/or
00007  *  modify it under the terms of the GNU Library General Public
00008  *  License as published by the Free Software Foundation version 2.0.
00009  *
00010  *  This library is distributed in the hope that it will be useful,
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  *  Library General Public License for more details.
00014  *
00015  *  You should have received a copy of the GNU Library General Public License
00016  *  along with this library; see the file COPYING.LIB.  If not, write to
00017  *  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018  *  Boston, MA 02111-1307, USA.
00019  */
00020 #ifndef KILEMETAINFO_H
00021 #define KILEMETAINFO_H
00022 
00023 /* Hack for HPUX: Namespace pollution
00024    m_unit is a define in <sys/sysmacros.h> */
00025 #define m_unit outouftheway_m_unit
00026 
00027 #include <qdict.h>
00028 #include <qvariant.h>
00029 #include <qobject.h>
00030 #include <qstring.h>
00031 #include <kurl.h>
00032 
00033 #undef m_unit
00034 
00035 class QValidator;
00036 class KFilePlugin;
00037 class KFileMetaInfoGroup;
00038 
00048 class KIO_EXPORT KFileMimeTypeInfo
00049 {
00050     // the plugin needs to be a friend because it puts the data into the object,
00051     // and it should be the only one allowed to do this.
00052     friend class KFilePlugin;
00053     friend class KFileMetaInfoProvider;
00054 
00055 public:
00056     KFileMimeTypeInfo() {}
00057 
00062     enum Attributes
00063     {
00064         Addable     =  1, 
00065         Removable   =  2, 
00066         Modifiable  =  4, 
00067         Cumulative =  8,  
00070         Cummulative = Cumulative, 
00071         Averaged    = 16, 
00073         MultiLine   = 32, 
00077         SqueezeText = 64  
00081     };
00082 
00087     enum Hint {
00088         NoHint      = 0, 
00089         Name        = 1, 
00090         Author      = 2, 
00091         Description = 3, 
00092         Width       = 4, 
00093         Height      = 5, 
00094         Size        = 6, 
00095         Bitrate     = 7, 
00096         Length      = 8, 
00097         Hidden      = 9, 
00098         Thumbnail   = 10 
00099 
00100     };
00101 
00109     enum Unit {
00110         NoUnit          = 0,  
00111         Seconds         = 1,  
00112         MilliSeconds    = 2,  
00113         BitsPerSecond   = 3,  
00114         Pixels          = 4,  
00115         Inches          = 5,  
00116         Centimeters     = 6,  
00117         Bytes           = 7,  
00118         FramesPerSecond = 8,  
00119         DotsPerInch     = 9,  
00120         BitsPerPixel    = 10, 
00121         Hertz           = 11, 
00122         KiloBytes       = 12, 
00123         Millimeters     = 13  
00124     };
00125 
00126 
00127     class ItemInfo;
00128 
00135     class KIO_EXPORT GroupInfo
00136     {
00137 
00138     friend class KFilePlugin;
00139     friend class KFileMimeTypeInfo;
00140     public:
00151         QStringList supportedKeys() const
00152         {
00153             return m_supportedKeys;
00154         }
00155 
00162         const QString& name() const
00163         {
00164             return m_name;
00165         }
00166 
00174         const QString& translatedName() const
00175         {
00176             return m_translatedName;
00177         }
00178 
00186         const ItemInfo * itemInfo( const QString& key ) const;
00187 
00193         uint attributes() const
00194         {
00195             return m_attr;
00196         }
00197 
00202         bool supportsVariableKeys() const
00203         {
00204             return m_variableItemInfo;
00205         }
00206 
00214         const ItemInfo* variableItemInfo( ) const
00215         {
00216             return m_variableItemInfo;
00217         }
00218 
00219     private:
00221         GroupInfo( const QString& name, const QString& translatedName);
00222 
00224         KFileMimeTypeInfo::ItemInfo* addItemInfo( const QString& key,
00225                                                   const QString& translatedKey,
00226                                                   QVariant::Type type);
00227 
00229         void addVariableInfo( QVariant::Type type, uint attr );
00230 
00231         QString         m_name;
00232         QString         m_translatedName;
00233         QStringList     m_supportedKeys;
00234         uint            m_attr;
00235         ItemInfo*       m_variableItemInfo;
00236         QDict<ItemInfo> m_itemDict;
00237 
00238     };
00239 
00245     class KIO_EXPORT ItemInfo
00246     {
00247     friend class KFilePlugin;
00248     friend class GroupInfo;
00249     public:
00251         ItemInfo() {}     // ### should be private?
00252 
00260         const QString& prefix() const
00261         {
00262             return m_prefix;
00263         }
00264 
00271         const QString& suffix() const
00272         {
00273             return m_suffix;
00274         }
00275 
00282         QVariant::Type type() const
00283         {
00284             return m_type;
00285         }
00286 
00291         const QString& key() const
00292         {
00293             return m_key;
00294         }
00295 
00307         QString string( const QVariant& value, bool mangle = true ) const;
00308 
00314         bool isVariableItem() const
00315         {
00316             // every valid item is supposed to have a non-null key
00317             return key().isNull();
00318         }
00319 
00326         const QString& translatedKey() const
00327         {
00328             return m_translatedKey;
00329         }
00330 
00336         uint attributes() const
00337         {
00338             return m_attr;
00339         }
00340 
00346         uint hint() const
00347         {
00348             return m_hint;
00349         }
00350 
00356         uint unit() const
00357         {
00358             return m_unit;
00359         }
00360 
00361     private:
00363         ItemInfo(const QString& key, const QString& translatedKey,
00364                  QVariant::Type type)
00365             : m_key(key), m_translatedKey(translatedKey),
00366               m_type(type),
00367               m_attr(0), m_unit(NoUnit), m_hint(NoHint),
00368               m_prefix(QString::null), m_suffix(QString::null)
00369         {}
00370 
00371         QString           m_key;
00372         QString           m_translatedKey;
00373         QVariant::Type    m_type;
00374         uint              m_attr;
00375         uint              m_unit;
00376         uint              m_hint;
00377         QString           m_prefix;
00378         QString           m_suffix;
00379     };
00380 
00381     // ### could it be made private? Would this be BC?
00382     ~KFileMimeTypeInfo();
00383 
00394     QValidator * createValidator(const QString& group, const QString& key,
00395                                  QObject *parent = 0, const char *name = 0) const;
00396 
00403     QStringList supportedGroups() const;
00404 
00411     QStringList translatedGroups() const;
00412 
00419     QStringList preferredGroups() const
00420     {
00421         return m_preferredGroups;
00422     }
00423 
00428     QString mimeType()  const {return m_mimeType;}
00429 
00437     const GroupInfo * groupInfo( const QString& group ) const;
00438 
00439     // always returning stringlists which the user has to iterate and use them
00440     // to look up the real items sounds strange to me. I think we should add
00441     // our own iterators some time (somewhere in the future ;)
00442 
00449     QStringList supportedKeys() const;
00450 
00456     QStringList preferredKeys() const
00457     {
00458         return m_preferredKeys;
00459     }
00460 
00461     // ### shouldn't this be private? BC?
00462     GroupInfo * addGroupInfo( const QString& name,
00463                               const QString& translatedName);
00464 
00465     QString         m_translatedName;
00466     QStringList     m_supportedKeys;
00467     uint            m_attr;
00468     //        bool            m_supportsVariableKeys : 1;
00469     QDict<ItemInfo> m_itemDict;
00470 
00471 // ### this should be made private instead, but this would be BIC
00472 protected:
00474     KFileMimeTypeInfo( const QString& mimeType );
00475 
00476     QDict<GroupInfo> m_groups;
00477     QString     m_mimeType;
00478     QStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
00479     QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
00480 };
00481 
00482 
00488 class KIO_EXPORT KFileMetaInfoItem
00489 {
00490 public:
00491     class Data;
00492     typedef KFileMimeTypeInfo::Hint Hint;
00493     typedef KFileMimeTypeInfo::Unit Unit;
00494     typedef KFileMimeTypeInfo::Attributes Attributes;
00495 
00501     // ### hmm, then it should be private
00502     KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
00503                        const QString& key, const QVariant& value);
00504 
00508     KFileMetaInfoItem( const KFileMetaInfoItem & item );
00509 
00519     const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
00520 
00524     KFileMetaInfoItem();
00525 
00526     ~KFileMetaInfoItem();
00527 
00532     QString key() const;
00533 
00539     QString translatedKey() const;
00540 
00545     const QVariant& value() const;
00546 
00554     QString string( bool mangle = true ) const;
00555 
00561     bool setValue( const QVariant& value );
00562 
00567     QVariant::Type type() const;
00568 
00577     bool isEditable() const;
00578 
00587     bool isRemoved() const;
00588 
00597     bool isModified() const;
00598 
00605     QString prefix() const;
00606 
00613     QString suffix() const;
00614 
00619     uint hint() const;
00620 
00626     uint unit() const;
00627 
00633     uint attributes() const;
00634 
00642     bool isValid() const;
00643 
00644     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
00645     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00646     KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
00647     friend class KFileMetaInfoGroup;
00648 
00649 protected:
00650     void setAdded();
00651     void setRemoved();
00652 
00653     void ref();
00654     void deref();
00655 
00656     Data *d;
00657 };
00658 
00664 class KIO_EXPORT KFileMetaInfoGroup
00665 {
00666   friend class KFilePlugin;
00667   friend class KFileMetaInfo;
00668   KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00669   KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
00670 
00671 public:
00672     class Data;
00678     // ### hmm, then it should be private
00679     KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info );
00680 
00684     KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
00685 
00695     const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
00696 
00701      KFileMetaInfoGroup();
00702 
00703     ~KFileMetaInfoGroup();
00704 
00712     bool isValid() const;
00713 
00719     bool isEmpty() const;
00720 
00727     bool isModified() const;
00728 
00733     KFileMetaInfoItem operator[]( const QString& key ) const
00734     { return item( key ); }
00735 
00742     KFileMetaInfoItem item( const QString& key ) const;
00743 
00749     KFileMetaInfoItem item( uint hint ) const;
00750 
00757     const QVariant value( const QString& key ) const
00758     {
00759         const KFileMetaInfoItem &i = item( key );
00760         return i.value();
00761     }
00762 
00773     QStringList supportedKeys() const;
00774 
00780     bool supportsVariableKeys() const;
00781 
00786     bool contains( const QString& key ) const;
00787 
00792     QStringList keys() const;
00793 
00798     QStringList preferredKeys() const;
00799 
00806     // ### do we really want to support that?
00807     // let's not waste time on thinking about it. Let's just kick it for now
00808     // and add it in 4.0 if needed ;)
00809 //    const QMemArray<QVariant::Type>& types( const QString& key ) const;
00810 
00818     KFileMetaInfoItem addItem( const QString& key );
00819 
00828     bool removeItem(const QString& key);
00829 
00834     QStringList removedItems();
00835 
00840     QString name() const;
00841 
00847     QString translatedName() const;
00848 
00853     uint attributes() const;
00854 
00855 protected:
00856       void setAdded();
00857       KFileMetaInfoItem appendItem( const QString& key, const QVariant& value);
00858 
00859       Data* d;
00860       void ref();
00861       void deref();
00862 
00863 };
00864 
00865 
00868 
00869 
00887 class KIO_EXPORT KFileMetaInfo
00888 {
00889 public:
00890     typedef KFileMimeTypeInfo::Hint Hint;
00891     typedef KFileMimeTypeInfo::Unit Unit;
00892     typedef KFileMimeTypeInfo::Attributes Attributes;
00893     class Data;
00894 
00899     enum What
00900     {
00901       Fastest       = 0x1,  
00904       DontCare      = 0x2,  
00905 
00906       TechnicalInfo = 0x4,  
00909       ContentInfo   = 0x8,  
00911       ExtenedAttr   = 0x10, 
00913       Thumbnail     = 0x20, 
00915       Preferred     = 0x40,  
00916       Everything    = 0xffff 
00917 
00918     };
00919 
00940     KFileMetaInfo( const QString& path,
00941                    const QString& mimeType = QString::null,
00942                    uint what = Fastest);
00943 
00951     KFileMetaInfo( const KURL& url,
00952                    const QString& mimeType = QString::null,
00953                    uint what = Fastest);
00954 
00959     KFileMetaInfo();
00960 
00967     KFileMetaInfo( const KFileMetaInfo& original);
00968 
00969     ~KFileMetaInfo();
00970 
00981     const KFileMetaInfo& operator= (const KFileMetaInfo& info );
00982 
00983 
00988     QStringList groups() const;
00989 
00994     QStringList supportedGroups() const;
00995 
01000     QStringList preferredGroups() const;
01001 
01006     QStringList preferredKeys() const;
01007 
01012     QStringList supportedKeys() const;
01013 
01018     QStringList editableGroups() const;
01019 
01020     // I'd like to keep those for lookup without group, at least the hint
01021     // version
01027     KFileMetaInfoItem item(const QString& key) const;
01033     KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
01034 
01042     KFileMetaInfoItem saveItem( const QString& key,
01043                                 const QString& preferredGroup = QString::null,
01044                                 bool createGroup = true );
01045 
01051     KFileMetaInfoGroup group(const QString& key) const;
01052 
01058     KFileMetaInfoGroup operator[] (const QString& key) const
01059     {
01060         return group(key);
01061     }
01062 
01071     bool addGroup( const QString& name );
01072 
01081     bool removeGroup( const QString& name );
01082 
01087     QStringList removedGroups();
01088 
01095     bool applyChanges();
01096 
01102     bool contains( const QString& key ) const;
01103 
01109     bool containsGroup( const QString& key ) const;
01110 
01111     /*
01112      * Returns the value with the given @p key.
01113      * @param key the key to retrieve
01114      * @return the value. Invalid if it does not exist
01115      */
01116     const QVariant value( const QString& key ) const
01117     {
01118         return item(key).value();
01119     }
01120 
01121 
01127     bool isValid() const;
01128 
01134     bool isEmpty() const;
01135 
01140     QString mimeType() const;
01141 
01146     QString path() const;
01147 
01152     KURL url() const;
01153 
01154     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01155     KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01156     friend class KFilePlugin;
01157 
01158 protected:
01159     KFileMetaInfoGroup appendGroup(const QString& name);
01160 
01165     KFilePlugin * const plugin() const;
01166 
01167     void ref();
01168     void deref();
01169 
01170     Data* d;
01171 
01172 private:
01173     KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
01174                                         const QString& key );
01175 
01176     void init( const KURL& url,
01177                const QString& mimeType = QString::null,
01178                uint what = Fastest);
01179 };
01180 
01183 
01184 
01202 class KIO_EXPORT KFilePlugin : public QObject
01203 {
01204     Q_OBJECT
01205 
01206 public:
01213     KFilePlugin( QObject *parent, const char *name,
01214                  const QStringList& args );
01215 
01216     virtual ~KFilePlugin();
01217 
01226     virtual bool readInfo( KFileMetaInfo& info,
01227                            uint what = KFileMetaInfo::Fastest ) = 0;
01228 
01235     virtual bool writeInfo( const KFileMetaInfo& info ) const
01236     {
01237         Q_UNUSED(info);
01238         return true;
01239     }
01240 
01254     virtual QValidator* createValidator( const QString& mimeType,
01255                                          const QString& group,
01256                                          const QString& key,
01257                                          QObject* parent,
01258                                          const char* name) const
01259     {
01260         Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
01261         Q_UNUSED(parent);Q_UNUSED(name);
01262         return 0;
01263     }
01264 
01265 protected:
01266 
01267     KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
01268                       const QString& key, const QString& translatedKey) const;
01269     void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
01270     void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
01271                          uint attr) const;
01272     KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
01273                                              const QString& key,
01274                                              const QString& translatedKey,
01275                                              QVariant::Type type);
01276     void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
01277     void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
01278     void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
01279     void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
01280     void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
01281     KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
01282     void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
01283 
01287     // ### do we need this, if it only calls the provider?
01288     // IMHO the Plugin shouldn't call its provider.
01289     // DF: yes we need this. A plugin can create more than one mimetypeinfo.
01290     // What sucks though, is to let plugins do that in their ctor.
01291     // Would be much simpler to have a virtual init method for that,
01292     // so that the provider can set up stuff with the plugin pointer first!
01293     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01294 
01295     QStringList m_preferredKeys;
01296     QStringList m_preferredGroups;
01297 
01298 protected:
01299     virtual void virtual_hook( int id, void* data );
01300 private:
01301     class KFilePluginPrivate;
01302     KFilePluginPrivate *d;
01303 };
01304 
01307 
01308 
01315 class KIO_EXPORT KFileMetaInfoProvider: private QObject
01316 {
01317     friend class KFilePlugin;
01318 
01319   Q_OBJECT
01320 public:
01321     virtual ~KFileMetaInfoProvider();
01322 
01323     static KFileMetaInfoProvider * self();
01324 
01329     KFilePlugin * plugin( const QString& mimeType ); // KDE4: merge with method below
01330 
01336     KFilePlugin * plugin( const QString& mimeType, const QString& protocol );
01337 
01338     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType ); // KDE4: merge with below
01339     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType, const QString& protocol );
01340 
01341     QStringList preferredKeys( const QString& mimeType ) const;
01342     QStringList preferredGroups( const QString& mimeType ) const;
01343 
01345     QStringList supportedMimeTypes() const;
01346 
01347 protected: // ## should be private, right?
01348     KFileMetaInfoProvider();
01349 
01350 private:
01351 
01352     // Data structure:
01353     // Mimetype or Protocol -> { Plugin and MimeTypeInfo }
01354     // The {} struct is CachedPluginInfo
01355     struct CachedPluginInfo
01356     {
01357         CachedPluginInfo() : plugin( 0 ), mimeTypeInfo( 0 ), ownsPlugin( false ) {}
01358         CachedPluginInfo( KFilePlugin* p, KFileMimeTypeInfo* i, bool owns )
01359             : plugin( p ), mimeTypeInfo( i ), ownsPlugin( owns ) {}
01360         // auto-delete behavior
01361         ~CachedPluginInfo() {
01362             if ( ownsPlugin ) delete plugin;
01363             delete mimeTypeInfo;
01364         }
01365 
01366         // If plugin and mimeTypeInfo are 0, means that no plugin is available.
01367         KFilePlugin* plugin;
01368         KFileMimeTypeInfo* mimeTypeInfo;
01369         // The problem here is that plugin can be shared in multiple instances,
01370         // so the memory management isn't easy. KDE4 solution: use KSharedPtr?
01371         // For now we flag one copy of the KFilePlugin pointer as being "owned".
01372         bool ownsPlugin;
01373     };
01374 
01375     // The key is either a mimetype or a protocol. Those things don't look the same
01376     // so there's no need for two QDicts.
01377     QDict<CachedPluginInfo> m_plugins;
01378 
01379     // This data is aggregated during the creation of a plugin,
01380     // before being moved to the appropriate CachedPluginInfo(s)
01381     // At any other time than during the loading of a plugin, this dict is EMPTY.
01382     // Same key as in m_plugins: mimetype or protocol
01383     QDict<KFileMimeTypeInfo> m_pendingMimetypeInfos;
01384 
01385 private:
01386     static KFileMetaInfoProvider * s_self;
01387 
01388     KFilePlugin* loadPlugin( const QString& mimeType, const QString& protocol );
01389     KFilePlugin* loadAndRegisterPlugin( const QString& mimeType, const QString& protocol );
01390     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01391 
01392     class KFileMetaInfoProviderPrivate;
01393     KFileMetaInfoProviderPrivate *d;
01394 
01395 };
01396 
01397 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
01398 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
01399 
01400 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
01401 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
01402 
01403 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01404 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01405 
01406 
01407 #endif // KILEMETAINFO_H
KDE Logo
This file is part of the documentation for kio Library Version 3.4.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Tue Nov 1 10:33:16 2005 by doxygen 1.4.3 written by Dimitri van Heesch, © 1997-2003