UTIOStreams.h

Go to the documentation of this file.

//==================================================================================================
// Copyright (C) 2010  Brian Tietz    sdbtietz at yahoo dot com
//
// This program is free software; you can redistribute it and/or modify it under the terms of the
// GNU General Public License as published by the Free Software Foundation, version 2.0 of the
// License.
//
// This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with this program; if
// not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
// 02110-1301, USA.
//
// For commercial software, the copyright holder (Brian Tietz, email sdbtietz at yahoo dot com)
// reserves the right and is willing to waive the proprietary source code disclosure aspects of that
// license as applied to the UT library in exchange for either substantial contributions to the
// development of the UT library or other forms of compensation.  Any such waiver must be
// established in writing between the copyright holder and the commercial entity obtaining such a
// waiver.
//==================================================================================================


#ifndef _UT_IOSTREAMS_H_
#define _UT_IOSTREAMS_H_


//==================================================================================================
//=== Project headers
//==================================================================================================
#include "UTString.h"


//==================================================================================================
//=== Forward name declarations
//==================================================================================================
class Buffer_t;


//==================================================================================================
//=== Debugging facilities
//==================================================================================================
#if LOG_FILE_OPS_CALLERS
    #define LOG_FILE_OPS    1
#endif


//==================================================================================================
class UT_EXPORT InputStream_t
//==================================================================================================
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
    virtual             ~InputStream_t();

    virtual Status_t    Read(   byte* buffer,
                                int bytes_to_read,
                                bool force_read_all = true ) = 0;

    virtual Status_t    ReadLine(out String_t* line);

    virtual Status_t    Peek( byte* buffer, int bytes_to_read );

    virtual Status_t    Position(out fileoff_t* position) = 0;

    virtual Status_t    Seek(fileoff_t position) = 0;

    virtual Status_t    SeekRelative(fileoff_t delta);

    virtual Status_t    Close() = 0;

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    #if LOG_FILE_OPS
    void                DebugLogReadLineError(  stringliteral* why,
                                                const byte* buf,
                                                int length,
                                                int curr_index,
                                                const String_t& accumulated ) const;
    #endif
};


//==================================================================================================
class UT_EXPORT OutputStream_t
//==================================================================================================
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
    virtual             ~OutputStream_t();

    virtual Status_t    Write(  const byte* buffer,
                                int bytes_to_write,
                                bool force_write_all = true ) = 0;

    virtual Status_t    WriteLine(  const String_t& line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    WriteLine(  const utf8* line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    WriteLine(  stringliteral* line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    Position(out fileoff_t* position) = 0;

    virtual Status_t    Seek(fileoff_t position) = 0;

    virtual Status_t    SeekRelative(fileoff_t delta);

    virtual Status_t    Flush() = 0;

    virtual Status_t    Close() = 0;
};


//==================================================================================================
class UT_EXPORT IOStream_t
//==================================================================================================
:   public InputStream_t,
    public OutputStream_t
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
    virtual Status_t    Position(out fileoff_t* position) = 0;

    virtual Status_t    Seek(fileoff_t position) = 0;

    virtual Status_t    SeekRelative(fileoff_t delta);

    virtual Status_t    Close() = 0;

    #if LOG_FILE_OPS
    static void         SetFileUnderTest(IOStream_t* file);
    #endif

    //----------------------------------------------------------------------------------------------
    protected:
    //----------------------------------------------------------------------------------------------
    #if LOG_FILE_OPS
    virtual void AppendStateInfo(String_t* state) const;

    static void FunctionIn( const IOStream_t* file,
                            bool from_thread,
                            stringliteral* function,
                            stringliteral* format,
                            ... );

    static void FunctionReturnStatusCode(   const IOStream_t* file,
                                            bool from_thread,
                                            int line,
                                            error_code_t status );

    static void FunctionReturn( const IOStream_t* file, bool from_thread, int line );

    static void FunctionLogState(   const IOStream_t* file,
                                    bool from_thread,
                                    int line,
                                    stringliteral* format,
                                    ... );

    static void FunctionReadStart(  const IOStream_t* file,
                                    bool from_thread,
                                    int line,
                                    fileoff_t pos,
                                    int bytes_to_read,
                                    bool force_read_all );

    static void FunctionReadData(   const IOStream_t* file,
                                    bool from_thread,
                                    int line,
                                    const byte* buffer,
                                    fileoff_t pos,
                                    int bytes_read );

    static void FunctionWriteData(  const IOStream_t* file,
                                    bool from_thread,
                                    int line,
                                    stringliteral* what,
                                    const byte* buffer,
                                    fileoff_t pos,
                                    int bytes_to_write,
                                    bool force_write_all );
    #endif
};


//==================================================================================================
class UT_EXPORT BufferIOStream_t
//==================================================================================================
: public IOStream_t
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
    inline              BufferIOStream_t(Buffer_t* buffer);

    virtual Status_t    Read(   byte* buffer,
                                int bytes_to_read,
                                bool force_read_all = true );

    virtual Status_t    ReadLine(out String_t* line);

    virtual Status_t    Peek( byte* buffer, int bytes_to_read );

    virtual Status_t    Write(  const byte* buffer,
                                int bytes_to_write,
                                bool force_write_all = true );

    virtual Status_t    Position(out fileoff_t* position);

    virtual Status_t    Seek(fileoff_t position);

    virtual Status_t    SeekRelative(fileoff_t delta);

    virtual Status_t    Flush();

    virtual Status_t    Close();

    //----------------------------------------------------------------------------------------------
    protected:
    //----------------------------------------------------------------------------------------------
    #if LOG_FILE_OPS
    virtual void        AppendStateInfo(String_t* state) const;

    #endif

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    Buffer_t*           m_buffer;
    int                 m_pos;
};


