digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
Digikam::ItemScanner Class Reference

Public Types

enum  ScanMode { NewScan , ModifiedScan , Rescan , CleanScan }
 

Public Member Functions

 ItemScanner (const QFileInfo &info)
 Construct an ItemScanner from an existing QFileInfo object.
 
 ItemScanner (const QFileInfo &info, const ItemScanInfo &Iteminfo)
 Construct an ItemScanner object from an existing QFileInfo and ItemScanInfo object.
 
 ItemScanner (qlonglong imageid)
 Construct an ItemScanner for an image in the database.
 
const ItemScanInfoitemScanInfo () const
 Provides access to the information retrieved by scanning.
 
void loadFromDisk ()
 Loads data from disk (metadata, image file properties).
 
void setCategory (DatabaseItem::Category category)
 Inform the scanner about the category of the file.
 

Static Public Member Functions

static QString formatToString (const QString &format)
 Helper method to translate enum values to user presentable strings.
 

Operations on History Metadata

bool hasHistoryToResolve () const
 Returns true if this file has been marked as needing history resolution at a later stage.
 
void scanBalooInfo ()
 scanBalooInfo - retrieve tags, comments and rating from Baloo Desktop service.
 
static bool resolveImageHistory (qlonglong id, QList< qlonglong > *needTaggingIds=nullptr)
 Resolves the image history of the image id by filling the ImageRelations table for all contained referred images.
 
static bool resolveImageHistory (qlonglong imageId, const QString &historyXml, QList< qlonglong > *needTaggingIds=nullptr)
 
static void tagItemHistoryGraph (qlonglong id)
 Takes the history graph reachable from the given image, and assigns versioning tags to all entries based on history image types and graph structure.
 
static DImageHistory resolvedImageHistory (const DImageHistory &history, bool mustBeAvailable=false)
 All referred images of the given history will be resolved.
 
static bool sameReferredImage (const HistoryImageId &id1, const HistoryImageId &id2)
 Determines if the two ids refer to the same image.
 
static QList< qlonglong > resolveHistoryImageId (const HistoryImageId &historyId)
 Returns all image ids fulfilling the given image id.
 
void scanImageHistory ()
 
void commitImageHistory ()
 
void scanImageHistoryIfModified ()
 
QString uniqueHash () const
 

Operations with Database

void newFile (int albumId)
 Call this when you want ItemScanner to add a new file to the database and read all information into the database.
 
void newFileFullScan (int albumId)
 Call this when you want ItemScanner to add a new file to the database and read all information into the database.
 
void rescan ()
 Call this to take an existing image in the database, but re-read all information from the file into the database, possibly overwriting information there.
 
void cleanScan ()
 This is the same as rescan() but the database metadata will be cleaned up if the corresponding metadata write option is enabled.
 
void commit ()
 Commits the scanned information to the database.
 
qlonglong id () const
 Returns the image id of the scanned file, if (yet) available.
 
void copiedFrom (int albumId, qlonglong srcId)
 Similar to newFile.
 
static void sortByProximity (QList< ItemInfo > &infos, const ItemInfo &subject)
 Sort a list of infos by proximity to the given subject.
 
bool copyFromSource (qlonglong src)
 
void commitCopyImageAttributes ()
 
void cleanDatabaseMetadata ()
 
void prepareAddImage (int albumId)
 
bool commitAddImage ()
 

Operations on File Metadata

void fileModified ()
 Call this when you have detected that a file in the database has been modified on disk.
 
static void fillCommonContainer (qlonglong imageid, ImageCommonContainer *const container)
 Returns File-metadata container with user-presentable information.
 
static QDateTime creationDateFromFilesystem (const QFileInfo &info)
 Returns a suitable creation date from file system information.
 
void prepareUpdateImage ()
 
void commitUpdateImage ()
 
bool scanFromIdenticalFile ()
 
void scanFile (ScanMode mode)
 
void scanItemInformation ()
 
void commitItemInformation ()
 

Operations on Photo Metadata

static QString iptcCorePropertyName (MetadataInfo::Field field)
 Helper method to return official property name by which IPTC core properties are stored in the database (ItemCopyright and ImageProperties table).
 
static MetadataFields allImageMetadataFields ()
 
QString detectImageFormat () const
 
void scanImageMetadata ()
 
void commitImageMetadata ()
 
void scanItemPosition ()
 
void commitItemPosition ()
 
void scanItemComments ()
 
void commitItemComments ()
 
void scanItemCopyright ()
 
void commitItemCopyright ()
 
void scanIPTCCore ()
 
void commitIPTCCore ()
 
void scanTags ()
 
void commitTags ()
 
void scanFaces ()
 
void commitFaces ()
 
bool checkRatingFromMetadata (const QVariant &ratingFromMetadata) const
 
