/*
 * _DEBUG.H
 *
 *  Header file for ArchiveLib 1.0
 *
 *  Copyright (c) 1994 Greenleaf Software, Inc.
 *  All Rights Reserved
 *
 * DESCRIPTION
 *
 *  These macros and types are all used in the debug versions of the
 *  ArchiveLib.
 * 
 * MACROS
 *
 *   _ALAssertFailure()
 *   AL_ASSERT()
 *   AL_ASSERT_OBJECT()
 *   AL_CLASS_TAG()
 * 
 * PROTOTYPES:
 *
 *   IsBadWritePtr()
 *
 * ENUMERATED TYPES:
 *
 *   _ALClassTags
 *
 * REVISION HISTORY
 *
 *  May 26, 1994  1.0A  : First release
 *
 */

#ifndef __DEBUG_H
#define __DEBUG_H
/*
 * _ALAssertFailure is the function called by AL_ASSERT() and
 * AL_ASSERT_OBJECT() when their assertion fails.
 */
void AL_CFUNCTION _ALAssertFailure( const char AL_DLL_FAR *condition,
                                    const char AL_DLL_FAR *filename,
                                    int line,
                                    const char AL_DLL_FAR *message,
                                    ... );
#ifdef NDEBUG
/*
 * In the non-debug versions, both of these macros basically go away.
 * The only difficulty is trying to avoid having the compilers generate
 * error messages when they see this code.  Maybe in NDEBUG mode I could
 * change these to inline functions that do nothing?
 */

#define AL_ASSERT( condition, message ) ((void) 0)
#define AL_ASSERT_OBJECT( pointer, class, message ) ((void) 0)

#else
/*
 * In debug mode, AL_ASSERT() tests the condition, and generates
 * an abort with an error message when the condition fails.
 */
#define AL_ASSERT( condition, message )             \
            ( ( condition ) ?                       \
                   (void) 0 :                       \
                   _ALAssertFailure( #condition,    \
                                     __FILE__,      \
                                     __LINE__,      \
                                     message ) )    \
/*
 * I can only call IsBadWritePtr() if TOOLHELP.DLL is available.  As far
 * as I know, it won't be available with any of the DOS Extenders
 * The only way we have access to TOOLHELP.DLL is if we are *really*
 * running under Windows, not some bogus imitation.
 */
#if !defined( AL_WINDOWS_GUI ) 
  #define IsBadWritePtr( p, s ) 0
#endif
/*
 * AL_ASSERT_OBJECT() is a great macro.  It is used to test the 
 * validity of an object.  This is a two step process.  First,
 * we make sure we are dealing with a good pointer.  If not, an
 * asserting error is triggered.  This is much better than the
 * GPF you would normally get from a bad pointer.  Next, we
 * test the GoodTag() macro, which verifies that this is
 * a properly constructed object from the specified class.  Of
 * course, in NDEBUG mode this all goes away.
 *
 */ 
#define AL_ASSERT_OBJECT( pointer, class, message )                    \
    ( pointer == 0 || IsBadWritePtr( pointer, sizeof( class ) ) ) ?    \
        _ALAssertFailure( "IsBadWritePtr()",                           \
                          __FILE__,                                    \
                          __LINE__,                                    \
                          "%s: Bad pointer to object of class %s",     \
                          message,                                     \
                          #class )                                     \
     :                                                                 \
        ( ( (class *)pointer)->GoodTag() ?                             \
            (void) 0                                                   \
    :                                                                  \
            _ALAssertFailure( #pointer "->GoodTag()",                  \
            __FILE__,                                                  \
            __LINE__,                                                  \
            "%s: %s is not an object of class %s",                     \
            message,                                                   \
            #pointer,                                                  \
            #class ) )
#endif
/*
 * The AL_CLASS_TAG() macro assigns a new debug class and data
 * member to each of the classes in ArchiveLib.  Each of these
 * debug classes uses a special integer tag (stored in the data member)
 * to uniquely identify itself.  These are the integer values of
 * these integers.
 */

enum _ALClassTags {
    _ALDeletedObjectTag = 0,
    _ALStorageTag,
    _ALFileTag,
    _ALMemoryTag,
    _ALEntryTag,
    _ALEntryListTag,
    _ALArchiveBaseTag,
    _ALArchiveTag,
    _ALMonitorTag,
    _ALBarGraphTag,
    _ALSpinnerTag,
    _ALWindowsMessageTag,
    _ALCompressionEngineTag,
    _ALCopyEngineTag,
    _ALGreenleafEngineTag,
    _ALCompressedObjectTag,
    _ALNameTag,
    _ALWildCardExpanderTag,
};

/*
 * AL_CLASS_TAG( x ) is a macro that is used to help debug
 * ArchiveLib.  The insertion of this macro in a class definition
 * adds a new data member and member function to the class.  The
 * data member is an object of a class uniquely created by the
 * macro.  The reason the data member is a class object instead
 * of a simple integer or character tag is this: By making it a 
 * class object, we can automatically assign it a valid value
 * when constructed, and an invalid value when destroyed.
 *
 * The member function added to the class is called GoodTag().
 * Once you have added AL_CLASS_TAG( x ) to your class definition,
 * you can call object.GoodTag() anytime you want.  It will return
 * a true value only if the data member has the correct value,
 *
 * We make use of this function in AL_ASSERT_OBJECT().  It
 * checks the value of this object frequently in member functions
 * and destructors, generating an assertion failure if the object
 * doesn't look like the correct type.
 *
 * Note that the ASSERT_OBJECT() statements generate no code when the 
 * library is compiled with NDEBUG, so this class will not be 
 * generating much low overhead.  However, the data member will
 * still be taking up a single byte in each instance.
 *
 * If you want to eliminate class tags, this line in will do it
 * You will save one byte per instance.  The best way to accomplish this
 * is to define the macro in ALCUSTOM.H, then rebuild the library with
 * macro AL_CUSTOM defined in your project.  After you build this new
 * version of the library, you must absolutely, positively, be sure
 * that you continue to use AL_CUSTOM and ALCUSTOM.H when working
 * with the library.  If you don't, your library and your application
 * will think that most classes in ArchiveLib are different sizes, and
 * *nothing* will work.
 *
 *#define AL_CLASS_TAG( x ) int GoodTag(){ return 1; }
 */

#if defined( NDEBUG ) && !defined( AL_CLASS_TAG )
  #define AL_CLASS_TAG( x ) class AL_CLASS_TYPE _ALTag##x {                   \
               public :                                                       \
                   unsigned char mucTagVal;                                   \
              } mMyTag;                                                       \
              int AL_PROTO GoodTag(){ return 1; }
#endif  /* #if defined( NDEBUG ) && !defined( AL_CLASS_TAG ) */

#if !defined( NDEBUG ) && !defined( AL_CLASS_TAG )
  #define AL_CLASS_TAG( x ) class AL_CLASS_TYPE _ALTag##x {                   \
               public :                                                       \
                   AL_PROTO _ALTag##x(){ mucTagVal = x; }                     \
                   AL_PROTO ~_ALTag##x(){ mucTagVal = _ALDeletedObjectTag; }  \
                   unsigned char mucTagVal;                                   \
              } mMyTag;                                                       \
              int AL_PROTO GoodTag(){ return mMyTag.mucTagVal == x; }
#endif /* #if !defined( NDEBUG ) && !defined( AL_CLASS_TAG ) */
#endif /* #ifndef __DEBUG_H      */
