KCoreAddons

kbackup.h
1 /*
2  This file is part of the KDE libraries
3 
4  SPDX-FileCopyrightText: 1999 Waldo Bastian <[email protected]>
5  SPDX-FileCopyrightText: 2006 Jaison Lee <[email protected]>
6  SPDX-FileCopyrightText: 2011 Romain Perier <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-only
9 */
10 
11 #ifndef KBACKUP_H
12 #define KBACKUP_H
13 
14 #include <QString>
15 #include <kcoreaddons_export.h>
16 
17 /**
18  * @namespace KBackup
19  * Provides utility functions for backup of files.
20  */
21 namespace KBackup
22 {
23 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 75)
24 /**
25  * @brief Function to create a backup file before saving.
26  *
27  * @warning This code lost its former functionality during the conversion from KDELibs4 to KDE Framrworks 5.
28  * It now only forwards and calls
29  * @code
30 KBackup::simpleBackupFile(filename, backupDir, QStringLiteral("~")));
31  * @endcode
32  * To restore the former functionality for your software, which read
33  * the backup type (simple or numbered), extension string, and maximum
34  * number of backup files from the user's global configuration,
35  * you could use code like this:
36  * @code
37  KConfigGroup configGroup(KSharedConfig::openConfig(), "Backups"); // look in the Backups section
38  const QString type = configGroup.readEntry("Type", QStringLiteral("simple"));
39  const QString extension = configGroup.readEntry("Extension", QStringLiteral("~"));
40  bool success = false;
41  if (type == QLatin1String("numbered")) {
42  const int maxNumber = configGroup.readEntry("MaxBackups", 10);
43  success = numberedBackupFile(filename, backupDir, extension, maxNumber);
44  } else {
45  success = simpleBackupFile(filename, backupDir, extension);
46  }
47  * @endcode
48  *
49  * @param filename the file to backup
50  * @param backupDir optional directory where to save the backup file in.
51  * If empty (the default), the backup will be in the same directory as @p filename.
52  * @return true if successful, or false if an error has occurred.
53  *
54  * @deprecated Since 5.0, use simpleBackupFile() or numberedBackupFile() directly
55  */
56 KCOREADDONS_DEPRECATED_VERSION_BELATED(5, 75, 5, 0, "Use simpleBackupFile() or numberedBackupFile() directly")
57 KCOREADDONS_EXPORT bool backupFile(const QString &filename, const QString &backupDir = QString());
58 #endif
59 
60 /**
61  * @brief Function to create a backup file for a given filename.
62  *
63  * This function creates a backup file from the given filename.
64  * You can use this method even if you don't use KSaveFile.
65  * @param filename the file to backup
66  * @param backupDir optional directory where to save the backup file in.
67  * If empty (the default), the backup will be in the same directory as @p filename.
68  * @param backupExtension the extension to append to @p filename, "~" by default.
69  * @return true if successful, or false if an error has occurred.
70  */
71 KCOREADDONS_EXPORT bool simpleBackupFile(const QString &filename, const QString &backupDir = QString(), const QString &backupExtension = QStringLiteral("~"));
72 
73 /**
74  * @brief Function to create a backup file for a given filename.
75  *
76  * This function creates a series of numbered backup files from the
77  * given filename.
78  *
79  * The backup file names will be of the form:
80  * <name>.<number><extension>
81  * for instance
82  * \verbatim chat.3.log \endverbatim
83  *
84  * The new backup file will be have the backup number 1.
85  * Each existing backup file will have its number incremented by 1.
86  * Any backup files with numbers greater than the maximum number
87  * permitted (@p maxBackups) will be removed.
88  * You can use this method even if you don't use KSaveFile.
89  *
90  * @param filename the file to backup
91  * @param backupDir optional directory where to save the backup file in.
92  * If empty (the default), the backup will be in the same directory as
93  * @p filename.
94  * @param backupExtension the extension to append to @p filename,
95  * which is "~" by default. Do not use an extension containing digits.
96  * @param maxBackups the maximum number of backup files permitted.
97  * For best performance a small number (10) is recommended.
98  * @return true if successful, or false if an error has occurred.
99  */
100 KCOREADDONS_EXPORT bool numberedBackupFile(const QString &filename,
101  const QString &backupDir = QString(),
102  const QString &backupExtension = QStringLiteral("~"),
103  const uint maxBackups = 10);
104 
105 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 75)
106 /**
107  * @brief Function to create an rcs backup file for a given filename.
108  *
109  * This function creates a rcs-formatted backup file from the
110  * given filename.
111  *
112  * The backup file names will be of the form:
113  * <name>,v
114  * for instance
115  * \verbatim photo.jpg,v \endverbatim
116  *
117  * The new backup file will be in RCS format.
118  * Each existing backup file will be committed as a new revision.
119  * You can use this method even if you don't use KSaveFile.
120  *
121  * @param filename the file to backup
122  * @param backupDir optional directory where to save the backup file in.
123  * If empty (the default), the backup will be in the same directory as
124  * @p filename.
125  * @param backupMessage is the RCS commit message for this revision.
126  * @return true if successful, or false if an error has occurred.
127  * @deprecated Since 5.75, no known users
128  */
129 KCOREADDONS_DEPRECATED_VERSION(5, 75, "No known users")
130 KCOREADDONS_EXPORT bool rcsBackupFile(const QString &filename, const QString &backupDir = QString(), const QString &backupMessage = QString());
131 #endif
132 }
133 
134 #endif
bool rcsBackupFile(const QString &qFilename, const QString &backupDir, const QString &backupMessage)
Function to create an rcs backup file for a given filename.
Definition: kbackup.cpp:47
bool numberedBackupFile(const QString &qFilename, const QString &backupDir, const QString &backupExtension, const uint maxBackups)
Function to create a backup file for a given filename.
Definition: kbackup.cpp:120
Provides utility functions for backup of files.
Definition: kbackup.cpp:23
bool simpleBackupFile(const QString &qFilename, const QString &backupDir, const QString &backupExtension)
Function to create a backup file for a given filename.
Definition: kbackup.cpp:32
KCOREADDONS_DEPRECATED_VERSION_BELATED(5, 75, 5, 0,"Use simpleBackupFile() or numberedBackupFile() directly") KCOREADDONS_EXPORT bool backupFile(const QString &filename
Function to create a backup file before saving.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Apr 9 2021 23:01:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.