• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdelibs-4.10.2 API Reference
  • KDE Home
  • Contact Us
 

KDECore

Public Member Functions | Static Public Member Functions | List of all members
KSaveFile Class Reference

#include <KSaveFile>

Inheritance diagram for KSaveFile:

Public Member Functions

 KSaveFile ()
 
 KSaveFile (const QString &filename, const KComponentData &componentData=KGlobal::mainComponent())
 
virtual ~KSaveFile ()
 
void abort ()
 
QFile::FileError error () const
 
QString errorString () const
 
QString fileName () const
 
bool finalize ()
 
virtual bool open (OpenMode flags=QIODevice::ReadWrite)
 
void setFileName (const QString &filename)
 

Static Public Member Functions

static bool backupFile (const QString &filename, const QString &backupDir=QString())
 
static bool numberedBackupFile (const QString &filename, const QString &backupDir=QString(), const QString &backupExtension=QString::fromLatin1("~"), const uint maxBackups=10)
 
static bool rcsBackupFile (const QString &filename, const QString &backupDir=QString(), const QString &backupMessage=QString())
 
static bool simpleBackupFile (const QString &filename, const QString &backupDir=QString(), const QString &backupExtension=QLatin1String("~"))
 

Detailed Description

Class to allow for atomic file I/O, as well as utility functions.

The KSaveFile class has been made to write out changes to an existing file atomically. This means that either ALL changes will be written to the file, or NO changes have been written, and the original file (if any) has been unchanged. This is useful if you have lots of time-consuming processing to perform during which an interruption could occur, or if any error in the file structure will cause the entire file to be corrupt.

When you create a KSaveFile for a given file, a temporary file is instead created and all your I/O occurs in the save file. Once you call finalize() the temporary file is renamed to the target file, so that all your changes happen at once. If abort() is called then the temporary file is removed and the target file is untouched. KSaveFile derives from QFile so you can use it just as you would a normal QFile.

This class also includes several static utility functions available that can help ensure data integrity. See the individual functions for details.

Here is a quick example of how to use KSaveFile:

First we create the KSaveFile and open it.

KSaveFile saveFile;
saveFile.setFileName("/lib/foo/bar.dat");
if ( !saveFile.open() ) {
//Handle error
}

At this point the file "/lib/foo/bar.dat" has not been altered in any way. Now, let's write out some data to the file.

QTextStream stream ( &saveFile );
stream << "Add some data.";
// Perform long processing
stream << "Add some more data.";
stream.flush();

Even after writing this data, the target file "/lib/foo/bar.dat" still has not been altered in any way. Now that we are done writing our data, we can write out all the changes that we have made by calling finalize().

if ( !saveFile.finalize() ) {
//Handle error
}

If a user interruption or error occurred while we were writing out our changes, we would instead call abort() to cancel all the I/O without affecting the target file.

See Also
QFile
Author
Jaison Lee lee.j.nosp@m.aiso.nosp@m.n@gma.nosp@m.il.c.nosp@m.om
Waldo Bastian basti.nosp@m.an@k.nosp@m.de.or.nosp@m.g

Definition at line 96 of file ksavefile.h.

Constructor & Destructor Documentation

KSaveFile::KSaveFile ( )

Default constructor.

Definition at line 60 of file ksavefile.cpp.

KSaveFile::KSaveFile ( const QString &  filename,
const KComponentData &  componentData = KGlobal::mainComponent() 
)
explicit

Creates a new KSaveFile and sets the target file to filename.

Parameters
filenamethe path of the file
componentDataunused

Definition at line 66 of file ksavefile.cpp.

KSaveFile::~KSaveFile ( )
virtual

Destructor.

Note
If the file has been opened but not yet finalized, the destructor will call finalize(). If you do not want the target file to be affected you need to call abort() before destroying the object.

Definition at line 72 of file ksavefile.cpp.

Member Function Documentation

void KSaveFile::abort ( )

Discard changes without affecting the target file.

This will discard all changes that have been made to this file. The target file will not be altered in any way.

Definition at line 185 of file ksavefile.cpp.

bool KSaveFile::backupFile ( const QString &  filename,
const QString &  backupDir = QString() 
)
static

Static method to create a backup file before saving.

If empty (the default), the backup will be in the same directory as filename. The backup type (simple, rcs, or numbered), extension string, and maximum number of backup files are read from the user's global configuration. Use simpleBackupFile() or numberedBackupFile() to force one of these specific backup styles. You can use this method even if you don't use KSaveFile.

