libzypp: zypp::Exception Class Reference

libzypp 17.38.5

zypp::Exception Class Reference

Base class for Exception. More...

`#include <zypp-core/base/Exception.h>`

Inheritance diagram for zypp::Exception:

## Public Types
using | CodeLocation = exception_detail::CodeLocation
using | History = std::list<std::string>
using | HistoryIterator = History::const_iterator
using | HistorySize = History::size_type

## Public Member Functions
| Exception ()
| Default ctor.
| Exception (const std::string &msg_r)
| Ctor taking a message.
| Exception (std::string &&msg_r)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
| Exception (const std::string &msg_r, const Exception &history_r)
| Ctor taking a message and an exception to remember as history.
| Exception (std::string &&msg_r, const Exception &history_r)
| Exception (const std::string &msg_r, Exception &&history_r)
| Exception (std::string &&msg_r, Exception &&history_r)
| ~Exception () override throw ()
| Dtor.
const CodeLocation & | where () const
| Return CodeLocation.
void | relocate (const CodeLocation &where_r) const
| Exchange location on rethrow.
void | relocate (CodeLocation &&where_r) const
| Exchange location on rethrow.
const std::string & | msg () const
| Return the message string provided to the ctor.
std::string | asString () const
| Error message provided by dumpOn as string.
std::string | asUserString () const
| Translated error message as string suitable for the user.

## Friends
std::ostream & | operator<< (std::ostream &str, const Exception &obj)

## Related Symbols
(Note that these are not member symbols.)
std::ostream & | operator<< (std::ostream &str, const Exception &obj) ZYPP_API
| Stream output.

## History list of message strings.
Maintain a simple list of individual error messages, that lead to this Exception. The Exceptions message itself is not included in the history. The History list stores the most recent message fist.
CodeLocation | _where
std::string | _msg
History | _history
void | remember (const Exception &old_r)
| Store an other Exception as history.
void | remember (Exception &&old_r)
void | remember (std::exception_ptr old_r)
void | remember (const std::string &msg_r)
| Remembering a plain string is most probably not wanted - we addHistory.
void | remember (std::string &&msg_r)
void | addHistory (const std::string &msg_r)
| Add some message text to the history.
void | addHistory (std::string &&msg_r)
template<class TContainer>
void | addToHistory (const TContainer &msgc_r)
| addHistory from string container types (oldest first)
template<class TContainer>
void | moveToHistory (TContainer &&msgc_r)
| addHistory from string container types (oldest first) moving
HistoryIterator | historyBegin () const
| Iterator pointing to the most recent message.
HistoryIterator | historyEnd () const
| Iterator pointing behind the last message.
bool | historyEmpty () const
| Whether the history list is empty.
HistorySize | historySize () const
| The size of the history list.
std::string | historyAsString () const
| The history as string.
std::string | asUserHistory () const
| A single (multiline) string composed of asUserString and historyAsString.
virtual std::ostream & | dumpOn (std::ostream &str) const
| Overload this to print a proper error message.
static std::string | strErrno (int errno_r)
| Make a string from errno_r.
static std::string | strErrno (int errno_r, std::string msg_r)
| Make a string from errno_r and msg_r.
static void | log (const Exception &excpt_r, const CodeLocation &where_r, const char *const prefix_r)
| Drop a logline on throw, catch or rethrow.
static void | log (const char *typename_r, const CodeLocation &where_r, const char *const prefix_r)
| \overrload for not-Exception types thrown via ZYPP_THROW
const char * | what () const override throw ()
| Return message string.
std::ostream & | dumpError (std::ostream &str) const
| Called by std::ostream & operator<<.

## Detailed Description

Base class for Exception.

Exception offers to store a message string passed to the ctor. Derived classes may provide additional information. Overload dumpOn to provide a proper error text.

- Use ZYPP_THROW macros to throw exceptions.
- Use ZYPP_CAUGHT If you caught an exceptions in order to handle it.
- Use ZYPP_RETHROW to rethrow a caught exception.

The use of these macros is not mandatory. but `ZYPP_THROW` and `ZYPP_RETHROW` will adjust the code location information stored in the Exception. All three macros will drop a line in the logfile.

