digiKam Developer Documentation: Digikam::ItemScanner Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | List of all members
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 ItemScanInfo & | itemScanInfo () 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.
static void | sortByProximity (QList< ItemInfo > &infos, const ItemInfo &subject)
| Sort a list of infos by proximity to the given subject.
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.

## ◆ 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.