//==================================================================================================
//=== Debugging facilities
//==================================================================================================
#if LOG_FILE_OPS

// \cond DOXYGEN_DOCUMENT_NEVER
class CallLogger_t;
extern UT_EXPORT CallLogger_t* FileCanLog( const IOStream_t* file, bool from_thread );
// \endcond

#define debug_file_func_in( file, from_thread, func, format, a1, a2 )                                  \
    IOStream_t::FunctionIn( file, from_thread, func, format, a1, a2 )

#define debug_file_func_return_statuscode( file, from_thread, status )                             \
    IOStream_t::FunctionReturnStatusCode( file, from_thread, __LINE__, status )

#define debug_file_func_return( file, from_thread )                                                \
    IOStream_t::FunctionReturn( file, from_thread, __LINE__ )

#define debug_file_func_state1( file, from_thread, format, a1 )                                    \
    IOStream_t::FunctionLogState( file, from_thread, __LINE__, format, a1 )

#define debug_file_func_state2( file, from_thread, format, a1, a2 )                                \
    IOStream_t::FunctionLogState( file, from_thread, __LINE__, format, a1, a2 )

#define debug_file_func_read_start( file, from_thread, pos, bytes_to_read, all )                       \
    IOStream_t::FunctionReadStart( file, from_thread, __LINE__, pos, bytes_to_read, all )

#define debug_file_func_read_data( file, from_thread, buffer, pos, bytes_read )                    \
    IOStream_t::FunctionReadData( file, from_thread, __LINE__, buffer, pos, bytes_read )

#define debug_file_func_write_data( file, from_thread, what, buffer, pos, bytes_to_write, all )    \
    IOStream_t::FunctionWriteData(  file,                                                          \
                                    from_thread,                                                   \
                                    __LINE__,                                                      \
                                    what,                                                          \
                                    buffer,                                                        \
                                    pos,                                                           \
                                    bytes_to_write,                                                \
                                    all )

#else

#define debug_file_func_in( file, from_thread, func, format, a1, a2 )
#define debug_file_func_return_statuscode( file, from_thread, status )
#define debug_file_func_return( file, from_thread )
#define debug_file_func_state1( file, from_thread, format, a1 )
#define debug_file_func_state2( file, from_thread, format, a1, a2 )
#define debug_file_func_read_start( file, from_thread, pos, bytes_to_read, all )
#define debug_file_func_read_data( file, from_thread, buffer, pos, bytes_read )
#define debug_file_func_write_data( file, from_thread, what, buffer, pos, bytes_to_write, all )

#endif




//==================================================================================================
//==================================================================================================
//===
//=== Inline function implementations
//===
//==================================================================================================
//==================================================================================================
inline
BufferIOStream_t::BufferIOStream_t(Buffer_t* buffer)
{
    m_buffer = buffer;
    m_pos = 0;
}


#endif // _UT_IOSTREAMS_H_