/** @file  psLogMsg.h
 *  @brief Procedures for logging messages.
 *  \ingroup LogTrace
 *
 *  This file will hold the prototypes for defining procedure which set
 *  message log levels, messahe log formats, message log destinations, and
 *  for generating the messages themselves.
 *  @ingroup LogTrace
 *
 *  @author Robert Lupton, Princeton University
 *  @author George Gusciora, MHPCC
 *
 *  @version $Revision: 1.19 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2004-10-27 00:57:31 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */
#if !defined(PS_LOG_MSG_H)
#define PS_LOG_MSG_H
#include <stdarg.h>

#include "psType.h"

/** @addtogroup LogTrace
 *  @{
 */

/** This procedure sets the destination for future log messages.  Currently
 *  the destination is specified by an integer which can have the following
 *  pre-defined values: PS_LOG_NONE, PS_LOG_TO_STDOUT, and PS_LOG_TO_STDERR.
 *  In future versions, this procedure will take a character string as an
 *  argument which can specify more general log destinations.
 *
 *  @return psS32     true if set successfully, otherwise false.
 */
psBool psLogSetDestination(
    const char *dest                   ///< Specifies where to send messages.
);

/** This procedure sets the message level for future log messages.  Subsequent
 *  log messages, with a log level of "mylevel", will only be logged if
 *  "mylevel" is less than the current log level set by this procedure.
 *  Ie. higher values set by this procedure will cause more log messages to
 *  be displayed.
 *
 *  @return psS32    old logging level
 */
psS32 psLogSetLevel(
    psS32 level                          ///< Specifies the system log level
);

/** This procedure sets the log format for future log messages.  The argument
 *  must be a character string consistsing of the letters H (host), L
 *  (level), M (message), N (name), and T (time).  The default is "THLNM".
 *  Deleting a letter from the string will cause the associated information
 *  to not be logged.
 *
 */
void psLogSetFormat(
    const char *fmt                    ///< Specifies the system log format
);

/** This procedure logs a message to the destination set by a prior
 *  call to psLogSetDestination(), if myLevel is less than the level
 *  specified by a prior call to psLogSetLevel().  The message is specified
 *  with a printf-stype string an arguments.
 *
 */
void psLogMsg(
    const char *name,                  ///< name of the log source
    psS32 myLevel,                       ///< severity level of this log message
    const char *fmt,                   ///< printf-style format command
    ...
);

/** This procedure is functionally equivalent to psLogMsg(), except that
 *  it takes a va_list as the message parameter, not a printf-style string.
 *
 */
void psLogMsgV(
    const char *name,                  ///< name of the log source
    psS32 myLevel,                       ///< severity level of this log message
    const char *fmt,                   ///< printf-style format command
    va_list ap                         ///< varargs argument list
);

///< Status codes for log messages
enum {
    PS_LOG_ABORT = 0,                  ///< log message is a critical error, perform an abort after printing
    PS_LOG_ERROR,                      ///< log message is an error, but don't abort
    PS_LOG_WARN,                       ///< log message is a warning
    PS_LOG_INFO                        ///< log message is informational only
};

///< Destinations for log messages
enum {
    PS_LOG_NONE,                       ///< turn off logging
    PS_LOG_TO_STDERR,                  ///< log to system's stderr
    PS_LOG_TO_STDOUT                   ///< log to system's stdout
};

/** Logs a warning message.
 *
 *  This procedure logs a message to the destination set by a prior
 *  call to psLogSetDestination(), This is equivalent to calling
 *  psLogMsg with a level of PS_LOG_WARN.
 *
 */
void psWarning(
    const char* name,
    const char* fmt,
    ...
);

/// @}

#endif
