AirTV-Qt/qtsingleapplication/src/qtlockedfile.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 **
   6 ** Contact: Nokia Corporation (qt-info@nokia.com)
   7 **
   8 ** This file is part of a Qt Solutions component.
   9 **
  10 ** You may use this file under the terms of the BSD license as follows:
  11 **
  12 ** "Redistribution and use in source and binary forms, with or without
  13 ** modification, are permitted provided that the following conditions are
  14 ** met:
  15 **   * Redistributions of source code must retain the above copyright
  16 **     notice, this list of conditions and the following disclaimer.
  17 **   * Redistributions in binary form must reproduce the above copyright
  18 **     notice, this list of conditions and the following disclaimer in
  19 **     the documentation and/or other materials provided with the
  20 **     distribution.
  21 **   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
  22 **     the names of its contributors may be used to endorse or promote
  23 **     products derived from this software without specific prior written
  24 **     permission.
  25 **
  26 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  27 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  28 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  29 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  30 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  31 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  32 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  33 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  34 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  35 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  36 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
  37 **
  38 ****************************************************************************/
  39
  40 #include "qtlockedfile.h"
  41
  42 /*!
  43     \class QtLockedFile
  44
  45     \brief The QtLockedFile class extends QFile with advisory locking
  46     functions.
  47
  48     A file may be locked in read or write mode. Multiple instances of
  49     \e QtLockedFile, created in multiple processes running on the same
  50     machine, may have a file locked in read mode. Exactly one instance
  51     may have it locked in write mode. A read and a write lock cannot
  52     exist simultaneously on the same file.
  53
  54     The file locks are advisory. This means that nothing prevents
  55     another process from manipulating a locked file using QFile or
  56     file system functions offered by the OS. Serialization is only
  57     guaranteed if all processes that access the file use
  58     QLockedFile. Also, while holding a lock on a file, a process
  59     must not open the same file again (through any API), or locks
  60     can be unexpectedly lost.
  61
  62     The lock provided by an instance of \e QtLockedFile is released
  63     whenever the program terminates. This is true even when the
  64     program crashes and no destructors are called.
  65 */
  66
  67 /*! \enum QtLockedFile::LockMode
  68
  69     This enum describes the available lock modes.
  70
  71     \value ReadLock A read lock.
  72     \value WriteLock A write lock.
  73     \value NoLock Neither a read lock nor a write lock.
  74 */
  75
  76 /*!
  77     Constructs an unlocked \e QtLockedFile object. This constructor
  78     behaves in the same way as \e QFile::QFile().
  79
  80     \sa QFile::QFile()
  81 */
  82 QtLockedFile::QtLockedFile()
  83     : QFile()
  84 {
  85 #ifdef Q_OS_WIN
  86     wmutex = 0;
  87     rmutex = 0;
  88 #endif
  89     m_lock_mode = NoLock;
  90 }
  91
  92 /*!
  93     Constructs an unlocked QtLockedFile object with file \a name. This
  94     constructor behaves in the same way as \e QFile::QFile(const
  95     QString&).
  96
  97     \sa QFile::QFile()
  98 */
  99 QtLockedFile::QtLockedFile(const QString &name)
 100     : QFile(name)
 101 {
 102 #ifdef Q_OS_WIN
 103     wmutex = 0;
 104     rmutex = 0;
 105 #endif
 106     m_lock_mode = NoLock;
 107 }
 108
 109 /*!
 110   Opens the file in OpenMode \a mode.
 111
 112   This is identical to QFile::open(), with the one exception that the
 113   Truncate mode flag is disallowed. Truncation would conflict with the
 114   advisory file locking, since the file would be modified before the
 115   write lock is obtained. If truncation is required, use resize(0)
 116   after obtaining the write lock.
 117
 118   Returns true if successful; otherwise false.
 119
 120   \sa QFile::open(), QFile::resize()
 121 */
 122 bool QtLockedFile::open(OpenMode mode)
 123 {
 124     if (mode & QIODevice::Truncate) {
 125         qWarning("QtLockedFile::open(): Truncate mode not allowed.");
 126         return false;
 127     }
 128     return QFile::open(mode);
 129 }
 130
 131 /*!
 132     Returns \e true if this object has a in read or write lock;
 133     otherwise returns \e false.
 134
 135     \sa lockMode()
 136 */
 137 bool QtLockedFile::isLocked() const
 138 {
 139     return m_lock_mode != NoLock;
 140 }
 141
 142 /*!
 143     Returns the type of lock currently held by this object, or \e
 144     QtLockedFile::NoLock.
 145
 146     \sa isLocked()
 147 */
 148 QtLockedFile::LockMode QtLockedFile::lockMode() const
 149 {
 150     return m_lock_mode;
 151 }
 152
 153 /*!
 154     \fn bool QtLockedFile::lock(LockMode mode, bool block = true)
 155
 156     Obtains a lock of type \a mode. The file must be opened before it
 157     can be locked.
 158
 159     If \a block is true, this function will block until the lock is
 160     aquired. If \a block is false, this function returns \e false
 161     immediately if the lock cannot be aquired.
 162
 163     If this object already has a lock of type \a mode, this function
 164     returns \e true immediately. If this object has a lock of a
 165     different type than \a mode, the lock is first released and then a
 166     new lock is obtained.
 167
 168     This function returns \e true if, after it executes, the file is
 169     locked by this object, and \e false otherwise.
 170
 171     \sa unlock(), isLocked(), lockMode()
 172 */
 173
 174 /*!
 175     \fn bool QtLockedFile::unlock()
 176
 177     Releases a lock.
 178
 179     If the object has no lock, this function returns immediately.
 180
 181     This function returns \e true if, after it executes, the file is
 182     not locked by this object, and \e false otherwise.
 183
 184     \sa lock(), isLocked(), lockMode()
 185 */
 186
 187 /*!
 188     \fn QtLockedFile::~QtLockedFile()
 189
 190     Destroys the \e QtLockedFile object. If any locks were held, they
 191     are released.
 192 */