43 try
44 {
45 try
46 {
47 ZYPP_THROW( Exception("Something bad happened.") );
48 }
49 catch ( Exception & excpt )
50 {
51 ZYPP_RETHROW( excpt );
52 }
53
54 }
55 catch ( Exception & excpt )
56 {
57 ZYPP_CAUGHT( excpt );
58 }
ZYPP_RETHROW
#define ZYPP_RETHROW(EXCPT)
Drops a logline and rethrows, updating the CodeLocation.
Definition Exception.h:479
ZYPP_CAUGHT
#define ZYPP_CAUGHT(EXCPT)
Drops a logline telling the Exception was caught (in order to handle it).
Definition Exception.h:475
ZYPP_THROW
#define ZYPP_THROW(EXCPT)
Drops a logline and throws the Exception.
Definition Exception.h:459
zypp::Exception
Base class for Exception.
Definition Exception.h:153
zypp::Exception::Exception
Exception()
Default ctor.
Definition Exception.cc:94

The above produces the following log lines:

Main.cc(main):47 THROW: Main.cc(main):47: Something bad happened.
Main.cc(main):51 RETHROW: Main.cc(main):47: Something bad happened.
Main.cc(main):57 CAUGHT: Main.cc(main):51: Something bad happened.

Class Exception now offers a history list of message strings. These messages should describe what lead to the exception.

The Exceptions message itself is NOT included in the history.

Rethrow, remembering an old exception:

try
{
....
}
catch( const Exception & olderr_r )
{
ZYPP_CAUGHT( olderr_r )
HighLevelException newerr( "Something failed." );
newerr.rember( olderr_r );
ZYPP_THROW( newerr );
}

Print an Exception, followed by its history, if available:

Exception error;
ERR << error << endl << error.historyAsString();
ERR
#define ERR
Definition Logger.h:102

Todo
  That's a draft to have a common way of throwing exceptions. Most probably, we'll finally use blocxx exceptions here, but not in the remaining code of zypp. If we can, we should try to wrap the blocxx macros and typedef the classes in here.

Definition at line 152 of file Exception.h.

## Member Typedef Documentation

## ◆ CodeLocation

using zypp::Exception::CodeLocation = exception_detail::CodeLocation

Definition at line 157 of file Exception.h.

## ◆ History

using zypp::Exception::History = std::list<std::string>

Definition at line 158 of file Exception.h.

## ◆ HistoryIterator

using zypp::Exception::HistoryIterator = History::const_iterator

Definition at line 159 of file Exception.h.

## ◆ HistorySize

using zypp::Exception::HistorySize = History::size_type

Definition at line 160 of file Exception.h.

## Constructor & Destructor Documentation

## ◆ Exception() [1/7]

zypp::Exception::Exception | ( |  | ) |

Default ctor.

Use ZYPP_THROW macros to throw exceptions.

Definition at line 94 of file Exception.cc.

## ◆ Exception() [2/7]

zypp::Exception::Exception | ( | const std::string & | msg_r | ) |

Ctor taking a message.

Use ZYPP_THROW macros to throw exceptions.

Definition at line 97 of file Exception.cc.

## ◆ Exception() [3/7]

zypp::Exception::Exception | ( | std::string && | msg_r | ) |

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 101 of file Exception.cc.

## ◆ Exception() [4/7]

zypp::Exception::Exception | ( | const std::string & | msg_r,
|  | const Exception & | history_r )

Ctor taking a message and an exception to remember as history.

See also
  remember Use ZYPP_THROW macros to throw exceptions.

Definition at line 105 of file Exception.cc.

## ◆ Exception() [5/7]

zypp::Exception::Exception | ( | std::string && | msg_r,
|  | const Exception & | history_r )

Definition at line 109 of file Exception.cc.

## ◆ Exception() [6/7]

zypp::Exception::Exception | ( | const std::string & | msg_r,
|  | Exception && | history_r )

Definition at line 113 of file Exception.cc.

## ◆ Exception() [7/7]

zypp::Exception::Exception | ( | std::string && | msg_r,
|  | Exception && | history_r )

Definition at line 117 of file Exception.cc.

## ◆ ~Exception()

zypp::Exception::~Exception | ( |  | ) |
throw | ( | ) |  |  |
| override

Dtor.

Definition at line 121 of file Exception.cc.

## Member Function Documentation

## ◆ where()

const CodeLocation & zypp::Exception::where | ( |  | ) | const
| inline

Return CodeLocation.

Definition at line 190 of file Exception.h.

## ◆ relocate() [1/2]

