xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | Protected Member Functions | List of all members
xtd::diagnostics::trace_listener Class Referenceabstract

#include <trace_listener.h>

Definition

Provides the abstract base class for the listeners who monitor trace and debug output.

Namespace
xtd::diagnostics
Library
xtd.core
Remarks
For examples of how to implement a trace_listener, see the default_trace_listener, text_writer_trace_listener and the event_log_trace_listener classes.
You must enable tracing or debugging to use a trace listener. The syntax is compiler specific. If you use other than cmake to manage your build, refer to the documentation of your build nanager.
  • To enable debugging with cmake, add the add_definitions(-DDEBUG) command line in the CMakeLists.txt of your porject, or you can add #define DEBUG to the top of your file but in this case, the compiler options for debug is not activated.
  • To enable tracing with cmake, add the add_definitions(-DTRACE) command line in the CMakeLists.txt of your porject, or you can add #define TRACE to the top of your file.
Note
to Inheritors: Inherit from this class to implement a custom listener for the debug and trace classes. At a minimum, you must implement the write and write_line methods. Additionally, you can implement the fail, close and flush methods.

Public Member Functions

 trace_listener ()=default
 Initializes a new instance of the trace_listener class. More...
 
 trace_listener (const xtd::ustring &name)
 Initializes a new instance of the trace_listener class using the specified name as the listener. More...
 
virtual void close ()
 When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output. More...
 
virtual void fail (const xtd::ustring &message)
 Emits an error message to the listener you create when you implement the TraceListener class. More...
 
virtual void fail (const xtd::ustring &message, const xtd::ustring &detail_message)
 Emits the specified error message. More...
 
virtual void flush ()
 When overridden in a derived class, flushes the output buffer. More...
 
unsigned int indent_level () const
 Gets the indent level. More...
 
void indent_level (unsigned int indent_level)
 Sets the indent level. More...
 
unsigned int indent_size () const
 Gets the number of spaces in an indent. More...
 
void indent_size (unsigned int indent_size)
 Sets the number of spaces in an indent. More...
 
virtual bool is_thread_safe () const
 Gets a value indicating whether the trace listener is thread safe. More...
 
const xtd::ustringname () const
 Gets or sets a name for this TraceListener. More...
 
void name (const xtd::ustring &name)
 Sets a name for this TraceListener. More...
 
template<typename object >
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const object &data)
 Writes trace information, a data object and event information to the listener specific output. More...
 
template<typename object >
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const std::vector< object > &data)
 Writes trace information, a data object and event information to the listener specific output. More...
 
template<typename ... objects>
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const objects &... data)
 Writes trace information, an array of data objects and event information to the listener specific output. More...
 
virtual void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id)
 Writes trace and event information to the listener specific output. More...
 
virtual void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const xtd::ustring &message)
 Writes trace information, a message, and event information to the listener specific output. More...
 
template<typename ... objects>
void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const xtd::ustring &format, const objects &... args)
 Writes trace information, a formatted array of objects and event information to the listener specific output. More...
 
const trace_optionstrace_output_options () const
 Gets the trace output options. More...
 
void trace_output_options (const trace_options &trace_output_options)
 Sets the trace output options. More...
 
template<typename activity_id_type >
void trace_transfer (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, int id, const xtd::ustring &message, const activity_id_type &related_activity_id)
 Writes trace information, a message, a related activity identity and event information to the listener specific output. More...
 
template<typename object >
void write (const object &o)
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
template<typename object >
void write (const object &o, const xtd::ustring &category)
 Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
virtual void write (const xtd::ustring &message)=0
 Writes the message to the listener you create when you implement the trace_listener class. More...
 
template<typename object >
void write_line (const object &o)
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
template<typename object >
void write_line (const object &o, const xtd::ustring &category)
 Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
virtual void write_line (const xtd::ustring &message)=0
 Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Protected Member Functions

bool need_indent () const
 Gets a value indicating whether to indent the output. More...
 
void need_indent (bool need_indent)
 Sets a value indicating whether to indent the output. More...
 