void checkCreationDateFromMetadata (QVariant &dateFromMetadata) const
 

Operations on Video Metadata

static void fillVideoMetadataContainer (qlonglong imageid, VideoMetadataContainer *const container)
 Returns Video container with user-presentable information.
 
void scanVideoInformation ()
 
void scanVideoMetadata ()
 
void commitVideoMetadata ()
 
QString detectVideoFormat () const
 
QString detectAudioFormat () const
 
static MetadataFields allVideoMetadataFields ()
 

Constructor & Destructor Documentation

◆ ItemScanner() [1/3]

Digikam::ItemScanner::ItemScanner ( const QFileInfo &  info,
const ItemScanInfo Iteminfo 
)

This constructor shall be used with fileModified() or fullScan().

◆ ItemScanner() [2/3]

Digikam::ItemScanner::ItemScanner ( const QFileInfo &  info)
explicit

Use this constructor if you intend to call newFile().

◆ ItemScanner() [3/3]

Digikam::ItemScanner::ItemScanner ( qlonglong  imageid)
explicit

File info, Scan info and the category will be retrieved from the database.

Member Function Documentation

◆ commit()

void Digikam::ItemScanner::commit ( )

You must call this after scanning was done for any changes to take effect. Only this method will perform write operations to the database.

◆ copiedFrom()

void Digikam::ItemScanner::copiedFrom ( int  albumId,
qlonglong  srcId 
)

Call this when you want ItemScanner to add a new file to the database which is a copy of another file, copying attributes from the src and rescanning other attributes as appropriate. Give the id of the album of the new file, and the id of the src file.

◆ creationDateFromFilesystem()

QDateTime Digikam::ItemScanner::creationDateFromFilesystem ( const QFileInfo &  info)
static

Use this as a fallback if metadata is not available.

◆ fileModified()

void Digikam::ItemScanner::fileModified ( )

Only two groups of fields will be updated in the database:

  • filesystem specific properties (those that signaled you that the file has been modified because their state on disk differed from the state in the database)
  • image specific properties, for which a difference in the database independent from the actual file does not make sense (width/height, bit depth, color model)

◆ fillCommonContainer()

void Digikam::ItemScanner::fillCommonContainer ( qlonglong  imageid,
ImageCommonContainer *const  container 
)
static

These methods provide the reverse service: Not writing into the db, but reading from the db.

◆ fillVideoMetadataContainer()

void Digikam::ItemScanner::fillVideoMetadataContainer ( qlonglong  imageid,
VideoMetadataContainer *const  container 
)
static

These methods provide the reverse service: Not writing into the db, but reading from the db.

◆ iptcCorePropertyName()

QString Digikam::ItemScanner::iptcCorePropertyName ( MetadataInfo::Field  field)
static

Allowed arguments: All MetadataInfo::Fields starting with "IptcCore..."

◆ itemScanInfo()

const ItemScanInfo & Digikam::ItemScanner::itemScanInfo ( ) const

The validity depends on the previously executed scan.

◆ loadFromDisk()

void Digikam::ItemScanner::loadFromDisk ( )

This method is called from any of the main entry points above. You can call it before if you want to control the time when it is executed. Calling it a second time with data already loaded will do nothing.

◆ newFileFullScan()

void Digikam::ItemScanner::newFileFullScan ( int  albumId)

This variant will not use the unique hash to establish identify with an existing entry, but read all information newly from the file.

◆ resolvedImageHistory()

DImageHistory Digikam::ItemScanner::resolvedImageHistory ( const DImageHistory history,
bool  mustBeAvailable = false 
)
static

In the returned history, the actions are the same, while each referred image actually exists in the collection (if mustBeAvailable is true, it is even in a currently available collection). That means the number of referred images may be less or greater than initially. Note that this history may have peculiar properties, like multiple Original or Current entries (if the source entry resolves to multiple collection images), so this history is only for internal use, not for storage.

◆ resolveImageHistory()

bool Digikam::ItemScanner::resolveImageHistory ( qlonglong  id,
QList< qlonglong > *  needTaggingIds = nullptr 
)
static

If needTaggingIds is given, all ids marked for needing tagging of the history graph are added.

◆ sameReferredImage()

bool Digikam::ItemScanner::sameReferredImage ( const HistoryImageId id1,
const HistoryImageId id2 
)
static

Does not check if such a referred image really exists.

◆ setCategory()

void Digikam::ItemScanner::setCategory ( DatabaseItem::Category  category)

Required at least for newFile() calls, recommended for calls with the first constructor above as well.

◆ sortByProximity()

void Digikam::ItemScanner::sortByProximity ( QList< ItemInfo > &  infos,
const ItemInfo subject 
)
static

Infos are near if they are e.g. in the same album. They are not near if they are e.g. in different collections.