file.h

Go to the documentation of this file.

/*
 * file.h
 *
 * Copyright (C) 2003-2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Helpful file/filename utilities
 */

#ifndef WAVEPACKET_UTIL_FILE_H__
#define WAVEPACKET_UTIL_FILE_H__


// includes --------------------------------------------------------------------
#include "common/common.h"

#ifdef WIN32

// win32 filesystem headers
#include <io.h>

#else   // WIN32

// posix filesystem headers
#include <dirent.h>
#include <unistd.h>
#include <sys/errno.h>
#include <sys/file.h>

#endif  // WIN32


// doxygen block

/// \ingroup general
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup util Utility Library
///
/// Very low-level utility APIs and objects.  More or less a grab bag of
/// parsing, file, and date-based helper methods. 
///     
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/*
 * Filename APIs
 */


// GetExtension() -- gets the extension for the specified filename.  Returns
// NULL if there is no extension (no period in the name).  Can return an
// empty string if the filename ends in a period.
const char * GetExtension(IN const char * filename) throw();



/// returns true if the given filename ends with the specified string (NOT
///     case-sensitive)
bool hasExtension(IN const char * filename, IN const char * extension) throw();


// GetFileRoot() -- gets the root name from the given filename (strips out
// any path information, and the filename extension)
void GetFileRoot(IN const char * filename,
                OUT std::string& file_root);

// GetParentDirectory() -- given a full path, return the parent directory
// string will be empty if this is the root directory.
void GetParentDirectory(IN const char * filename,
        OUT std::string& directory) throw();

/// retrieves the highest known folder for the given file.
/// returns a pointer to the beginning of the filename now relative to
///     the top directory
const char * getTopDirectory(IN const char * filename,
                OUT std::string& topDir);


/// given a starting filename, and then a path relative to that, return
///     the full path of the file.  Examples:
///  - getPathRelativeTo("foo/bar.txt", "hi.txt") --> "foo/hi.txt"
///  - getPathRelativeTo("foo/bar.txt", "x/hi.txt") --> "foo/x/hi.txt"
///  - getPathRelativeTo("foo/bar.txt", "../hi.txt") --> "hi.txt"
///  - getPathRelativeTo("foo/models/x.model", "../textures/y.texture")
///     --> "foo/textures/y.texture"
std::string getPathRelativeTo(IN const char * startFilename,
                                IN const char * relFilename);


/// given a starting path (directory), append another piece of the path
void appendPath(IN const char * parentDirectory,
                                IN const char * nextPath,
                                OUT std::string& path);


// GetFilename() -- given a full path, return just the tail filename
const char * GetFilename(IN const char * path) throw();

// getTempfile() - given a full path, return a temp file in the same directory
void getTempfile(IN const char * path,
                OUT std::string& tempfile) throw();

// getUserHomePath() - determines the path to the user's home directory
void getUserHomePath(OUT std::string& path);

// ContainsWhitespace() - does this string contain whitespace?
bool ContainsWhitespace(IN const char * test) throw();

// doesPathExist() - does this path exist?
bool doesPathExist(IN const char * path) throw();

// createEmptyFileIfDoesNotExist() -- yup, creates empty file if none already there
void createEmptyFileIfDoesNotExist(IN const char * path) throw();


/// does a recursive directory walk, and returns all paths relative to root
void walkDirectoryTree(IN const char * rootDirectory,
                                IN const char * matchExtension, ///< can be null
                                OUT VecString& paths);

#ifdef WIN32
// my own win32 wrappers for opendir(), readdir(), closedir()
struct DIR {
        DIR(void) throw() { this->clear(); }
        void clear(void) throw() {
                        path = "";
                        h = NULL;
                }

        std::string     path;
        HANDLE          h;
};

DIR * opendir(IN const char * path);
struct dirent {
        char d_name[MAX_PATH];
};
struct dirent * readdir(IO DIR * dir);
int readdir_r(IO DIR * dir, IN struct dirent * entry,
        OUT struct dirent ** result);
int closedir(IN DIR * dir);
char * strerror_r(IN int error, IN char * buf, IN int bufsize);
#endif // WIN32



/// throws a (hopefully) descriptive error based on errno passed in
#define THROW_ERROR( error , args )                                     \
        {                                                               \
                if (error) {                                            \
                        char buffer[512];                               \
                        strerror_r(error, buffer, sizeof(buffer));      \
                        WAVE_EX(wex);                                   \
                        wex << "Encountered an error (" << error;       \
                        wex << "): " << buffer;                         \
                        wex << "\n" << args ;                           \
                }                                                       \
        }



