2 * Copyright Andrey Semashev 2007 - 2015.
3 * Distributed under the Boost Software License, Version 1.0.
4 * (See accompanying file LICENSE_1_0.txt or copy at
5 * http://www.boost.org/LICENSE_1_0.txt)
8 * \file event_log_backend.hpp
9 * \author Andrey Semashev
12 * The header contains a logging sink backend that uses Windows NT event log API
13 * for signaling application events.
16 #ifndef BOOST_LOG_SINKS_EVENT_LOG_BACKEND_HPP_INCLUDED_
17 #define BOOST_LOG_SINKS_EVENT_LOG_BACKEND_HPP_INCLUDED_
19 #include <boost/log/detail/config.hpp>
21 #ifdef BOOST_HAS_PRAGMA_ONCE
25 #ifndef BOOST_LOG_WITHOUT_EVENT_LOG
31 #include <boost/filesystem/path.hpp>
32 #include <boost/log/detail/light_function.hpp>
33 #include <boost/log/detail/parameter_tools.hpp>
34 #include <boost/log/attributes/attribute_value_set.hpp>
35 #include <boost/log/keywords/message_file.hpp>
36 #include <boost/log/keywords/log_name.hpp>
37 #include <boost/log/keywords/log_source.hpp>
38 #include <boost/log/keywords/registration.hpp>
39 #include <boost/log/keywords/target.hpp>
40 #include <boost/log/sinks/basic_sink_backend.hpp>
41 #include <boost/log/sinks/frontend_requirements.hpp>
42 #include <boost/log/sinks/attribute_mapping.hpp>
43 #include <boost/log/sinks/event_log_constants.hpp>
44 #include <boost/log/core/record_view.hpp>
45 #include <boost/log/expressions/formatter.hpp>
46 #include <boost/log/detail/header.hpp>
50 BOOST_LOG_OPEN_NAMESPACE
56 //! Event log source registration modes
57 enum registration_mode
59 never, //!< Never register event source, even if it's not registered
60 on_demand, //!< Register if the source is not registered yet
61 forced //!< Register always, event if the source is already registered
65 * \brief Straightforward event type mapping
67 * This type of mapping assumes that attribute with a particular name always
68 * provides values that map directly onto the native event types. The mapping
69 * simply returns the extracted attribute value converted to the native event type.
71 template< typename AttributeValueT = int >
72 class direct_event_type_mapping :
73 public basic_direct_mapping< event_type, AttributeValueT >
76 typedef basic_direct_mapping< event_type, AttributeValueT > base_type;
82 * \param name Attribute name
84 explicit direct_event_type_mapping(attribute_name const& name) :
91 * \brief Customizable event type mapping
93 * The class allows to setup a custom mapping between an attribute and native event types.
94 * The mapping should be initialized similarly to the standard \c map container, by using
95 * indexing operator and assignment.
97 template< typename AttributeValueT = int >
98 class custom_event_type_mapping :
99 public basic_custom_mapping< event_type, AttributeValueT >
102 typedef basic_custom_mapping< event_type, AttributeValueT > base_type;
108 * \param name Attribute name
110 explicit custom_event_type_mapping(attribute_name const& name) :
111 base_type(name, info)
117 * \brief Straightforward event ID mapping
119 * This type of mapping assumes that attribute with a particular name always
120 * provides values that map directly onto the event identifiers. The mapping
121 * simply returns the extracted attribute value converted to the event ID.
123 template< typename AttributeValueT = int >
124 class direct_event_id_mapping :
125 public basic_direct_mapping< event_id, AttributeValueT >
128 typedef basic_direct_mapping< event_id, AttributeValueT > base_type;
134 * \param name Attribute name
136 explicit direct_event_id_mapping(attribute_name const& name) :
137 base_type(name, make_event_id(0))
143 * \brief Customizable event ID mapping
145 * The class allows to setup a custom mapping between an attribute and event identifiers.
146 * The mapping should be initialized similarly to the standard \c map container, by using
147 * indexing operator and assignment.
149 template< typename AttributeValueT = int >
150 class custom_event_id_mapping :
151 public basic_custom_mapping< event_id, AttributeValueT >
154 typedef basic_custom_mapping< event_id, AttributeValueT > base_type;
160 * \param name Attribute name
162 explicit custom_event_id_mapping(attribute_name const& name) :
163 base_type(name, make_event_id(0))
169 * \brief Straightforward event category mapping
171 * This type of mapping assumes that attribute with a particular name always
172 * provides values that map directly onto the event categories. The mapping
173 * simply returns the extracted attribute value converted to the event category.
175 template< typename AttributeValueT = int >
176 class direct_event_category_mapping :
177 public basic_direct_mapping< event_category, AttributeValueT >
180 typedef basic_direct_mapping< event_category, AttributeValueT > base_type;
186 * \param name Attribute name
188 explicit direct_event_category_mapping(attribute_name const& name) :
189 base_type(name, make_event_category(0))
195 * \brief Customizable event category mapping
197 * The class allows to setup a custom mapping between an attribute and event categories.
198 * The mapping should be initialized similarly to the standard \c map container, by using
199 * indexing operator and assignment.
201 template< typename AttributeValueT = int >
202 class custom_event_category_mapping :
203 public basic_custom_mapping< event_category, AttributeValueT >
206 typedef basic_custom_mapping< event_category, AttributeValueT > base_type;
212 * \param name Attribute name
214 explicit custom_event_category_mapping(attribute_name const& name) :
215 base_type(name, make_event_category(0))
221 * \brief An event composer
223 * This class is a function object that extracts event identifier from the attribute values set
224 * and formats insertion strings for the particular event. Each insertion string is formatted with
225 * a distinct formatter, which can be created just like regular sinks formatters.
227 * Before using, the composer must be initialized with the following information:
228 * \li Event identifier extraction logic. One can use \c basic_direct_event_id_mapping or
229 * \c basic_custom_event_id_mapping classes in order to create such extractor and pass it
230 * to the composer constructor.
231 * \li Event identifiers and insertion string formatters. The composer provides the following
232 * syntax to provide this information:
235 * event_composer comp;
236 * comp[MY_EVENT_ID1] % formatter1 % ... % formatterN;
237 * comp[MY_EVENT_ID2] % formatter1 % ... % formatterN;
241 * The event identifiers in square brackets are provided by the message compiler generated
242 * header (the actual names are specified in the .mc file). The formatters represent
243 * the insertion strings that will be used to replace placeholders in event messages,
244 * thus the number and the order of the formatters must correspond to the message definition.
246 template< typename CharT >
247 class BOOST_LOG_API basic_event_composer
251 typedef CharT char_type;
252 //! String type to be used as a message text holder
253 typedef std::basic_string< char_type > string_type;
255 //! Event identifier mapper type
256 typedef boost::log::aux::light_function< event_id (record_view const&) > event_id_mapper_type;
258 //! Type of an insertion composer (a formatter)
259 typedef basic_formatter< char_type > formatter_type;
260 //! Type of the composed insertions list
261 typedef std::vector< string_type > insertion_list;
266 //! The class that implements formatting of insertion strings
267 class insertion_composer;
269 //! Type of the events map
270 typedef std::map< event_id, insertion_composer > event_map;
272 //! A smart reference that puts formatters into the composer
273 class event_map_reference;
274 friend class event_map_reference;
275 class event_map_reference
280 //! A reference to the object that created the reference
281 basic_event_composer< char_type >& m_Owner;
282 //! A hint for the owner to optimize insertion
283 insertion_composer* m_Composer;
286 //! Initializing constructor
287 explicit event_map_reference(event_id id, basic_event_composer< char_type >& owner) :
293 //! The operator puts the formatter into the composer
294 template< typename FormatterT >
295 event_map_reference& operator% (FormatterT const& fmt)
297 m_Composer = m_Owner.add_formatter(m_ID, m_Composer, formatter_type(fmt));
305 //! The mapper that will extract the event identifier
306 event_id_mapper_type m_EventIDMapper;
307 //! The map of event identifiers and their insertion composers
308 event_map m_EventMap;
312 * Default constructor. Creates an empty map of events.
314 * \param id_mapper An event identifier mapping function that will be used to extract event ID from attribute values
316 explicit basic_event_composer(event_id_mapper_type const& id_mapper);
318 * Copy constructor. Performs a deep copy of the object.
320 basic_event_composer(basic_event_composer const& that);
324 ~basic_event_composer();
327 * Assignment. Provides strong exception guarantee.
329 basic_event_composer& operator= (basic_event_composer that);
331 * Swaps \c *this and \c that objects.
333 void swap(basic_event_composer& that);
335 * Initiates creation of a new event description. The result of the operator can be used to
336 * add formatters for insertion strings construction. The returned reference type is implementation detail.
338 * \param id Event identifier.
340 event_map_reference operator[] (event_id id);
342 * Initiates creation of a new event description. The result of the operator can be used to
343 * add formatters for insertion strings construction. The returned reference type is implementation detail.
345 * \param id Event identifier.
347 event_map_reference operator[] (int id);
349 * Event composition operator. Extracts an event identifier from the attribute values by calling event ID mapper.
350 * Then runs all formatters that were registered for the event with the extracted ID. The results of formatting
351 * are returned in the \a insertions parameter.
353 * \param rec Log record view
354 * \param insertions A sequence of formatted insertion strings
355 * \return An event identifier that was extracted from \c attributes
357 event_id operator() (record_view const& rec, insertion_list& insertions) const;
360 #ifndef BOOST_LOG_DOXYGEN_PASS
361 //! Adds a formatter to the insertion composers list
362 insertion_composer* add_formatter(event_id id, insertion_composer* composer, formatter_type const& fmt);
363 #endif // BOOST_LOG_DOXYGEN_PASS
366 #ifdef BOOST_LOG_USE_CHAR
367 typedef basic_event_composer< char > event_composer; //!< Convenience typedef for narrow-character logging
369 #ifdef BOOST_LOG_USE_WCHAR_T
370 typedef basic_event_composer< wchar_t > wevent_composer; //!< Convenience typedef for wide-character logging
373 } // namespace event_log
376 * \brief An implementation of a simple logging sink backend that emits events into Windows NT event log
378 * The sink uses Windows NT 5 (Windows 2000) and later event log API to emit events
379 * to an event log. The sink acts as an event source in terms of the API, it implements all needed resources
380 * and source registration in the Windows registry that is needed for the event delivery.
382 * The backend performs message text formatting. The composed text is then passed as the first
383 * and only string parameter of the event. The resource embedded into the backend describes the event
384 * so that the parameter is inserted into the event description text, thus making it visible
387 * The backend allows to customize mapping of application severity levels to the native Windows event types.
388 * This allows to write portable code even if OS-specific sinks, such as this one, are used.
390 * \note Since the backend registers itself into Windows registry as the resource file that contains
391 * event description, it is important to keep the library binary in a stable place of the filesystem.
392 * Otherwise Windows might not be able to load event resources from the library and display
395 * \note It is known that Windows is not able to find event resources in the application executable,
396 * which is linked against the static build of the library. Users are advised to use dynamic
397 * builds of the library to solve this problem.
399 template< typename CharT >
400 class basic_simple_event_log_backend :
401 public basic_formatted_sink_backend< CharT, concurrent_feeding >
404 typedef basic_formatted_sink_backend< CharT, concurrent_feeding > base_type;
405 //! Implementation type
406 struct implementation;
410 typedef typename base_type::char_type char_type;
411 //! String type to be used as a message text holder
412 typedef typename base_type::string_type string_type;
414 //! Mapper type for the event type
415 typedef boost::log::aux::light_function< event_log::event_type (record_view const&) > event_type_mapper_type;
418 //! Pointer to the backend implementation that hides various types from windows.h
419 implementation* m_pImpl;
423 * Default constructor. Registers event source with name based on the application
424 * executable file name in the Application log. If such a registration is already
425 * present, it is not overridden.
427 BOOST_LOG_API basic_simple_event_log_backend();
429 * Constructor. Registers event log source with the specified parameters.
430 * The following named parameters are supported:
432 * \li \c target - Specifies an UNC path to the remote server which log records should be sent to.
433 * The local machine will be used to process log records, if not specified.
434 * \li \c log_name - Specifies the log in which the source should be registered.
435 * The result of \c get_default_log_name is used, if the parameter is not specified.
436 * \li \c log_source - Specifies the source name. The result of \c get_default_source_name
437 * is used, if the parameter is not specified.
438 * \li \c registration - Specifies the event source registration mode in the Windows registry.
439 * Can have values of the \c registration_mode enum. Default value: \c on_demand.
441 * \param args A set of named parameters.
443 #ifndef BOOST_LOG_DOXYGEN_PASS
444 BOOST_LOG_PARAMETRIZED_CONSTRUCTORS_CALL(basic_simple_event_log_backend, construct)
446 template< typename... ArgsT >
447 explicit basic_simple_event_log_backend(ArgsT... const& args);
451 * Destructor. Unregisters event source. The log source description is not removed from the Windows registry.
453 BOOST_LOG_API ~basic_simple_event_log_backend();
456 * The method installs the function object that maps application severity levels to WinAPI event types
458 BOOST_LOG_API void set_event_type_mapper(event_type_mapper_type const& mapper);
461 * \returns Default log name: Application
463 BOOST_LOG_API static string_type get_default_log_name();
465 * \returns Default log source name that is based on the application executable file name and the sink name
467 BOOST_LOG_API static string_type get_default_source_name();
470 * The method puts the formatted message to the event log
472 BOOST_LOG_API void consume(record_view const& rec, string_type const& formatted_message);
475 #ifndef BOOST_LOG_DOXYGEN_PASS
476 //! Constructs backend implementation
477 template< typename ArgsT >
478 void construct(ArgsT const& args)
481 args[keywords::target | string_type()],
482 args[keywords::log_name || &basic_simple_event_log_backend::get_default_log_name],
483 args[keywords::log_source || &basic_simple_event_log_backend::get_default_source_name],
484 args[keywords::registration | event_log::on_demand]);
486 BOOST_LOG_API void construct(
487 string_type const& target,
488 string_type const& log_name,
489 string_type const& source_name,
490 event_log::registration_mode reg_mode);
491 #endif // BOOST_LOG_DOXYGEN_PASS
495 * \brief An implementation of a logging sink backend that emits events into Windows NT event log
497 * The sink uses Windows NT 5 (Windows 2000) and later event log API to emit events
498 * to an event log. The sink acts as an event source. Unlike \c basic_simple_event_log_backend,
499 * this sink backend allows users to specify the custom event message file and supports
500 * mapping attribute values onto several insertion strings. Although it requires considerably
501 * more scaffolding than the simple backend, this allows to support localizable event descriptions.
503 * Besides the file name of the module with event resources, the backend provides the following
505 * \li Remote server UNC address, log name and source name. These parameters have similar meaning
506 * to \c basic_simple_event_log_backend.
507 * \li Event type and category mappings. These are function object that allow to map attribute
508 * values to the according event parameters. One can use mappings in the \c event_log namespace.
509 * \li Event composer. This function object extracts event identifier and formats string insertions,
510 * that will be used by the API to compose the final event message text.
512 template< typename CharT >
513 class basic_event_log_backend :
514 public basic_sink_backend< synchronized_feeding >
517 typedef basic_sink_backend< synchronized_feeding > base_type;
518 //! Implementation type
519 struct implementation;
523 typedef CharT char_type;
525 typedef std::basic_string< char_type > string_type;
526 //! Type of the composed insertions list
527 typedef std::vector< string_type > insertion_list;
529 //! Mapper type for the event type
530 typedef boost::log::aux::light_function< event_log::event_type (record_view const&) > event_type_mapper_type;
531 //! Mapper type for the event category
532 typedef boost::log::aux::light_function< event_log::event_category (record_view const&) > event_category_mapper_type;
533 //! Event composer type
534 typedef boost::log::aux::light_function< event_log::event_id (record_view const&, insertion_list&) > event_composer_type;
537 //! Pointer to the backend implementation that hides various types from windows.h
538 implementation* m_pImpl;
542 * Constructor. Registers event source with name based on the application
543 * executable file name in the Application log. If such a registration is already
544 * present, it is not overridden.
546 template< typename T >
547 explicit basic_event_log_backend(std::basic_string< T > const& message_file_name)
549 construct(keywords::message_file = message_file_name);
552 * Constructor. Registers event source with name based on the application
553 * executable file name in the Application log. If such a registration is already
554 * present, it is not overridden.
556 explicit basic_event_log_backend(filesystem::path const& message_file_name)
558 construct(keywords::message_file = message_file_name);
561 * Constructor. Registers event log source with the specified parameters.
562 * The following named parameters are supported:
564 * \li \c message_file - Specifies the file name that contains resources that
565 * describe events and categories. This parameter is mandatory unless \c registration is \c never.
566 * \li \c target - Specifies an UNC path to the remote server to which log records should be sent to.
567 * The local machine will be used to process log records, if not specified.
568 * \li \c log_name - Specifies the log in which the source should be registered.
569 * The result of \c get_default_log_name is used, if the parameter is not specified.
570 * \li \c log_source - Specifies the source name. The result of \c get_default_source_name
571 * is used, if the parameter is not specified.
572 * \li \c registration - Specifies the event source registration mode in the Windows registry.
573 * Can have values of the \c registration_mode enum. Default value: \c on_demand.
575 * \param args A set of named parameters.
577 #ifndef BOOST_LOG_DOXYGEN_PASS
578 BOOST_LOG_PARAMETRIZED_CONSTRUCTORS_CALL(basic_event_log_backend, construct)
580 template< typename... ArgsT >
581 explicit basic_event_log_backend(ArgsT... const& args);
585 * Destructor. Unregisters event source. The log source description is not removed from the Windows registry.
587 BOOST_LOG_API ~basic_event_log_backend();
590 * The method creates an event in the event log
592 * \param rec Log record to consume
594 BOOST_LOG_API void consume(record_view const& rec);
597 * The method installs the function object that maps application severity levels to WinAPI event types
599 BOOST_LOG_API void set_event_type_mapper(event_type_mapper_type const& mapper);
602 * The method installs the function object that extracts event category from attribute values
604 BOOST_LOG_API void set_event_category_mapper(event_category_mapper_type const& mapper);
607 * The method installs the function object that extracts event identifier from the attributes and creates
608 * insertion strings that will replace placeholders in the event message.
610 BOOST_LOG_API void set_event_composer(event_composer_type const& composer);
613 * \returns Default log name: Application
615 BOOST_LOG_API static string_type get_default_log_name();
617 * \returns Default log source name that is based on the application executable file name and the sink name
619 BOOST_LOG_API static string_type get_default_source_name();
622 #ifndef BOOST_LOG_DOXYGEN_PASS
623 //! Constructs backend implementation
624 template< typename ArgsT >
625 void construct(ArgsT const& args)
628 filesystem::path(args[keywords::message_file | filesystem::path()]),
629 args[keywords::target | string_type()],
630 args[keywords::log_name || &basic_event_log_backend::get_default_log_name],
631 args[keywords::log_source || &basic_event_log_backend::get_default_source_name],
632 args[keywords::registration | event_log::on_demand]);
634 BOOST_LOG_API void construct(
635 filesystem::path const& message_file_name,
636 string_type const& target,
637 string_type const& log_name,
638 string_type const& source_name,
639 event_log::registration_mode reg_mode);
640 #endif // BOOST_LOG_DOXYGEN_PASS
643 #ifdef BOOST_LOG_USE_CHAR
644 typedef basic_simple_event_log_backend< char > simple_event_log_backend; //!< Convenience typedef for narrow-character logging
645 typedef basic_event_log_backend< char > event_log_backend; //!< Convenience typedef for narrow-character logging
647 #ifdef BOOST_LOG_USE_WCHAR_T
648 typedef basic_simple_event_log_backend< wchar_t > wsimple_event_log_backend; //!< Convenience typedef for wide-character logging
649 typedef basic_event_log_backend< wchar_t > wevent_log_backend; //!< Convenience typedef for wide-character logging
654 BOOST_LOG_CLOSE_NAMESPACE // namespace log
658 #include <boost/log/detail/footer.hpp>
660 #endif // BOOST_LOG_WITHOUT_EVENT_LOG
662 #endif // BOOST_LOG_SINKS_EVENT_LOG_BACKEND_HPP_INCLUDED_