UTStatus.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_H_
#error "DO NOT INCLUDE THIS FILE - INCLUDE UT.h INSTEAD"
#endif


//==================================================================================================
//=== Error status value space integration
//==================================================================================================
typedef int32 error_code_t;

#if __cplusplus
#define ERROR_CODE(error_code)      ( static_cast<error_code_t>(error_code) )
#else
#define ERROR_CODE(error_code)      ( (error_code_t)(error_code) )
#endif

#if WINDOWS

#define eERR_windows_error_base     ERROR_CODE(0xC0000000)

#endif

#define eERR_unknown_error          ERROR_CODE(0xE0000000)

#define eERR_user_base              ERROR_CODE(0xE0010000)

#define eERR_posix_error_base       ERROR_CODE(0xEF000000)




//==================================================================================================
//=== Forward name declarations
//==================================================================================================
#if __cplusplus

class String_t;
class RefCountedString_t;


//==================================================================================================
class UT_EXPORT Status_t
//==================================================================================================
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
    inline                      Status_t();

    inline                      Status_t(error_code_t error_code);

    inline                      Status_t( error_code_t error_code, const utf8* explanation );

    inline                      Status_t( error_code_t error_code, stringliteral* explanation );

                                Status_t( error_code_t error_code, const String_t& explanation );

    inline                      Status_t(const Status_t& copy);

                                Status_t( const Status_t& copy, const utf8* explanation );

                                Status_t( const Status_t& copy, stringliteral* explanation );

                                Status_t( const Status_t& copy, const String_t& explanation );

    inline                      ~Status_t();

    inline const Status_t&      operator =(const Status_t& set);

    inline const Status_t&      operator =(error_code_t set);

    inline error_code_t         StatusCode() const;

    inline bool                 Success() const;

    inline bool                 SuccessAndTrue() const;

    inline bool                 SuccessAndFalse() const;

    const String_t*             Explanation() const;

    bool                        operator ==(const Status_t& other) const;

    inline bool                 operator ==(error_code_t error_code) const;

    inline bool                 operator !=(const Status_t& other);

    inline bool                 operator !=(error_code_t error_code);

    inline bool                 operator <(int32 value);

    inline bool                 operator <=(int32 value);

    inline bool                 operator >(int32 value);

    inline bool                 operator >=(int32 value);

    #if WINDOWS
    static Status_t             GetLastWinError();

    static Status_t             GetLastWinError(const utf8* extra_explanation);

    static Status_t             GetLastWinError(const String_t& extra_explanation);

    static Status_t             GetLastWinError(stringliteral* extra_explanation);

    inline static Status_t      WinError(int32 windows_error_code);

    inline static Status_t      WinError(   int32 windows_error_code,
                                            const utf8* extra_explanation );

    inline static Status_t      WinError(   int32 windows_error_code,
                                            stringliteral* extra_explanation );
    #endif

    inline static Status_t      POSIXError(int posix_error_code);

    inline static Status_t      POSIXError( int posix_error_code,
                                            const utf8* extra_explanation );

    inline static Status_t      POSIXError( int posix_error_code,
                                            stringliteral* extra_explanation );

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    void                        CreateExplanation(const utf8* explanation);
                                    // Creates explanatory text where m_explanation will be a
                                    // RefCountedString_t with a reference count of 1 and will have
                                    // made an autonomous copy of the explanatory text.

    void                        CreateExplanation(stringliteral* explanation);
                                    // Creates explanatory text where m_explanation will be a
                                    // RefCountedString_t with a reference count of 1.  The
                                    // explanatory String_t persistently references the string
                                    // literal; the pointer is borrowed.  Therefore the Status_t
                                    // object and its explanatory text, including copies of it and
                                    // copies returned by value are dependent on the pointer with
                                    // which it was constructed.  The contents of that pointer must
                                    // remain valid for the life of the Status_t object and all
                                    // copies.

    void                        AddExplanation(RefCountedString_t* explanation);
                                    // Attaches the specified explanation to this, and adds 
                                    // reference to it, preventing the explanation
                                    // RefCountedString_t object from being deleted until this 
                                    // either been deleted or assigned a new value.

    void                        RemoveExplanation();
                                    // Removes a reference to the attached explanatory text when
                                    // deleting this or assigning it a new value to facilitate its
                                    // deletion when the last reference is removed.

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    error_code_t                m_error_code;
    RefCountedString_t*         m_explanation;
};


