File indexing completed on 2025-01-19 03:53:31

 /* ============================================================
  *
  * This file is a part of digiKam project
  * https://www.digikam.org
  *
  * Date        : 2007-03-19
  * Description : Core database Url interface.
  *
  * SPDX-FileCopyrightText: 2007-2008 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
  *
  * SPDX-License-Identifier: GPL-2.0-or-later
  *
  * ============================================================ */
 
 #ifndef DIGIKAM_CORE_DB_URL_H
 #define DIGIKAM_CORE_DB_URL_H
 
 // Qt includes
 
 #include <QDateTime>
 #include <QList>
 #include <QUrl>
 
 // Local includes
 
 #include "digikam_export.h"
 #include "dbengineparameters.h"
 #include "coredbaccess.h"
 
 namespace Digikam
 {
 
 class DIGIKAM_DATABASE_EXPORT CoreDbUrl : public QUrl
 {
 public:
 
     /**
       * This class shall facilitate the usage of
       * digikamalbums:/, digikamtags:/, digikamdates:/ and digikamsearch: URLs.
       * It provides functions to set and get the parameters stored in such a URL.
       * (with the exception of the search parameters in a search URL, which
       *  are out of the scope of this class.)
       */
 
     /**
       * Create a digikamalbums:/ URL from a file:// URL.
       * The file URL can point to a file or a directory (an album in this case).
       * The additional information stored in the URL need to be supplied as well:
       * - The album root in which the entity pointed to is stored.
       *   This is the left part of the file URL.
       *   (if the file is "/media/fotos/Summer 2007/001.jpg", the album root may be "/media/fotos")
       * - The parameters of the database that is referenced
       */
     static CoreDbUrl fromFileUrl(const QUrl& fileUrl,
                                  const QUrl& albumRoot,
                                  int   albumRootId,
                                  const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     static CoreDbUrl fromFileUrl(const QUrl& fileUrl,
                                  const QUrl& albumRoot,
                                  const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamalbums:/ url from an album name and an image in this album.
      * If name is empty, the album is referenced.
      * Other parameters as above.
      */
     static CoreDbUrl fromAlbumAndName(const QString& name,
                                       const QString& album,
                                       const QUrl& albumRoot,
                                       int   albumRootId,
                                       const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     static CoreDbUrl fromAlbumAndName(const QString& name,
                                       const QString& album,
                                       const QUrl& albumRoot,
                                       const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create an empty digikamalbums:/ url
      */
     static CoreDbUrl albumUrl(const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamtags:/ url from a list of tag IDs, where this list is the tag hierarchy
      * of the referenced tag, with the topmost parent first, and the tag last in the list.
      * An empty list references the root tag.
      */
     static CoreDbUrl fromTagIds(const QList<int>& tagIds,
                                 const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create an empty digikamdates:/ url
      */
     static CoreDbUrl dateUrl(const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamdates:/ url for the month of the given date.
      * (The whole month of the given date will included in the referenced time span)
      */
     static CoreDbUrl fromDateForMonth(const QDate& date,
                                       const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamdates:/ url for the year of the given date.
      * (The whole year of the given date will included in the referenced time span)
      */
     static CoreDbUrl fromDateForYear(const QDate& date,
                                      const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamdates:/ url for a specified time span which begin with the
      * start date (inclusive) and ends before the end date (exclusive).
      * To cover the whole year of 1984, you would pass 1/1/1984 and 1/1/1985.
      */
     static CoreDbUrl fromDateRange(const QDate& startDate, const QDate& endDate,
                                    const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create an empty digikammapimages:/ url
      */
     static CoreDbUrl mapImagesUrl(const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     static CoreDbUrl fromAreaRange(const qreal lat1, const qreal lng1,
                                    const qreal lat2, const qreal lng2,
                                    const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
      * Create a digikamsearch: URL for the search with the given id.
      */
     static CoreDbUrl searchUrl(int searchId, const DbEngineParameters& parameters = CoreDbAccess::parameters());
 
     /**
       * Create a CoreDbUrl object from a QUrl, to retrieve the information stored
       */
     explicit CoreDbUrl(const QUrl& digikamUrl);
 
     /**
      * Create an invalid database URL
      */
     CoreDbUrl();
 
     /**
      * These test for the protocol of this URL.
      * The protocol string is of course available via protocol().
      */
     bool isAlbumUrl()     const;
     bool isTagUrl()       const;
     bool isDateUrl()      const;
     bool isSearchUrl()    const;
     bool isMapImagesUrl() const;
 
     /**
      * Returns the DbEngineParameters stored in this URL.
      * Applicable to all protocols.
      */
     DbEngineParameters parameters() const;
 
     /**
      * Change the database parameters stored in this URL
      * Applicable to all protocols.
      */
     void setParameters(const DbEngineParameters& parameters);
 
     /**
      * The following methods are only applicable for a certain protocol each.
      * If the URL has another protocol, the return value of these methods is undefined.
      */
 
     /// Album URL
 
     /**
      * Returns the album root URL of the file or album referenced by this URL
      * In the example above, this is "file://media/fotos"
      */
     QUrl albumRoot() const;
 
     /**
      * Returns the album root path of the file or album referenced by this URL
      * In the example above, this is "/media/fotos"
      */
     QString albumRootPath() const;
 
     /**
      * Returns the album root id
      */
     int albumRootId() const;
 
     /**
      * Returns the album: This is the directory hierarchy below the album root.
      * In the example above, the album is "/Summer 2007"
      */
     QString album() const;
 
     /**
      * Returns the file name. In the example above, this is "001.jpg"
      */
     QString name() const;
 
     /**
      * Converts this digikamalbums:// URL to a file:// URL
      */
     QUrl fileUrl() const;
 
     /// Tag URL
 
     /**
      * Returns the tag ID, or -1 if the root tag is referenced
      */
     int tagId() const;
 
     /**
      * Returns the tag ids of all tags in the tag path of this tag,
      * the topmost tag in the hierarchy first.
      */
     QList<int> tagIds() const;
 
     /// Date URL
 
     /**
      * Return the referenced start date (included in the referenced span)
      */
     QDate startDate() const;
 
     /**
      * Return the referenced end date (excluded from the referenced span)
      */
     QDate endDate() const;
 
     /// MapImages URL
 
     /**
      * Returns the coordinates surrounding the map area.
      * Returns true if the string to number conversion was ok.
      */
     bool areaCoordinates(double* lat1, double* lat2, double* lon1, double* lon2) const;
 
     /// Search URL
 
     /**
      * Return the id of the search.
      */
     int searchId() const;
 
     CoreDbUrl(const CoreDbUrl& url);
 
     CoreDbUrl& operator=(const QUrl& digikamalbumsUrl);
     CoreDbUrl& operator=(const CoreDbUrl& url);
 
     bool operator==(const QUrl& digikamalbumsUrl) const;
 };
 
 } // namespace Digikam
 
 #endif // DIGIKAM_CORE_DB_URL_H