void thread_safe (bool thread_safe)
 Sets a value indicating whether the trace listener is thread safe. More...
 
virtual void write_indent ()
 Writes the indent to the listener you create when you implement this class, and resets the NeedIndent property to false. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are considered equal. More...
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance. More...
 

Constructor & Destructor Documentation

◆ trace_listener() [1/2]

xtd::diagnostics::trace_listener::trace_listener ( )
default

Initializes a new instance of the trace_listener class.

Remarks
The following table shows initial property values for an instance of trace_listener.
Property Default Value
name  The empty string ("").
indent_level Zero.
indent_size Four spaces.

◆ trace_listener() [2/2]

xtd::diagnostics::trace_listener::trace_listener ( const xtd::ustring name)
explicit

Initializes a new instance of the trace_listener class using the specified name as the listener.

Parameters
nameThe name of the trace_listener.

Member Function Documentation

◆ close()

virtual void xtd::diagnostics::trace_listener::close ( )
virtual

When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.

Remarks
Use this method when the output is going to a file, such as to the TextWriterTraceListener. After a call to this method, you must reinitialize the object.

Reimplemented in xtd::diagnostics::default_trace_listener, xtd::forms::control_trace_listener, and xtd::diagnostics::ostream_trace_listener.

◆ fail() [1/2]

virtual void xtd::diagnostics::trace_listener::fail ( const xtd::ustring message)
inlinevirtual

Emits an error message to the listener you create when you implement the TraceListener class.

Parameters
messageA message to emit.
Remarks
The default behavior is to display the specified message in a message box when the application is running in a user-interface mode, and to the TraceListener instances in a TraceListenerCollection collection. By default, the TraceListenerCollection collection has an instance of a DefaultTraceListener. You can customize this behavior by adding a TraceListener to or removing one from the collection.

◆ fail() [2/2]

virtual void xtd::diagnostics::trace_listener::fail ( const xtd::ustring message,
const xtd::ustring detail_message 
)
inlinevirtual

Emits the specified error message.

Parameters
messageA message to emit.
detailMessageA detailed message to emit.
Remarks
The default behavior is to display the message and detailed message in a message box when the application is running in a user-interface mode, and to the TraceListener instances in a TraceListenerCollection collection. By default, the TraceListenerCollection collection has an instance of a DefaultTraceListener. You can customize this behavior by adding a TraceListener to or removing one from the collection.

◆ flush()

virtual void xtd::diagnostics::trace_listener::flush ( )
inlinevirtual

When overridden in a derived class, flushes the output buffer.

Reimplemented in xtd::diagnostics::default_trace_listener, xtd::forms::control_trace_listener, and xtd::diagnostics::ostream_trace_listener.

◆ indent_level() [1/2]

unsigned int xtd::diagnostics::trace_listener::indent_level ( ) const

Gets the indent level.

Returns
unsigned int The indent level. The default is zero.
Remarks
The IndentLevel property represents the number of times that the indent specified by the IndentSize property is applied. This property is stored on per-thread/per-request basis.

◆ indent_level() [2/2]

void xtd::diagnostics::trace_listener::indent_level ( unsigned int  indent_level)

Sets the indent level.

Parameters
indent_levelThe indent level. The default is zero.
Remarks
The IndentLevel property represents the number of times that the indent specified by the IndentSize property is applied. This property is stored on per-thread/per-request basis.

◆ indent_size() [1/2]

unsigned int xtd::diagnostics::trace_listener::indent_size ( ) const

Gets the number of spaces in an indent.

Returns
unsigned int The number of spaces in an indent. The default is four spaces.
Remarks
The property is stored on per-thread/per-request basis.

◆ indent_size() [2/2]

void xtd::diagnostics::trace_listener::indent_size ( unsigned int  indent_size)

Sets the number of spaces in an indent.

Parameters
int32The number of spaces in an indent. The default is four spaces.
Remarks
The property is stored on per-thread/per-request basis.