/// smart file descriptor -- only use this for low-level objects!  You probably
///     want to use nstream or iostreams instead.
class smart_fd {
public:
        // constructor, destructor ---------------------------------------------
        smart_fd(void) throw() : m_fd(-1) { }
        smart_fd(IN int fd) throw() : m_fd(fd) { }
        ~smart_fd(void) throw() { this->clear(); }

        // accessors -----------------------------------------------------------
        void clear(void) throw() {
                        if (m_fd > -1) {
#ifdef WIN32
                                if (_close(m_fd)) {
#else   // WIN32
                                if (close(m_fd)) {
#endif  // WIN32
                                        DPRINTF("Failed to close descriptor");
                                }
                                m_fd = -1;
                        }
                }

        bool open(IN const char * path, IN int flags) {
                        this->clear();
#ifdef WIN32
                        m_fd = _open(path, flags);
#else   // WIN32
                        m_fd = ::open(path, flags);
#endif  // WIN32
                        return (m_fd > -1);
                }

        operator int(void) const throw() { return m_fd; }

        operator bool(void) const throw() { return (m_fd > -1); }
        bool operator !(void) const throw() { return (m_fd < 0); }

private:
        // we do not want to allow copy construction--who closes?
        smart_fd(IN const smart_fd&);

        // private member data -------------------------------------------------
        int             m_fd;   // file descriptor
};


/// smart directory handle.  You probably don't want to use this!  Use the
/// nstream interfaces instead.  This is for low-level filesystem access.
///
/// Why no constructor that takes a path?  Because opening a directory can fail!
/// Always use the open() method, and always check the result.
class smart_dir {
public:
        // constructor, destructor ---------------------------------------------
        smart_dir(void) throw() : m_dir(NULL) { }
        ~smart_dir(void) throw() { this->clear(); }

        // smart_dir class interface methods -----------------------------------
        void clear(void) throw() {
                        if (m_dir) {
                                closedir(m_dir);
                                m_dir = NULL;
                        }
                }

        operator bool(void) const throw() { return !!m_dir; }

        void open(IN const char * path) {
                        this->clear();
                        m_dir = opendir(path);
                        if (!m_dir) {
                                THROW_ERROR(errno,
                                    "Failed to open directory: " << path);
                        }
                }

        void close(void) throw() { this->clear(); }

        bool getNextEntry(OUT struct dirent& entry) {
                        ASSERT(m_dir, "need to open directory first!");
                        struct dirent * result = NULL;
                        THROW_ERROR(readdir_r(m_dir, &entry, &result),
                            "Failed to read next directory entry");
                        return (result != NULL);
                }

private:
        // hidden constructors -------------------------------------------------
        smart_dir(IN const smart_dir&);

        // private member data -------------------------------------------------
        DIR *           m_dir;  // directory handle
};



/// advisory locking object
/// \b WARNING: has no effect in Windows
class AdvisoryLock {
public:
        typedef int error_t;

        AdvisoryLock(void) throw() : m_fd(-1) { }
        ~AdvisoryLock(void) throw() {
                this->unlock();
                }

        bool attemptLock(IN const char * filename,
                        IN int operation) throw() {
                        ASSERT(filename, "NULL filename");
                        ASSERT(-1 == m_fd, "lock object already used");

#ifdef WIN32
                        operation = operation;  // ignore parameter
                        m_fd = 0;
#else   // WIN32
                        // open file descriptor
                        m_fd = open(filename, O_RDONLY);
                        if (-1 == m_fd) {
                                error_t error = errno;
                                DPRINTF("Could not open file: %s", filename);
                                DPRINTF("Open failed with error %d : %s",
                                    error, strerror(error));
                                return false;
                        }

                        // acquire lock
                        int result = flock(m_fd, operation);
                        if (-1 == result) {
                                close(m_fd);
                                m_fd = -1;
                                error_t error = errno;
                                DPRINTF("Lock failed with error %d : %s",
                                    error, strerror(error));
                                return false;
                        }
#endif  // WIN32
                        // success!
                        return true;
                }

        void unlock(void) throw() {
#ifndef WIN32
                        if (-1 != m_fd) {
                                flock(m_fd, LOCK_UN);
                                close(m_fd);
                                m_fd = -1;
                        }
#endif  // WIN32
                }

private:
        int             m_fd;   // file descriptor
};


/*@}*/  // end of documentation block

#endif  // WAVEPACKET_UTIL_FILE_H__