#endif // __cplusplus


//==================================================================================================
//=== User-defined error support for Status_t
//==================================================================================================

#define DEFINE_USER_ERROR( error, string )
#include "UTErrorCodes.h"


#if __cplusplus


//==================================================================================================
//==================================================================================================
//===
//=== Inline function implementations
//===
//==================================================================================================
//==================================================================================================
inline
Status_t::Status_t()
{
    m_error_code = 0;
    m_explanation = NULL;
}


inline
Status_t::Status_t(error_code_t error_code)
{
    m_error_code = error_code;
    m_explanation = NULL;
}


inline
Status_t::Status_t( error_code_t error_code, const utf8* explanation )
{
    m_error_code = error_code;
    assert(explanation);
    CreateExplanation(explanation);
}


inline
Status_t::Status_t( error_code_t error_code, stringliteral* explanation )
{
    m_error_code = error_code;
    assert(explanation);
    CreateExplanation(explanation);
}


inline
Status_t::Status_t(const Status_t& copy)
{
    m_error_code = copy.m_error_code;
    m_explanation = NULL;
    if(copy.m_explanation)
        AddExplanation(copy.m_explanation);
}


inline
Status_t::~Status_t()
{
    if(m_explanation)
        RemoveExplanation();
}


inline const Status_t&
Status_t::operator =(const Status_t& set)
{
    m_error_code = set.m_error_code;
    if(m_explanation)
        RemoveExplanation();
    if( set.Explanation() )
        AddExplanation(set.m_explanation);
    return *this;
}


inline const Status_t&
Status_t::operator =(error_code_t set)
{
    m_error_code = set;
    if(m_explanation)
        RemoveExplanation();
    return *this;
}


inline bool
Status_t::Success() const
{
    return (m_error_code >= 0);
}


inline bool
Status_t::SuccessAndTrue() const
{
    return (m_error_code > 0);
}


inline bool
Status_t::SuccessAndFalse() const
{
    return (m_error_code == 0);
}


inline error_code_t
Status_t::StatusCode() const
{
    return m_error_code;
}


inline bool
Status_t::operator ==(error_code_t error_code) const
{
    return (m_error_code == error_code);
}


inline bool
Status_t::operator !=(const Status_t& other)
{
    return !(*this == other);
}


inline bool
Status_t::operator !=(error_code_t error_code)
{
    return (m_error_code != error_code);
}


inline bool
Status_t::operator <(int32 value)
{
    return (m_error_code < value);
}


inline bool
Status_t::operator <=(int32 value)
{
    return (m_error_code <= value);
}


inline bool
Status_t::operator >(int32 value)
{
    return (m_error_code > value);
}


inline bool
Status_t::operator >=(int32 value)
{
    return (m_error_code >= value);
}


#if WINDOWS


inline Status_t
Status_t::WinError(int32 windows_error_code)
{
    // GetLastError, winerror.h
    //   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
    //   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    //  +---+-+-+-----------------------+-------------------------------+
    //  |Sev|C|R|     Facility          |               Code            |
    //  +---+-+-+-----------------------+-------------------------------+
    //      Sev - is the severity code
    //          00 - Success
    //          01 - Informational
    //          10 - Warning
    //          11 - Error
    //      C - is the Customer code flag
    //      R - is a reserved bit
    //      Facility - is the facility code
    //      Code - is the facility's status code
    return (windows_error_code | eERR_windows_error_base);
}


inline Status_t
Status_t::WinError( int32 win_error_code, const utf8* explanation )
{
    return Status_t( win_error_code | eERR_windows_error_base, explanation );
}


inline Status_t
Status_t::WinError( int32 win_error_code, stringliteral* explanation )
{
    return Status_t( win_error_code | eERR_windows_error_base, explanation );
}


#endif


inline Status_t
Status_t::POSIXError(int posix_error_code)
{
    // errno, errno.h
    return ( (posix_error_code & 0x0000FFFF) | eERR_posix_error_base );
}


inline Status_t
Status_t::POSIXError( int posix_error_code, const utf8* explanation )
{
    return Status_t( (posix_error_code & 0x0000FFFF) | eERR_posix_error_base, explanation );
}


inline Status_t
Status_t::POSIXError( int posix_error_code, stringliteral* explanation )
{
    return Status_t( (posix_error_code & 0x0000FFFF) | eERR_posix_error_base, explanation );
}


#endif // __cplusplus