◆ is_thread_safe()

virtual bool xtd::diagnostics::trace_listener::is_thread_safe ( ) const
virtual

Gets a value indicating whether the trace listener is thread safe.

Returns
bool true if the trace listener is thread safe; otherwise, false. The default is false.
Remarks
The value of IsThreadSafe is used to determine whether to use a global lock when writing to the listener. If the value of IsThreadSafe is false, the global lock is used regardless of the value of UseGlobalLock. The global lock is not used only if the value of IsThreadSafe is true and the value of UseGlobalLock is false. The default behavior is to use the global lock whenever writing to the listener.

◆ name() [1/2]

const xtd::ustring& xtd::diagnostics::trace_listener::name ( ) const

Gets or sets a name for this TraceListener.

Returns
string A name for this TraceListener. The default is an empty string ("").
Remarks
The name can be used to organize and access listeners in a TraceListenerCollection collection.

◆ name() [2/2]

void xtd::diagnostics::trace_listener::name ( const xtd::ustring name)

Sets a name for this TraceListener.

Parameters
nameA name for this TraceListener. The default is an empty string ("").
Remarks
The name can be used to organize and access listeners in a TraceListenerCollection collection.

◆ need_indent() [1/2]

bool xtd::diagnostics::trace_listener::need_indent ( ) const
protected

Gets a value indicating whether to indent the output.

Returns
true if the output should be indented; otherwise, false.

◆ need_indent() [2/2]

void xtd::diagnostics::trace_listener::need_indent ( bool  need_indent)
protected

Sets a value indicating whether to indent the output.

Parameters
need_indenttrue if the output should be indented; otherwise, false.

◆ thread_safe()

void xtd::diagnostics::trace_listener::thread_safe ( bool  thread_safe)
protected

Sets a value indicating whether the trace listener is thread safe.

Parameters
thread_safetrue if the trace listener is thread safe; otherwise, false. The default is false.

◆ trace_data() [1/3]

template<typename object >
void xtd::diagnostics::trace_listener::trace_data ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id,
const object data 
)
inline

Writes trace information, a data object and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataThe trace data to emit.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_data() [2/3]

template<typename object >
void xtd::diagnostics::trace_listener::trace_data ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id,
const std::vector< object > &  data 
)
inline

Writes trace information, a data object and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataThe trace data to emit.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_data() [3/3]

template<typename ... objects>
void xtd::diagnostics::trace_listener::trace_data ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id,
const objects &...  data 
)
inline

Writes trace information, an array of data objects and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataAn array of objects to emit as data.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_event() [1/3]

virtual void xtd::diagnostics::trace_listener::trace_event ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id 
)
inlinevirtual

Writes trace and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the values of the source, eventType and id parameters as a header. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_event() [2/3]

virtual void xtd::diagnostics::trace_listener::trace_event ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id,
const xtd::ustring message 
)
inlinevirtual

Writes trace information, a message, and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
messageA message to write.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the values of the source, eventType and id parameters as a header. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_event() [3/3]

template<typename ... objects>
void xtd::diagnostics::trace_listener::trace_event ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
const xtd::diagnostics::trace_event_type event_type,
int  id,
const xtd::ustring format,
const objects &...  args 
)
inline

Writes trace information, a formatted array of objects and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
formatA format string that contains zero or more format items, which correspond to objects in the args array.
argsAn object array containing zero or more objects to format.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The default implementation writes the values of the source, eventType and id parameters as a header. The args object array is converted to a string using the Format method, passing the format string and args array to format the string as the message portion of the trace. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_output_options() [1/2]

const trace_options& xtd::diagnostics::trace_listener::trace_output_options ( ) const

Gets the trace output options.

Returns
trace_options A bitwise combination of the enumeration values. The default is None.
Remarks
The TraceOutputOptions property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the TraceOutputOptions property for the console trace listener to TraceOptions.Callstack to add call stack information to the trace output.
The TraceOptions enumeration is not used by the following classes and methods:
  • The EventLogTraceListener class, because it can cause a large volume of data to be written to the log.
  • The Write and WriteLine methods of the ConsoleTraceListener, DefaultTraceListener, and TextWriterTraceListener classes.
  • The Write and WriteLine methods of the TraceListener class when they are not overridden in a derived class.