Parameters
filenamethe file to backup
backupDiroptional directory where to save the backup file in.
Returns
true if successful, or false if an error has occurred.

Definition at line 251 of file ksavefile.cpp.

QFile::FileError KSaveFile::error ( ) const

Returns the last error that occurred.

Use this function to check for errors.

Returns
The last error that occurred, or QFile::NoError.

Definition at line 162 of file ksavefile.cpp.

QString KSaveFile::errorString ( ) const

Returns a human-readable description of the last error.

Use this function to get a human-readable description of the last error that occurred.

Returns
A string describing the last error that occurred.

Definition at line 171 of file ksavefile.cpp.

QString KSaveFile::fileName ( ) const

Returns the name of the target file.

This function returns the name of the target file, or an empty QString if it has not yet been set.

Returns
The name of the target file.

Definition at line 180 of file ksavefile.cpp.

bool KSaveFile::finalize ( )

Finalize changes to the file.

This will commit all the changes that have been made to the file.

Returns
true if successful, or false if an error has occurred.

Definition at line 198 of file ksavefile.cpp.

bool KSaveFile::numberedBackupFile ( const QString &  filename,
const QString &  backupDir = QString(),
const QString &  backupExtension = QString::fromLatin1( "~" ),
const uint  maxBackups = 10 
)
static

Static method to create a backup file for a given filename.

This function creates a series of numbered backup files from the given filename.

The backup file names will be of the form: <name>.<number><extension> for instance

chat.3.log 

The new backup file will be have the backup number 1. Each existing backup file will have its number incremented by 1. Any backup files with numbers greater than the maximum number permitted (maxBackups) will be removed. You can use this method even if you don't use KSaveFile.

Parameters
filenamethe file to backup
backupDiroptional directory where to save the backup file in. If empty (the default), the backup will be in the same directory as filename.
backupExtensionthe extension to append to filename, which is "~" by default. Do not use an extension containing digits.
maxBackupsthe maximum number of backup files permitted. For best performance a small number (10) is recommended.
Returns
true if successful, or false if an error has occurred.

Definition at line 354 of file ksavefile.cpp.

bool KSaveFile::open ( OpenMode  flags = QIODevice::ReadWrite)
virtual

Open the save file.

This function will open the save file by creating a temporary file to write to. It will also check to ensure that there are sufficient permissions to write to the target file.

Parameters
flagsSets the QIODevice::OpenMode. It should contain the write flag, otherwise you have a save file you cannot save to.
Returns
true if successful, or false if an error has occurred.

Definition at line 80 of file ksavefile.cpp.

bool KSaveFile::rcsBackupFile ( const QString &  filename,
const QString &  backupDir = QString(),
const QString &  backupMessage = QString() 
)
static

Static method to create an rcs backup file for a given filename.

This function creates a rcs-formatted backup file from the given filename.

The backup file names will be of the form: <name>,v for instance

photo.jpg,v 

The new backup file will be in RCS format. Each existing backup file will be committed as a new revision. You can use this method even if you don't use KSaveFile.

Parameters
filenamethe file to backup
backupDiroptional directory where to save the backup file in. If empty (the default), the backup will be in the same directory as filename.
backupMessageis the RCS commit message for this revision.
Returns
true if successful, or false if an error has occurred.

Definition at line 287 of file ksavefile.cpp.

void KSaveFile::setFileName ( const QString &  filename)

Set the target filename for the save file.

You must use this to set the filename of the target file if you do not use the contructor that does so.

Parameters
filenameName of the target file.

Definition at line 147 of file ksavefile.cpp.

bool KSaveFile::simpleBackupFile ( const QString &  filename,
const QString &  backupDir = QString(),
const QString &  backupExtension = QLatin1String( "~" ) 
)
static

Static method to create a backup file for a given filename.

This function creates a backup file from the given filename. You can use this method even if you don't use KSaveFile.

Parameters
filenamethe file to backup
backupDiroptional directory where to save the backup file in. If empty (the default), the backup will be in the same directory as filename.
backupExtensionthe extension to append to filename, "~" by default.
Returns
true if successful, or false if an error has occurred.

Definition at line 271 of file ksavefile.cpp.


The documentation for this class was generated from the following files:
  • ksavefile.h
  • ksavefile.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Tue Apr 16 2013 19:11:48 by doxygen 1.8.3.1 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KDECore

Skip menu "KDECore"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages

kdelibs-4.10.2 API Reference

Skip menu "kdelibs-4.10.2 API Reference"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDEWebKit
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUnitConversion
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal