File indexing completed on 2024-05-19 05:00:33

0001 /*
0002  *   SPDX-FileCopyrightText: 2019 Méven Car <meven.car@kdemail.net>
0003  *
0004  *   SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0005  */
0006 
0007 #ifndef RECENTLYUSED_H
0008 #define RECENTLYUSED_H
0009 
0010 #include <KIO/WorkerBase>
0011 
0012 /**
0013  * Implements recentlyused:/ KIO worker
0014  * It uses KActivitiesStats as a backend (as kickoff/kicker do) to retrieve recently accessed
0015  * files or folders.
0016  * It supports filtering on mimetype (option type), path, date of access or date of access range, activity and agent (meaning application).
0017  * There are also order and limit options.
0018  *
0019  * There only three path allowed : / /files and /locations.
0020  * / does not do anything special
0021  * /files returns only files whose mimetype is known to the KActivity backend
0022  * /locations returns only folders
0023  * When /locations is used the option ?type, described below, cannot be used.
0024  *
0025  * It supports options to filter what is returned through url parameters:
0026  *
0027  * ?activity=[activity UUID|any]
0028  *
0029  *   Allows to filter the resources based on the activity they were used in.
0030  *   Defaults to the current user activity.
0031  *   any value means include resources from any activity.
0032  *   Example: recentlyused:/?activity=428fa590-1920-4b3c-a7e1-1842e6164707
0033  *
0034  * ?date=[ISODATE[,ISODATE]|today|yesterday]
0035  *
0036  *   Allows to filter on event date of resources
0037  *   today and yesterday returns resource that had an event today or
0038  *   yesterday respectively.
0039  *   ISODATE must be of the form YYYY-MM-DD
0040  *   If a secondary date is passed, the filtering occurs on the date range starting
0041  *   at the first date passed and ending at the second date passed inclusively
0042  *   Example: recentlyused:/?date=2019-07-30
0043  *
0044  * ?agent=[agentName1[,agentName*]*
0045  *
0046  *   Filter on the name or names of the application that used the resource.
0047  *   Defaults to no agent filtering
0048  *   Example: recentlyused:/?agent=kate,dolphin
0049  *
0050  * ?path=path
0051  *
0052  *   Filters resources based on the path of the file or directory.
0053  *   Path can contain '*', defaults to no filtering.
0054  *   Example: recentlyused:/?path=/home/meven/projects/*
0055  *
0056  * ?type=mimetype[,mimetype]*
0057  *
0058  *   Filters resources based on the mimetype of files.
0059  *   Defaults to no filtering
0060  *   Example: recentlyused:/?type=video/*,audio/*
0061  *
0062  * ?limit=number
0063  *
0064  *   Specify the number of resources to return.
0065  *   Defaults to 30
0066  *   Example: recentlyused:/?limit=10
0067  *
0068  * ?order=(HighScoredFirst|RecentlyCreatedFirst|OrderByUrl|OrderByTitle)
0069  *   Allow to modify the order of the returned resources.
0070  *   Defaults to RecentlyUsedFirst
0071  *   See KActivities::Stats::Terms::Order for detail
0072  *   Example: recentlyused:/?limit=HighScoredFirst
0073  *
0074  * Examples:
0075  *
0076  * - recentlyused:/?type=video/*,audio/*&order=HighScoredFirst : recently used video or audio files ordered by their scoring descending
0077  * - recentlyused:/?url=/home/meven/kde/src/*&type=text/plain : recently used text files located in a subdir of /home/meven/kde/src/
0078  *
0079  * @brief The RecentlyUsed implements an KIO worker to access recently used files or directories
0080  */
0081 class RecentlyUsed : public KIO::WorkerBase
0082 {
0083 public:
0084     RecentlyUsed(const QByteArray &pool, const QByteArray &app);
0085     ~RecentlyUsed() override;
0086 
0087 protected:
0088     KIO::WorkerResult listDir(const QUrl &url) override;
0089     KIO::WorkerResult stat(const QUrl &url) override;
0090     KIO::WorkerResult mimetype(const QUrl &url) override;
0091 
0092     /**
0093      * Implemention of the forget action
0094      *
0095      *  Use it like so:
0096      *
0097      *  QByteArray packedArgs;
0098      *  QDataStream stream(&packedArgs, QIODevice::WriteOnly);
0099      *  stream << int(1); // Forget
0100      *  stream << urls;
0101      *
0102      *  auto job = KIO::special(QUrl("recentlyused:/"), packedArgs);
0103      *  job->exec();
0104      */
0105     KIO::WorkerResult special(const QByteArray &data) override;
0106 
0107 private:
0108     /*
0109      * Creates a udsEntry for recentlyused:/
0110      *
0111      * row is the row number in the ResultModel for the recentlyused:/ url being queried
0112      */
0113     KIO::UDSEntry udsEntryFromResource(int row, const QString &resource, const QString &mimeType, const QString &agent, int lastUpdateTime);
0114     KIO::UDSEntry udsEntryForRoot(const QString &dirName, const QString &iconName);
0115 };
0116 
0117 #endif