◆ trace_output_options() [2/2]

void xtd::diagnostics::trace_listener::trace_output_options ( const trace_options trace_output_options)

Sets the trace output options.

Parameters
trace_output_optionsA bitwise combination of the enumeration values. The default is None.
Remarks
The TraceOutputOptions property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the TraceOutputOptions property for the console trace listener to TraceOptions.Callstack to add call stack information to the trace output.
The TraceOptions enumeration is not used by the following classes and methods:
  • The EventLogTraceListener class, because it can cause a large volume of data to be written to the log.
  • The Write and WriteLine methods of the ConsoleTraceListener, DefaultTraceListener, and TextWriterTraceListener classes.
  • The Write and WriteLine methods of the TraceListener class when they are not overridden in a derived class.

◆ trace_transfer()

template<typename activity_id_type >
void xtd::diagnostics::trace_listener::trace_transfer ( const xtd::diagnostics::trace_event_cache event_cache,
const xtd::ustring source,
int  id,
const xtd::ustring message,
const activity_id_type &  related_activity_id 
)
inline

Writes trace information, a message, a related activity identity and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
idA numeric identifier for the event.
messageA message to write.
relatedActivityIdA Guid object identifying a related activity.
Remarks
Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.
The TraceTransfer method is used for the correlation of related traces. The TraceTransfer method calls the TraceEvent method to process the call, with the eventType level set to Transfer and the relatedActivityIdGuid as a string appended to the message.
activity_id_type is generaly a guid.

◆ write() [1/3]

template<typename object >
void xtd::diagnostics::trace_listener::write ( const object o)
inline

Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.

Parameters
oAn Object whose fully qualified class name you want to write.

◆ write() [2/3]

template<typename object >
void xtd::diagnostics::trace_listener::write ( const object o,
const xtd::ustring category 
)
inline

Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class.

Parameters
oAn Object whose fully qualified class name you want to write.
categoryA category name used to organize the output.

◆ write() [3/3]

virtual void xtd::diagnostics::trace_listener::write ( const xtd::ustring message)
pure virtual

Writes the message to the listener you create when you implement the trace_listener class.

Parameters
messageA string you want to write.

Implemented in xtd::diagnostics::default_trace_listener, xtd::forms::control_trace_listener, and xtd::diagnostics::ostream_trace_listener.

◆ write_indent()

virtual void xtd::diagnostics::trace_listener::write_indent ( )
inlineprotectedvirtual

Writes the indent to the listener you create when you implement this class, and resets the NeedIndent property to false.

Remarks
This method writes the indent and resets the NeedIndent property to false. Call this method if NeedIndent is true when you are overriding the Write and WriteLine methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the IndentSize and IndentLevel properties. The IndentLevel property represents the number of times the indent of the size specified by the IndentSize property is applied. This method is called by the DefaultTraceListener and TextWriterTraceListener classes.

◆ write_line() [1/3]

template<typename object >
void xtd::diagnostics::trace_listener::write_line ( const object o)
inline

Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.

Parameters
oAn Object whose fully qualified class name you want to write.

◆ write_line() [2/3]

template<typename object >
void xtd::diagnostics::trace_listener::write_line ( const object o,
const xtd::ustring category 
)
inline

Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class.

Parameters
oAn Object whose fully qualified class name you want to write.
categoryA category name used to organize the output.

◆ write_line() [3/3]

virtual void xtd::diagnostics::trace_listener::write_line ( const xtd::ustring message)
pure virtual

Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator.

Parameters
messageA string you want to write.

Implemented in xtd::diagnostics::default_trace_listener, xtd::forms::control_trace_listener, and xtd::diagnostics::ostream_trace_listener.


The documentation for this class was generated from the following file: