1 // Created on: 2007-06-28
2 // Created by: OCC Team
3 // Copyright (c) 2007-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _Message_Messenger_HeaderFile
17 #define _Message_Messenger_HeaderFile
19 #include <Message_Gravity.hxx>
20 #include <Message_SequenceOfPrinters.hxx>
22 #include <TCollection_HAsciiString.hxx>
23 #include <TCollection_HExtendedString.hxx>
25 class Message_Printer;
27 // resolve name collisions with WinAPI headers
32 class Message_Messenger;
33 DEFINE_STANDARD_HANDLE(Message_Messenger, Standard_Transient)
35 //! Messenger is API class providing general-purpose interface for
36 //! libraries that may issue text messages without knowledge
37 //! of how these messages will be further processed.
39 //! The messenger contains a sequence of "printers" which can be
40 //! customized by the application, and dispatches every received
41 //! message to all the printers.
43 //! For convenience, a set of methods Send...() returning a string
44 //! stream buffer is defined for use of stream-like syntax with operator <<
48 //! Messenger->SendFail() << " Unknown fail at line " << aLineNo << " in file " << aFile;
51 //! The message is sent to messenger on destruction of the stream buffer,
52 //! call to Flush(), or passing manipulator std::ends, std::endl, or std::flush.
53 //! Empty messages are not sent except if manipulator is used.
54 class Message_Messenger : public Standard_Transient
56 DEFINE_STANDARD_RTTIEXT(Message_Messenger, Standard_Transient)
58 //! Auxiliary class wrapping std::stringstream thus allowing constructing
59 //! message via stream interface, and putting result into its creator
60 //! Message_Messenger within destructor.
62 //! It is intended to be used either as temporary object or as local
63 //! variable, note that content will be lost if it is copied.
68 //! Destructor flushing constructed message.
69 ~StreamBuffer() { Flush(); }
71 //! Flush collected string to messenger
72 void Flush(Standard_Boolean doForce = Standard_False)
75 if (doForce || myStream.rdbuf()->in_avail() > 0)
79 myMessenger->Send(myStream.str().c_str(), myGravity);
81 myStream.str(std::string()); // empty the buffer for possible reuse
85 //! Formal copy constructor.
87 //! Since buffer is intended for use as temporary object or local
88 //! variable, copy (or move) is needed only formally to be able to
89 //! return the new instance from relevant creation method.
90 //! In practice it should never be called because modern compilers
91 //! create such instances in place.
92 //! However note that if this constructor is called, the buffer
93 //! content (string) will not be copied (move is not supported for
94 //! std::stringstream class on old compilers such as gcc 4.4, msvc 9).
95 StreamBuffer (const StreamBuffer& theOther)
96 : myMessenger(theOther.myMessenger), myGravity(theOther.myGravity)
100 //! Wrapper for operator << of the stream
101 template <typename T>
102 StreamBuffer& operator << (const T& theArg)
108 //! Operator << for manipulators of ostream (ends, endl, flush),
109 //! flushes the buffer (sends the message)
110 StreamBuffer& operator << (std::ostream& (*)(std::ostream&))
112 Flush(Standard_True);
116 //! Access to the stream object
117 Standard_SStream& Stream () { return myStream; }
120 operator Standard_OStream& () { return myStream; }
122 //! Access to the messenger
123 Message_Messenger* Messenger () { return myMessenger; }
126 friend class Message_Messenger;
128 //! Main constructor creating temporary buffer.
129 //! Accessible only to Messenger class.
130 StreamBuffer (Message_Messenger* theMessenger, Message_Gravity theGravity)
131 : myMessenger (theMessenger),
132 myGravity (theGravity)
136 Message_Messenger* myMessenger; // don't make a Handle since this object should be created on stack
137 Message_Gravity myGravity;
138 Standard_SStream myStream;
143 //! Empty constructor; initializes by single printer directed to std::cout.
144 //! Note: the default messenger is not empty but directed to cout
145 //! in order to protect against possibility to forget defining printers.
146 //! If printing to cout is not needed, clear messenger by GetPrinters().Clear()
147 Standard_EXPORT Message_Messenger();
149 //! Create messenger with single printer
150 Standard_EXPORT Message_Messenger(const Handle(Message_Printer)& thePrinter);
152 //! Add a printer to the messenger.
153 //! The printer will be added only if it is not yet in the list.
154 //! Returns True if printer has been added.
155 Standard_EXPORT Standard_Boolean AddPrinter (const Handle(Message_Printer)& thePrinter);
157 //! Removes specified printer from the messenger.
158 //! Returns True if this printer has been found in the list
160 Standard_EXPORT Standard_Boolean RemovePrinter (const Handle(Message_Printer)& thePrinter);
162 //! Removes printers of specified type (including derived classes)
163 //! from the messenger.
164 //! Returns number of removed printers.
165 Standard_EXPORT Standard_Integer RemovePrinters (const Handle(Standard_Type)& theType);
167 //! Returns current sequence of printers
168 const Message_SequenceOfPrinters& Printers() const { return myPrinters; }
170 //! Returns sequence of printers
171 //! The sequence can be modified.
172 Message_SequenceOfPrinters& ChangePrinters() { return myPrinters; }
174 //! Dispatch a message to all the printers in the list.
175 //! Three versions of string representations are accepted for
176 //! convenience, by default all are converted to ExtendedString.
177 //! The parameter putEndl specifies whether the new line should
178 //! be started after this message (default) or not (may have
179 //! sense in some conditions).
180 Standard_EXPORT void Send (const Standard_CString theString,
181 const Message_Gravity theGravity = Message_Warning,
182 const Standard_Boolean putEndl = Standard_True) const;
185 Standard_EXPORT void Send (const TCollection_AsciiString& theString,
186 const Message_Gravity theGravity = Message_Warning,
187 const Standard_Boolean putEndl = Standard_True) const;
190 Standard_EXPORT void Send (const TCollection_ExtendedString& theString,
191 const Message_Gravity theGravity = Message_Warning,
192 const Standard_Boolean putEndl = Standard_True) const;
194 //! Create string buffer for message of specified type
195 StreamBuffer Send (Message_Gravity theGravity) { return StreamBuffer (this, theGravity); }
197 //! Create string buffer for sending Fail message
198 StreamBuffer SendFail () { return Send (Message_Fail); }
200 //! Create string buffer for sending Alarm message
201 StreamBuffer SendAlarm () { return Send (Message_Alarm); }
203 //! Create string buffer for sending Warning message
204 StreamBuffer SendWarning () { return Send (Message_Warning); }
206 //! Create string buffer for sending Info message
207 StreamBuffer SendInfo () { return Send (Message_Info); }
209 //! Create string buffer for sending Trace message
210 StreamBuffer SendTrace () { return Send (Message_Trace); }
212 //! Short-cut to Send (theMessage, Message_Fail)
213 void SendFail (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Fail); }
215 //! Short-cut to Send (theMessage, Message_Alarm)
216 void SendAlarm (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Alarm); }
218 //! Short-cut to Send (theMessage, Message_Warning)
219 void SendWarning (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Warning); }
221 //! Short-cut to Send (theMessage, Message_Info)
222 void SendInfo (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Info); }
224 //! Short-cut to Send (theMessage, Message_Trace)
225 void SendTrace (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Trace); }
229 Message_SequenceOfPrinters myPrinters;
233 #endif // _Message_Messenger_HeaderFile