#ifndef _apl_logging_traceapi_h_
#define _apl_logging_traceapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Run-Time Tracing API (TRACE)
**
** DESCRIPTION:
**  This file provides a sprintf based tracing logging facility (a.k.a printf
**  debugging support).  This interface is setup as macros that can be mapped
**  "nulls" at compile time to remove the overhead of the interface for
**  "production" releases.
**
**  USAGE:
**  ------
**  The trace macros have printf semantics.  However, ANSI C/C++ does not
**  directly support "var args" in a macro, so an extra set of '()' is
**  REQUIRED.  See below for example usage:
**
**      void foobar( int x )
**          {
**          int y = 2*x;
**          ....
**          APL_TRACE_OUTLINE( ("x=%d, y=%d", x, y) );
**          ....
**          }
**
**
** CONFIGURATION 
** -------------
**  COMPILE:        USE_APL_ENABLE_TRACE_MACROS
**
**  APPLICATION:    OPTION_APL_TRACE_NEWLINE_STRING
**
**  PLATFORM:       none.
**
**  NOTES:
**  1. Unless explicitly stated, NONE of the following methods may be called
**     from interrtup service routines.
**  2. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as macros.
----------------------------------------------------------------------------*/
                    
#include "apl/logging/trace.h"          /* For: inline implementation */
#include "platform/traceapi.h"          /* For: platform implementation */


#ifdef __cplusplus
extern "C" {
#endif

/*-------------- CONSTANTS -------------------------------------------------*/
/** This symbol defines the newline string to be used when outputing
    trace messages.
 */
#ifndef OPTION_APL_TRACE_NEWLINE_STRING
#define OPTION_APL_TRACE_NEWLINE_STRING    "\n"
#endif


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This macro is use to turn on tracing at RUNTIME.  On start-up, the 
    default is tracing-enabled.
 */
#define APL_TRACE_ON()                      _APL_TRACE_ON()

/** This macro is use to turn off tracing at RUNTIME. 
 */
#define APL_TRACE_OFF()                     _APL_TRACE_OFF()

/** This macro is used to output a trace message WITH a trailing NEWLINE
    character.  It has printf semantics.  See interface description above 
    for example usage.
 */
#define APL_TRACE_OUTLINE( var_args )       _APL_TRACE_OUTLINE( var_args )

/** This macro is used to output a trace message WITHOUT a trailing NEWLINE
    character.  It has printf semantics.  See interface description above 
    for example usage.
 */
#define APL_TRACE_OUT( var_args )           _APL_TRACE_OUT( var_args )

/** This macro is used to output a trace message containing ONLY a 
    NEWLINE character.
 */
#define APL_TRACE_NEWLINE()                 _APL_TRACE_NEWLINE()




/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method is responsible for handling the low-level output of the 
    trace message.  

    Prototype:
        void Apl_traceOutput(const char* format, ....);
 */
#define Apl_traceOutput                     _Apl_traceOutput


#ifdef __cplusplus
}
#endif
/*--------------------------------------------------------------------------*/
#endif  /* end _apl_logging_xslogapi_h_ */