1/* 2 * Copyright 2021 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/support/ErrorsExt.h hrev????? 10 */ 11 12 13#if __cplusplus >= 201703L 14 15 16/*! 17 \file ErrorsExt.h 18 \ingroup netservices 19 \brief Defines advanced error types and error functions for the Network Services API. 20 21 \since Haiku R1 22*/ 23 24 25namespace BPrivate { 26 27namespace Network { 28 29 30/*! 31 \class BError 32 \ingroup netservices 33 \brief Abstract base class for advanced error objects. 34 35 This class defines the minimum interface for advanced error objects in 36 modern parts of the Haiku API. 37 38 The minimum definition of an error is that it contains an \em origin and 39 a \em message. The origin should contain a string that helps a developer 40 identify the origin of the error. Common practise is to pass the 41 \c __PRETTY_FUNCTION__ from the place where the error is constructed, but 42 subclasses can have their own definitions for the origin. 43 44 The message is a freeform message that describes the exact error condition. 45 While it is not meant as a user-facing message, when creating custom error 46 objects, take into account that a user may be confronted with a message in 47 situations where an application presents it to a user as a final resort. 48 49 \note The advanced error objects are not used in the existing legacy Haiku 50 Kits. They are being tested for use in the modern parts of the API and are 51 therefore included in the network services kit. 52 53 \since Haiku R1 54*/ 55 56 57/*! 58 \fn BError::BError(const char* error) 59 \brief Constructor that sets the \a origin. 60 61 \since Haiku R1 62*/ 63 64 65/*! 66 \fn BError::BError(BString origin) 67 \brief Constructor that sets the \a origin. 68 69 \since Haiku R1 70*/ 71 72 73/*! 74 \fn virtual BError::~BError() noexcept 75 \brief Standard destructor. 76 77 \since Haiku R1 78*/ 79 80 81/*! 82 \fn BError::BError(const BError& other) 83 \brief Copy constructor. 84 85 \since Haiku R1 86*/ 87 88 89/*! 90 \fn BError::BError(BError&& other) noexcept 91 \brief Move constructor. 92 93 \since Haiku R1 94*/ 95 96 97/*! 98 \fn BError& BError::operator=(const BError& other) 99 \brief Copy assignment operator. 100 101 \since Haiku R1 102*/ 103 104 105/*! 106 \fn BError& BError::operator=(BError&& other) noexcept 107 \brief Move assignment operator. 108 109 \since Haiku R1 110*/ 111 112 113/*! 114 \fn virtual const char* BError::Message() const noexcept = 0 115 \brief Access the string representation of the message. 116 117 Implementations should return a meaningful description of the error that 118 occured. The primary target audience of these messages are developers, who 119 (hopefully) see them during development, testing or in bug reports. 120 However, if it makes sense to have the error messages be instructive to 121 users too, then do not hesitate to do so. 122 123 Implementations of this function should never return \c NULL. 124 125 \since Haiku R1 126*/ 127 128 129/*! 130 \fn virtual const char* BError::Origin() const noexcept 131 \brief Access the string representation of the origin of the error. 132 133 The default implementation returns a pointer to the string that was set as 134 the origin when this object was constructed. 135 136 Implementations of this function should never return \c NULL. 137 138 \since Haiku R1 139*/ 140 141 142/*! 143 \fn virtual BString BError::DebugMessage() const 144 \brief Retrieve a debug message that contains all info in this error. 145 146 \code 147 [Origin] Message of error 148 \endcode 149 150 \exception std::bad_alloc In the future this method may throw this 151 exception when the memory for the debug message cannot be allocated. 152 153 \return A \ref BString object that contains the debug message. 154 155 \since Haiku R1 156*/ 157 158 159/*! 160 \fn void BError::WriteToStream(std::ostream& stream) const 161 \brief Write the error description to an output stream. 162 163 The default implementation will write the output of the \ref DebugMessage() 164 method, and append a newline. 165 166 \exception std::ios_base::failure Any error that is forwarded when writing 167 to the \a stream. 168 169 \since Haiku R1 170*/ 171 172 173/*! 174 \fn size_t BError::WriteToOutput(BDataIO* output) const 175 \brief Write the error description to an output. 176 177 The default implementation will use the output from \ref DebugMessage() 178 and write it to the \a output, including a newline and the NUL that 179 terminates the string. 180 181 \exception BSystemError For any error that occurs when calling 182 \ref BDataIO::Write() 183 184 \returns The number of bytes that was written to \a output. 185 186 \since Haiku R1 187*/ 188 189 190/*! 191 \class BRuntimeError 192 \ingroup netservices 193 \brief Advanced error object for runtime errors. 194 195 A \ref BRuntimeError is a concrete advanced error object that is used for 196 errors that happen during a program's execution and that by their nature 197 are outside of the scope of the control of the program. 198 199 Objects of this class store strings to the \em origin and the error 200 \em message. This class can be used as an error class or as a base to 201 create more specialized error types. 202 203 \since Haiku R1 204*/ 205 206 207/*! 208 \fn BRuntimeError::BRuntimeError(const char* origin, const char* message) 209 \brief Constructor for a new error object. 210 211 \param origin A string representing where this error occured. It is advised 212 to initialize it to \c __PRETTY_FUNCTION__ by default. 213 \param message A string explaining the contents for the error. While it is 214 generally geared towards the developer, it may be useful to make the 215 error understandable by a user, as they may sometimes see it. 216 217 \since Haiku R1 218*/ 219 220 221/*! 222 \fn BRuntimeError::BRuntimeError(const char* origin, BString message) 223 \copydoc BRuntimeError::BRuntimeError(const char* origin, const char* message) 224*/ 225 226 227/*! 228 \fn BRuntimeError::BRuntimeError(BString origin, BString message) 229 \copydoc BRuntimeError::BRuntimeError(const char* origin, const char* message) 230*/ 231 232 233/*! 234 \fn BRuntimeError::BRuntimeError(const BRuntimeError& other) 235 \brief Copy constructor. 236 237 \since Haiku R1 238*/ 239 240 241/*! 242 \fn BRuntimeError::BRuntimeError(BRuntimeError&& other) noexcept 243 \brief Move constructor. 244 245 \since Haiku R1 246*/ 247 248 249/*! 250 \fn BRuntimeError& BRuntimeError::operator=(const BRuntimeError& other) 251 \brief Copy assignment operator. 252 253 \since Haiku R1 254*/ 255 256 257/*! 258 \fn BRuntimeError& BRuntimeError::operator=(BRuntimeError&& other) noexcept 259 \brief Move assignment operator. 260 261 \since Haiku R1 262*/ 263 264 265/*! 266 \fn virtual const char* BRuntimeError::Message() const B_CXX_NOEXCEPT B_CXX_OVERRIDE 267 \brief Get a pointer to the message describing the runtime error. 268*/ 269 270 271/*! 272 \class BSystemError 273 \ingroup netservices 274 \brief Advanced error object that wrap low-level system errors. 275 276 A \ref BSystemError is a concrete advanced error object that is used to 277 wrap tradition errors that are usually returned as a \c status_t. This type 278 takes the system error, and adds an \em origin specifier. 279 280 \since Haiku R1 281*/ 282 283 284/*! 285 \fn BSystemError::BSystemError(const char* origin, status_t error) 286 \brief Create an object for \a error code with a specified \a origin. 287 288 \param origin A string representing where this error occured. As this 289 object usually wraps around a lower level API call, this should 290 usually be the call that the error code originated from. 291 \param error The error code. 292 293 \since Haiku R1 294*/ 295 296 297/*! 298 \fn BSystemError::BSystemError(BString origin, status_t error) 299 \copydoc BSystemError::BSystemError(const char* origin, status_t error) 300*/ 301 302 303/*! 304 \fn BSystemError::BSystemError(const BSystemError& other) 305 \brief Copy constructor. 306 307 \since Haiku R1 308*/ 309 310 311/*! 312 \fn BSystemError::BSystemError(BSystemError&& other) noexcept 313 \brief Move constructor. 314 315 \since Haiku R1 316*/ 317 318 319/*! 320 \fn BSystemError& BSystemError::operator=(const BSystemError& other) 321 \brief Copy assignment. 322 323 \since Haiku R1 324*/ 325 326 327/*! 328 \fn BSystemError& BSystemError::operator=(BSystemError&& other) noexcept 329 \brief Move assignment operator. 330 331 \since Haiku R1 332*/ 333 334 335/*! 336 \fn virtual const char* BSystemError::Message() const B_CXX_NOEXCEPT B_CXX_OVERRIDE 337 \brief Access the string representation of the message. 338 339 This returns the value of \c strerror() for the error code. 340 341 \since Haiku R1 342*/ 343 344 345/*! 346 \fn virtual BString BSystemError::DebugMessage() const B_CXX_OVERRIDE 347 \brief Retrieve a debug message that contains all info in this error. 348 349 \code 350 [Origin] Message of error (error code) 351 \endcode 352 353 \exception std::bad_alloc In the future this method may throw this 354 exception when the memory for the debug message cannot be allocated. 355 356 \return A \ref BString object that contains the debug message. 357 358 \since Haiku R1 359*/ 360 361 362/*! 363 \fn status_t BSystemError::Error() B_CXX_NOEXCEPT 364 \brief Get the error code for this error. 365 366 \since Haiku R1 367*/ 368 369 370} // namespace Network 371 372} // namespace BPrivate 373 374#endif 375