

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
//_/_/
//_/_/  This file is part of CMSDK version 2.1.1.260726 (26 July 2026)
//_/_/  
//_/_/  developed by
//_/_/  
//_/_/  Communicative Machines Ltd. 
//_/_/    http://cmlabs.com/
//_/_/  Copyright (c) 2026
//_/_/  
//_/_/  in collaboration with 
//_/_/  
//_/_/  Icelandic Institute for Intelligent Machines ses
//_/_/    Menntavegur 1
//_/_/    101 Reykjavik
//_/_/    ICELAND
//_/_/    http://www.iiim.is/
//_/_/
//_/_/  and is released under the following
//_/_/  
//_/_/  EXTENDED BSD License
//_/_/
//_/_/  Redistribution and use in source and binary forms, with or without
//_/_/  modification, is permitted provided that the following conditions 
//_/_/  are met:
//_/_/
//_/_/  - Redistributions of source code must retain the above copyright 
//_/_/    and collaboration notice, this list of conditions and the following 
//_/_/    disclaimer.
//_/_/
//_/_/  - Redistributions in binary form must reproduce the above copyright 
//_/_/    notice, this list of conditions and the following disclaimer in the 
//_/_/    documentation and/or other materials provided with the distribution.
//_/_/
//_/_/  - Neither the name of its copyright holders nor the names of its 
//_/_/    contributors may be used to endorse or promote products derived from 
//_/_/    this software without specific prior written permission.
//_/_/
//_/_/  - CADIA Clause: The license granted in and to the software under this 
//_/_/    agreement is a limited-use license. The software may not be used in 
//_/_/    furtherance of: (i) intentionally causing bodily injury or severe 
//_/_/    emotional harm to any person; (ii) invading the personal privacy or 
//_/_/    violating the human rights of any person; or (iii) committing or 
//_/_/    preparing for any act of war. 
//_/_/
//_/_/  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
//_/_/  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
//_/_/  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
//_/_/  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 
//_/_/  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
//_/_/  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
//_/_/  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
//_/_/  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
//_/_/  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
//_/_/  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
//_/_/  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//_/_/
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/*! @file ConsoleOutput.h
	@brief Levelled console logging: verbose, debug and error printf-style output with per-subject filtering.

	This header defines the CMSDK-wide console logging facility used by every
	subsystem (networking, nodes, processes, components). Output is split into
	three severities — verbose, debug and error — and further partitioned into
	five @e subjects (CONSOLE_SYSTEM .. CONSOLE_COMPONENT) so that, for
	example, network tracing can be turned up without flooding the console
	with component chatter. Each subject carries an independent numeric level;
	a message is printed only when its level is less than or equal to the
	currently configured level for its subject.

	The level tables (::VerboseLevel, ::DebugLevel, ::ErrorLevel) are defined
	@c static in this header, meaning each translation unit that includes it
	gets its own copy; the Set*Level() functions defined in ConsoleOutput.cpp
	operate on the copies visible in that translation unit. Levels are
	typically driven from a system specification (see the
	@c verbose-system / @c debug-network etc. names in ::VerboseSubjects and
	::DebugSubjects, which match spec attribute names).

	@ingroup Networking
*/
#if !defined(_CONSOLEOUTPUT_H_)
#define _CONSOLEOUTPUT_H_

#include <memory.h>
#include <stdio.h>
#include <stdarg.h>

namespace	cmlabs{

/*! @name Console subjects
	Subject identifiers used as the first argument to PrintVerbose() and
	PrintDebug(). They partition log output by architectural layer.
	@{ */
#define CONSOLE_SYSTEM		1	/*!< System-wide events (startup, shutdown, configuration). */
#define CONSOLE_NETWORK		2	/*!< Networking layer (sockets, protocols, connections). */
#define CONSOLE_NODE		3	/*!< Node-level events in a distributed system. */
#define CONSOLE_PROCESS		4	/*!< OS process management events. */
#define CONSOLE_COMPONENT	5	/*!< Individual component/module events. */
#define CONSOLE_COUNT		5	/*!< Number of defined subjects (array sizes below). */
/*! @} */

/*! Spec attribute names for per-subject verbose levels, indexed by subject-1. */
static const char *VerboseSubjects[] = { "verbose-system", "verbose-network", "verbose-node", "verbose-process", "verbose-component" };
/*! Spec attribute names for per-subject debug levels, indexed by subject-1. */
static const char *DebugSubjects[] = { "debug-system", "debug-network", "debug-node", "debug-process", "debug-component" };
/*! Current verbose level per subject (index = subject-1). Default 1 (basic verbosity on). Per-translation-unit copy. */
static unsigned char VerboseLevel[5] = {1,1,1,1,1};
/*! Current debug level per subject (index = subject-1). Default 0 (debug output off). Per-translation-unit copy. */
static unsigned char DebugLevel[5] =   {0,0,0,0,0};
/*! Current error level threshold. Default 1 (errors printed). Per-translation-unit copy. */
static unsigned char ErrorLevel = 1;

/*! Set the debug level for all subjects at once.
	@param level New debug level; messages with a level <= this value are printed. 0 disables debug output.
	@return true always. */
bool SetDebugLevel(unsigned char level);
/*! Set the debug level for a single subject.
	@param subject One of the CONSOLE_* subject ids (1..CONSOLE_COUNT).
	@param level New debug level for that subject.
	@return true on success, false if @p subject is out of range. */
bool SetDebugLevel(unsigned char subject, unsigned char level);
/*! Set the verbose level for all subjects at once.
	@param level New verbose level; 0 silences verbose output.
	@return true always. */
bool SetVerboseLevel(unsigned char level);
/*! Set the verbose level for a single subject.
	@param subject One of the CONSOLE_* subject ids (1..CONSOLE_COUNT).
	@param level New verbose level for that subject.
	@return true on success, false if @p subject is out of range. */
bool SetVerboseLevel(unsigned char subject, unsigned char level);
/*! Set the global error output level.
	@param level New error level threshold; 0 silences error output.
	@return true always. */
bool SetErrorLevel(unsigned char level);

/*! Print a printf-style formatted string to an arbitrary stdio stream.
	@param stream Destination stream (e.g. stdout, stderr or an open file).
	@param formatstring printf format followed by variadic arguments.
	@return true on success, false if @p stream or @p formatstring is NULL.
	@note Not gated by any level; always prints. Thread-safety is that of the
	underlying stdio stream (individual fprintf calls are atomic on most
	platforms, but interleaving between calls can occur). */
bool PrintFile(FILE* stream, const char *formatstring, ... );
/*! Print a verbose (informational) message if enabled for the subject.
	@param subject One of the CONSOLE_* subject ids.
	@param level Importance of this message; printed when <= the subject's verbose level.
	@param formatstring printf format followed by variadic arguments.
	@return true if the message was printed, false if filtered out or invalid. */
bool PrintVerbose(unsigned char subject, unsigned char level, const char *formatstring, ... );
/*! Print an error message if enabled.
	@param level Importance of this error; printed when <= ::ErrorLevel.
	@param formatstring printf format followed by variadic arguments.
	@return true if the message was printed, false if filtered out or invalid. */
bool PrintError(unsigned char level, const char *formatstring, ... );
/*! Print a debug message if enabled for the subject.
	@param subject One of the CONSOLE_* subject ids.
	@param level Importance of this message; printed when <= the subject's debug level.
	@param formatstring printf format followed by variadic arguments.
	@return true if the message was printed, false if filtered out or invalid. */
bool PrintDebug(unsigned char subject, unsigned char level, const char *formatstring, ... );

}

#endif //_CONSOLEOUTPUT_H_

