From 9ef95a8d64489fd1735255133ea1f8a2741b632a Mon Sep 17 00:00:00 2001 From: Simon Rozman Date: Fri, 4 Nov 2016 12:53:44 +0100 Subject: [PATCH] EventMonitor Doxygen documentation update --- EventMonitor/App.h | 10 +++ EventMonitor/ETWLog.cpp | 8 ++ EventMonitor/ETWLog.h | 171 ++++++++++++++++++++++++++++++++++++--- EventMonitor/Frame.cpp | 4 + EventMonitor/Frame.h | 45 ++++++++++- EventMonitor/LogPanel.h | 37 ++++++++- lib/PAP/include/Config.h | 2 +- 7 files changed, 264 insertions(+), 13 deletions(-) diff --git a/EventMonitor/App.h b/EventMonitor/App.h index ad2d80b..f6ff98c 100644 --- a/EventMonitor/App.h +++ b/EventMonitor/App.h @@ -18,6 +18,11 @@ along with GÉANTLink. If not, see . */ +/// +/// \defgroup EventMonitor Event Monitor +/// Real-time log of application events +/// + class wxEventMonitorApp; #pragma once @@ -29,6 +34,9 @@ class wxEventMonitorApp; #include +/// \addtogroup EventMonitor +/// @{ + /// /// EventMonitor application /// @@ -57,4 +65,6 @@ public: wxLocale m_locale; ///< Current locale }; +/// @} + wxDECLARE_APP(wxEventMonitorApp); diff --git a/EventMonitor/ETWLog.cpp b/EventMonitor/ETWLog.cpp index 2e2f7dd..1e96de4 100644 --- a/EventMonitor/ETWLog.cpp +++ b/EventMonitor/ETWLog.cpp @@ -115,6 +115,8 @@ void wxEventTraceProcessorThread::Abort() } +/// \cond internal + wxThread::ExitCode wxEventTraceProcessorThread::Entry() { // Process events. @@ -139,6 +141,8 @@ VOID WINAPI wxEventTraceProcessorThread::EventRecordCallback(_In_ PEVENT_RECORD _this->m_parent->QueueEvent(new wxETWEvent(wxEVT_ETW_EVENT, *pEvent)); } +/// \endcond + ////////////////////////////////////////////////////////////////////////// // wxETWListCtrl @@ -460,6 +464,8 @@ void wxETWListCtrl::RebuildItems() } +/// \cond internal + bool wxETWListCtrl::IsVisible(const EVENT_RECORD &rec) const { return @@ -678,6 +684,8 @@ void wxETWListCtrl::OnETWEvent(wxETWEvent& event) } } +/// \endcond + ////////////////////////////////////////////////////////////////////////// // wxPersistentETWListCtrl diff --git a/EventMonitor/ETWLog.h b/EventMonitor/ETWLog.h index 07a31f4..4d997ac 100644 --- a/EventMonitor/ETWLog.h +++ b/EventMonitor/ETWLog.h @@ -20,11 +20,16 @@ #include +/// \addtogroup EventMonitor +/// @{ + /// /// Maximum number of event records kept /// #define wxETWEVENT_RECORDS_MAX 1000000 +/// @} + class wxETWEvent; wxDECLARE_EVENT(wxEVT_ETW_EVENT, wxETWEvent); #define wxETWEventHandler(func) wxEVENT_HANDLER_CAST(wxETWEventFunction, func) @@ -47,53 +52,106 @@ class wxPersistentETWListCtrl; #include +/// \addtogroup EventMonitor +/// @{ + /// /// ETW event /// class wxETWEvent : public wxEvent { public: + /// + /// Creates ETW event + /// + /// \param[in] type The unique type of event + /// \param[in] record ETW event record + /// wxETWEvent(wxEventType type = wxEVT_NULL, const EVENT_RECORD &record = s_record_null); + + /// + /// Copies an ETW event + /// + /// \param[in] event ETW event to copy from + /// wxETWEvent(const wxETWEvent& event); - virtual wxEvent *Clone() const { return new wxETWEvent(*this); } - inline const winstd::event_rec& GetRecord() const { return m_record; } - inline winstd::event_rec& GetRecord() { return m_record; } + /// + /// Clones the ETW event + /// + /// \returns Event copy + /// + virtual wxEvent *Clone() const + { + return new wxETWEvent(*this); + } -protected: - bool DoSetExtendedData(size_t extended_data_count, const EVENT_HEADER_EXTENDED_DATA_ITEM *extended_data); - bool DoSetUserData(size_t user_data_length, const void *user_data); + /// + /// Returns ETW event record assosiated with event + /// + inline const winstd::event_rec& GetRecord() const + { + return m_record; + } + + /// + /// Returns ETW event record assosiated with event + /// + inline winstd::event_rec& GetRecord() + { + return m_record; + } private: DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxETWEvent) public: - static const EVENT_RECORD s_record_null; + static const EVENT_RECORD s_record_null; ///< Blank ETW event record protected: winstd::event_rec m_record; ///< ETW event record }; +/// +/// Prototype of the function consuming `wxETWEvent` events +/// typedef void (wxEvtHandler::*wxETWEventFunction)(wxETWEvent&); /// -/// Event trace processor +/// Monitors ETW events and forwards them as `wxETWEvent` event /// class wxEventTraceProcessorThread : public wxThread { public: + /// + /// A thread to process ETW events + /// + /// \param[in] parent Event handler this thread will send record notifications + /// \param[in] sessions An array of sessions to monitor + /// wxEventTraceProcessorThread(wxEvtHandler *parent, const wxArrayString &sessions); + + /// + /// Destructor + /// virtual ~wxEventTraceProcessorThread(); + /// + /// Closes all session handles to allow graceful thread termination + /// void Abort(); protected: + /// \cond internal virtual ExitCode Entry(); + /// \endcond private: + /// \cond internal static VOID WINAPI EventRecordCallback(PEVENT_RECORD pEvent); + /// \endcond protected: std::vector m_traces; ///< An array of tracing sessions this thread is monitoring @@ -112,6 +170,9 @@ protected: /// struct less_guid : public std::binary_function { + /// + /// Compares two GUIDs + /// bool operator()(const GUID &a, const GUID &b) const { if (a.Data1 < b.Data1) return true; @@ -131,6 +192,17 @@ protected: typedef std::set guidset; public: + /// + /// Creates a list control for ETW log display + /// + /// \param[in] parent Parent window. Must not be \c NULL. + /// \param[in] id Window identifier. The value \c wxID_ANY indicates a default value. + /// \param[in] pos Window position. If \c wxDefaultPosition is specified then a default position is chosen. + /// \param[in] size Window size. If \c wxDefaultSize is specified then the window is sized appropriately. + /// \param[in] style Window style. See \c wxListCtrl. + /// \param[in] validator Window validator + /// \param[in] name Window name + /// wxETWListCtrl( wxWindow *parent, wxWindowID id = wxID_ANY, @@ -139,21 +211,70 @@ public: long style = wxLC_NO_SORT_HEADER|wxLC_REPORT|wxLC_VIRTUAL|wxNO_BORDER, const wxValidator &validator = wxDefaultValidator, const wxString &name = wxListCtrlNameStr); + + /// + /// Destructor + /// virtual ~wxETWListCtrl(); - inline bool IsEmpty() const { return m_rec_db.empty(); } + /// + /// Returns true if the list is empty + /// + inline bool IsEmpty() const + { + return m_rec_db.empty(); + } + + /// + /// Copies selected rows to clipboard + /// void CopySelected() const; + + /// + /// Copies all rows (including hidden ones) to clipboard + /// void CopyAll() const; + + /// + /// Empties the list + /// void ClearAll(); + + /// + /// Selects all rows + /// void SelectAll(); + + /// + /// Clears row selection + /// void SelectNone(); + + /// + /// Rebuilds the list + /// void RebuildItems(); + /// + /// Checks if given ETW source is enabled + /// + /// \param[in] guid GUID of ETW source + /// + /// \returns + /// - \c true if ETW source with \p guid GUID is enabled; + /// - \c false otherwise. + /// inline bool IsSourceEnabled(const GUID &guid) const { return m_sources.find(guid) != m_sources.end(); } + /// + /// Enables/Disables ETW source + /// + /// \param[in] guid GUID of ETW source + /// \param[in] enable \c true to enable, \c false to disable + /// inline void EnableSource(const GUID &guid, bool enable = true) { auto s = m_sources.find(guid); @@ -173,6 +294,7 @@ public: friend class wxPersistentETWListCtrl; // Allow saving/restoring window state. protected: + /// \cond internal bool IsVisible(const EVENT_RECORD &rec) const; void FormatRow(const winstd::event_rec &rec, std::string &rowA, std::wstring &rowW) const; bool CopyToClipboard(const std::string &dataA, const std::wstring &dataW) const; @@ -181,6 +303,8 @@ protected: virtual wxString OnGetItemText(long item, long column) const; virtual wxString OnGetItemText(const winstd::event_rec &rec, long column) const; void OnETWEvent(wxETWEvent& event); + /// \endcond + DECLARE_EVENT_TABLE() public: @@ -205,20 +329,47 @@ protected: /// -/// Supports saving/restoring wxETWListCtrl state +/// Supports saving/restoring `wxETWListCtrl` state /// class wxPersistentETWListCtrl : public wxPersistentWindow { public: + /// + /// Constructor for a persistent window object + /// + /// \param[in] wnd Window this object will save/restore + /// wxPersistentETWListCtrl(wxETWListCtrl *wnd); + /// + /// Returns the string uniquely identifying the objects supported by this adapter. + /// + /// \returns This implementation always returns `wxT(wxPERSIST_TLW_KIND)` + /// virtual wxString GetKind() const; + + /// + /// Saves the object properties + /// virtual void Save() const; + + /// + /// Restores the object properties + /// + /// \returns + /// - \c true if the properties were successfully restored; + /// - \c false otherwise. + /// virtual bool Restore(); }; +/// +/// Creates persistent window object for `wxETWListCtrl` class window +/// inline wxPersistentObject *wxCreatePersistentObject(wxETWListCtrl *wnd) { return new wxPersistentETWListCtrl(wnd); } + +/// @} diff --git a/EventMonitor/Frame.cpp b/EventMonitor/Frame.cpp index ae38ad8..217dfb3 100644 --- a/EventMonitor/Frame.cpp +++ b/EventMonitor/Frame.cpp @@ -261,6 +261,8 @@ wxEventMonitorFrame::~wxEventMonitorFrame() } +/// \cond internal + void wxEventMonitorFrame::OnExit(wxCommandEvent& event) { Close(); @@ -408,6 +410,8 @@ void wxEventMonitorFrame::OnViewToolbar(wxCommandEvent& event) } } +/// \endcond + ////////////////////////////////////////////////////////////////////////// // wxPersistentEventMonitorFrame diff --git a/EventMonitor/Frame.h b/EventMonitor/Frame.h index 315f321..faff92e 100644 --- a/EventMonitor/Frame.h +++ b/EventMonitor/Frame.h @@ -35,6 +35,9 @@ class wxPersistentEventMonitorFrame; #include +/// \addtogroup EventMonitor +/// @{ + /// /// EventMonitor main frame /// @@ -58,12 +61,28 @@ protected: }; public: + /// + /// Creates an EventMonitor frame window + /// + /// \param[in] parent The window parent. This may be \c NULL. If it is non-NULL, the frame will always be displayed on top of the parent window on Windows. + /// \param[in] id The window identifier. It may take a value of \c wxID_ANY to indicate a default value. + /// \param[in] title The caption to be displayed on the frame's title bar. + /// \param[in] pos The window position. The value \c wxDefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform. + /// \param[in] size The window size. The value \c wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform. + /// \param[in] style The window style. See `wxFrame` class description. + /// \param[in] name The name of the window. This parameter is used to associate a name with the item, allowing the application user to set Motif resource values for individual windows. + /// wxEventMonitorFrame(wxWindow* parent, wxWindowID id = wxID_ANY, const wxString& title = _("Event Monitor"), const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize(600,400), long style = wxDEFAULT_FRAME_STYLE|wxTAB_TRAVERSAL, const wxString& name = wxT("EventMonitor")); + + /// + /// Destructor + /// ~wxEventMonitorFrame(); friend class wxPersistentEventMonitorFrame; protected: + /// \cond internal void OnExit(wxCommandEvent& event); void OnEditCopyUpdate(wxUpdateUIEvent& event); void OnEditCopy(wxCommandEvent& event); @@ -83,8 +102,10 @@ protected: void OnViewLevel(wxCommandEvent& event); void OnViewToolbarUpdate(wxUpdateUIEvent& event); void OnViewToolbar(wxCommandEvent& event); + /// \endcond protected: + /// \cond internal wxMenuBar* m_menubar; wxMenu* m_menuProgram; wxMenu* m_menuEdit; @@ -110,23 +131,45 @@ protected: wxStatusBar* m_statusBar; wxEventMonitorLogPanel* m_panel; wxAuiManager m_mgr; + /// \endcond }; /// -/// Supports saving/restoring wxEventMonitorFrame GUI state +/// Supports saving/restoring `wxEventMonitorFrame` GUI state /// class wxPersistentEventMonitorFrame : public wxPersistentTLW { public: + /// + /// Constructor for a persistent window object + /// + /// \param[in] wnd Window this object will save/restore + /// wxPersistentEventMonitorFrame(wxEventMonitorFrame *wnd); + /// + /// Saves the object properties + /// virtual void Save() const; + + /// + /// Restores the object properties + /// + /// \returns + /// - \c true if the properties were successfully restored; + /// - \c false otherwise. + /// virtual bool Restore(); }; +/// +/// Creates persistent window object for `wxETWListCtrl` class window +/// inline wxPersistentObject *wxCreatePersistentObject(wxEventMonitorFrame *wnd) { return new wxPersistentEventMonitorFrame(wnd); } + +/// @} diff --git a/EventMonitor/LogPanel.h b/EventMonitor/LogPanel.h index 4709c55..eb72f22 100644 --- a/EventMonitor/LogPanel.h +++ b/EventMonitor/LogPanel.h @@ -27,12 +27,20 @@ class wxPersistentEventMonitorLogPanel; #include +/// \addtogroup EventMonitor +/// @{ + /// /// EventMonitor trace log panel /// class wxEventMonitorLogPanel : public wxEventMonitorLogPanelBase { public: + /// + /// Constructs EventMonitor log panel + /// + /// \param[in] parent Parent window. Must not be \c NULL. + /// wxEventMonitorLogPanel(wxWindow* parent); friend class wxPersistentEventMonitorLogPanel; // Allow saving/restoring window state. @@ -40,20 +48,47 @@ public: /// -/// Supports saving/restoring wxEventMonitorLogPanel state +/// Supports saving/restoring `wxEventMonitorLogPanel` state /// class wxPersistentEventMonitorLogPanel : public wxPersistentWindow { public: + /// + /// Constructor for a persistent window object + /// + /// \param[in] wnd Window this object will save/restore + /// wxPersistentEventMonitorLogPanel(wxEventMonitorLogPanel *wnd); + /// + /// Returns the string uniquely identifying the objects supported by this adapter. + /// + /// \returns This implementation always returns `wxT(wxPERSIST_TLW_KIND)` + /// virtual wxString GetKind() const; + + /// + /// Saves the object properties + /// virtual void Save() const; + + /// + /// Restores the object properties + /// + /// \returns + /// - \c true if the properties were successfully restored; + /// - \c false otherwise. + /// virtual bool Restore(); }; +/// +/// Creates persistent window object for `wxEventMonitorLogPanel` class window +/// inline wxPersistentObject *wxCreatePersistentObject(wxEventMonitorLogPanel *wnd) { return new wxPersistentEventMonitorLogPanel(wnd); } + +/// @} diff --git a/lib/PAP/include/Config.h b/lib/PAP/include/Config.h index 9dbc562..812249c 100644 --- a/lib/PAP/include/Config.h +++ b/lib/PAP/include/Config.h @@ -36,7 +36,7 @@ namespace eap namespace eap { - /// \\addtogroup EAPBaseConfig + /// \addtogroup EAPBaseConfig /// @{ ///