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
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)
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
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)
static QDateTime	creationDateFromFilesystem (const QFileInfo &info)
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)
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

Returns

a suitable creation date from file system information. 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

Returns

File-metadata container with user-presentable information. 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

Returns

Video container with user-presentable information. These methods provide the reverse service: Not writing into the db, but reading from the db.

hasHistoryToResolve()

bool Digikam::ItemScanner::hasHistoryToResolve

(

)

const

Returns

true if this file has been marked as needing history resolution at a later stage

id()

qlonglong Digikam::ItemScanner::id

(

)

const

Returns

the image id of the scanned file, if (yet) available.

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.

resolveHistoryImageId()

QList< qlonglong > Digikam::ItemScanner::resolveHistoryImageId ( const HistoryImageId & historyId )

static

Returns

all image ids fulfilling the given image id.

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.