FS_Writer.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        FS_Writer.h ( FS Library, C++)
 *
 * COMMENTS:
 *
 */

#ifndef __FS_Writer__
#define __FS_Writer__

#include "FS_API.h"

#include <SYS/SYS_Types.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_UniquePtr.h>

#include <iosfwd>
#include <sys/types.h>

#if _WIN32
using mode_t = int;
#endif

class FS_WriterHelper;
class FS_WriterStream;

template <typename T> class UT_Array;

/// Class for writing files
class FS_API FS_Writer final
{
public:
    /// Use this constructor to create a new writer. The specified file is
    /// created immediately.
             FS_Writer(const char *dest);

            ~FS_Writer();

             FS_Writer(FS_Writer&&) noexcept;
             UT_NON_COPYABLE(FS_Writer)

    /// Get the amount of memory owned by this FS_Writer
    int64                getMemoryUsage(bool inclusive) const;

    /// Closes the stream. After calling this function, the getStream()
    /// function will always return @c NULL.
    void                 close();

    /// This function retrieves the C++ stream object which you can interact
    /// with in the normal ways. If this function returns @c NULL, the file
    /// specified in the constructor could not be created.
    std::ostream        *getStream() const;

    bool                 removeFile();

    // Functions for adding and removing helpers.
    static void          addWriterHelper(FS_WriterHelper *helper);
    static void          removeWriterHelper(FS_WriterHelper *helper);

    /// Ensure plugins for read helpers are loaded
    static void          ensureHelpersLoaded();

private:
    void                 createStreamFromDest(const char *dest);

    UT_UniquePtr<FS_WriterStream>   myStream;
};

/// This class provides a plug-in method for adding a custom "file-system"
/// @see FS_ReaderHelper, FS_InfoHelper
class FS_API FS_WriterHelper
{
public:
             FS_WriterHelper()
             { FS_Writer::addWriterHelper(this); }
    virtual ~FS_WriterHelper()
             { FS_Writer::removeWriterHelper(this); }

    UT_NON_COPYABLE(FS_WriterHelper)

    /// Return an FS_WriterStream if the helper is able to open the source
    /// filename.
    virtual FS_WriterStream     *createStream(const char *source) = 0;

    /// Whether this helper supports the given source path for makeDirectory().
    ///
    /// If this helper supports the concept of directories and can create them,
    /// then this method should share the same implementation as your
    /// FS_InfoHelper::canHandle() override.
    ///
    /// This is required for backwards compatibility for old FS_WriterHelper
    /// classes that did not understand how to make directories.  When this
    /// returns false and an FS_InfoHelper exists for source, FSmakeDirs() will
    /// silently succeed to allow FS_WriterHelper::createStream() a chance to
    /// create source without first creating the necessary directories.
    /// This is to support cases where source has no concept of a "directory".
    virtual bool                 canMakeDirectory(const char *source)
                                    { return false; }

    /// Make a directory and all the parent directories needed.
    ///
    /// @param source @n The path to create
    /// @param mode @n The unix file mode used to create the directory
    /// @param ignore_umask @n
    ///   By default, the user's umask will be used in conjunction with the
    ///   mode. This parameter will @b force the mode to be the given value.
    ///
    /// @note From the HDK, this is used by FSmakeDirs().
    virtual bool                 makeDirectory(
                                        const char *source,
                                        mode_t mode = 0777,
                                        bool ignore_umask = false)
                                    { return false; }
};

FS_API UT_Array<FS_WriterHelper *> &FSgetWriterHelpers();

#endif