void zypp::Exception::relocate | ( | const CodeLocation & | where_r | ) | const
| inline

Exchange location on rethrow.

Definition at line 194 of file Exception.h.

## ◆ relocate() [2/2]

void zypp::Exception::relocate | ( | CodeLocation && | where_r | ) | const
| inline

Exchange location on rethrow.

Definition at line 198 of file Exception.h.

## ◆ msg()

const std::string & zypp::Exception::msg | ( |  | ) | const
| inline

Return the message string provided to the ctor.

Note
  This is not necessarily the complete error message. The whole error message is provided by asString or dumpOn.

Definition at line 206 of file Exception.h.

## ◆ asString()

std::string zypp::Exception::asString | ( |  | ) | const

Error message provided by dumpOn as string.

Definition at line 124 of file Exception.cc.

## ◆ asUserString()

std::string zypp::Exception::asUserString | ( |  | ) | const

Translated error message as string suitable for the user.

See also
  asUserStringHistory

Definition at line 131 of file Exception.cc.

## ◆ remember() [1/5]

void zypp::Exception::remember | ( | const Exception & | old_r | ) |

Store an other Exception as history.

Definition at line 154 of file Exception.cc.

## ◆ remember() [2/5]

void zypp::Exception::remember | ( | Exception && | old_r | ) |

Definition at line 164 of file Exception.cc.

## ◆ remember() [3/5]

void zypp::Exception::remember | ( | std::exception_ptr | old_r | ) |

Definition at line 174 of file Exception.cc.

## ◆ remember() [4/5]

void zypp::Exception::remember | ( | const std::string & | msg_r | ) |
| inline

Remembering a plain string is most probably not wanted - we addHistory.

It would discards the old history and replace it with this string. If that's actually your intent, explicitly wrap it into an Exception.

Definition at line 238 of file Exception.h.

## ◆ remember() [5/5]

void zypp::Exception::remember | ( | std::string && | msg_r | ) |
| inline

Definition at line 241 of file Exception.h.

## ◆ addHistory() [1/2]

void zypp::Exception::addHistory | ( | const std::string & | msg_r | ) |

Add some message text to the history.

Definition at line 189 of file Exception.cc.

## ◆ addHistory() [2/2]

void zypp::Exception::addHistory | ( | std::string && | msg_r | ) |

Definition at line 192 of file Exception.cc.

## ◆ addToHistory()

template<class TContainer>

void zypp::Exception::addToHistory | ( | const TContainer & | msgc_r | ) |
| inline

addHistory from string container types (oldest first)

Definition at line 251 of file Exception.h.

## ◆ moveToHistory()

template<class TContainer>

void zypp::Exception::moveToHistory | ( | TContainer && | msgc_r | ) |
| inline

addHistory from string container types (oldest first) moving

Definition at line 258 of file Exception.h.

## ◆ historyBegin()

HistoryIterator zypp::Exception::historyBegin | ( |  | ) | const
| inline

Iterator pointing to the most recent message.

Definition at line 265 of file Exception.h.

## ◆ historyEnd()

HistoryIterator zypp::Exception::historyEnd | ( |  | ) | const
| inline

Iterator pointing behind the last message.

Definition at line 269 of file Exception.h.

## ◆ historyEmpty()

bool zypp::Exception::historyEmpty | ( |  | ) | const
| inline

Whether the history list is empty.

Definition at line 273 of file Exception.h.

## ◆ historySize()

HistorySize zypp::Exception::historySize | ( |  | ) | const
| inline

The size of the history list.

Definition at line 277 of file Exception.h.

## ◆ historyAsString()

std::string zypp::Exception::historyAsString | ( |  | ) | const

The history as string.

Empty if historyEmpty. Otherwise:

History:
- most recent message
- 2nd message
...
- oldest message
zypp::Exception::History
std::list< std::string > History
Definition Exception.h:158

Definition at line 195 of file Exception.cc.

## ◆ asUserHistory()

std::string zypp::Exception::asUserHistory | ( |  | ) | const

A single (multiline) string composed of asUserString and historyAsString.

Definition at line 140 of file Exception.cc.

## ◆ dumpOn()

std::ostream & zypp::Exception::dumpOn | ( | std::ostream & | str | ) | const
| protectedvirtual

Overload this to print a proper error message.

Reimplemented in zypp::media::MediaBadAttachPointException, zypp::media::MediaBadCAException, zypp::media::MediaBadFilenameException, zypp::media::MediaBadUrlEmptyDestinationException, zypp::media::MediaBadUrlEmptyFilesystemException, zypp::media::MediaBadUrlEmptyHostException, zypp::media::MediaBadUrlException, zypp::media::MediaCurlException, zypp::media::MediaCurlInitException, zypp::media::MediaCurlSetOptException, zypp::media::MediaFileNotFoundException, zypp::media::MediaFileSizeExceededException, zypp::media::MediaForbiddenException, zypp::media::MediaIsSharedException, zypp::media::MediaJammedException, zypp::media::MediaMountException, zypp::media::MediaNotADirException, zypp::media::MediaNotAFileException, zypp::media::MediaNotAttachedException, zypp::media::MediaNotDesiredException, zypp::media::MediaNotEjectedException, zypp::media::MediaNotOpenException, zypp::media::MediaNotSupportedException, zypp::media::MediaSystemException, zypp::media::MediaTemporaryProblemException, zypp::media::MediaTimeoutException, zypp::media::MediaUnauthorizedException, zypp::media::MediaUnmountException, zypp::media::MediaUnsupportedUrlSchemeException, zypp::media::MediaWriteException, zypp::ParseException, zypp::parser::ParseException, zypp::repo::RepoException, zypp::repo::ServiceException, zypp::target::rpm::RpmAccessBlockedException, zypp::target::rpm::RpmDbAlreadyOpenException, zypp::target::rpm::RpmDbConvertException, zypp::target::rpm::RpmDbNotOpenException, zypp::target::rpm::RpmDbOpenException, zypp::target::rpm::RpmInitException, zypp::target::rpm::RpmInvalidRootException, zypp::target::rpm::RpmNullDatabaseException, zypp::target::rpm::RpmSubprocessException, zypp::target::rpm::RpmTransactionFailedException, zypp::target::TargetAbortedException, and zypp::UserRequestException.

Definition at line 210 of file Exception.cc.

## ◆ strErrno() [1/2]

std::string zypp::Exception::strErrno | ( | int | errno_r | ) |
| static

Make a string from errno_r.

Definition at line 233 of file Exception.cc.

## ◆ strErrno() [2/2]

std::string zypp::Exception::strErrno | ( | int | errno_r,
|  | std::string | msg_r )
| static

Make a string from errno_r and msg_r.

Definition at line 236 of file Exception.cc.

## ◆ log() [1/2]

void zypp::Exception::log | ( | const Exception & | excpt_r,
|  | const CodeLocation & | where_r,
|  | const char *const | prefix_r )
| static

Drop a logline on throw, catch or rethrow.

Used by ZYPP_THROW macros macros.

Definition at line 242 of file Exception.cc.

## ◆ log() [2/2]

void zypp::Exception::log | ( | const char * | typename_r,
|  | const CodeLocation & | where_r,
|  | const char *const | prefix_r )
| static

\overrload for not-Exception types thrown via ZYPP_THROW

Definition at line 248 of file Exception.cc.

## ◆ what()

const char * zypp::Exception::what | ( |  | ) | const
throw | ( | ) |  |  |
| inlineoverrideprivate

Return message string.

Definition at line 322 of file Exception.h.

## ◆ dumpError()

std::ostream & zypp::Exception::dumpError | ( | std::ostream & | str | ) | const
| private

Called by std::ostream & operator<<.

Prints CodeLocation and the error message provided by dumpOn.

Definition at line 213 of file Exception.cc.

## Friends And Related Symbol Documentation

## ◆ operator<< [1/2]

std::ostream & operator<< | ( | std::ostream & | str,
|  | const Exception & | obj )
| friend

Definition at line 216 of file Exception.cc.

## ◆ operator<<() [2/2]

std::ostream & operator<< | ( | std::ostream & | str,
|  | const Exception & | obj )
| related

Stream output.

Definition at line 216 of file Exception.cc.

## Member Data Documentation

## ◆ _where

CodeLocation zypp::Exception::_where
| mutableprivate

Definition at line 317 of file Exception.h.

## ◆ _msg

std::string zypp::Exception::_msg
| private

Definition at line 318 of file Exception.h.

## ◆ _history

History zypp::Exception::_history
| private

Definition at line 319 of file Exception.h.

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

- zypp-core/base/Exception.h
- zypp-core/base/Exception.cc