src/security/Io.h

   1 /*
   2  * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_SRC_SECURITY_IO_H
  10 #define SQUID_SRC_SECURITY_IO_H
  11
  12 #include "comm/forward.h"
  13 #include "security/ErrorDetail.h"
  14 #include "security/forward.h"
  15
  16 namespace Security {
  17
  18 /// a summary a TLS I/O operation outcome
  19 class IoResult: public RefCountable {
  20 public:
  21     typedef RefCount<IoResult> Pointer;
  22
  23     /// all possible outcome cases
  24     typedef enum { ioSuccess, ioWantRead, ioWantWrite, ioError } Category;
  25
  26     explicit IoResult(const Category aCategory): category(aCategory) {}
  27     explicit IoResult(const ErrorDetailPointer &anErrorDetail): errorDetail(anErrorDetail) {}
  28     IoResult(const IoResult &aRes) = default;
  29
  30     /// convenience wrapper to detect successful I/O outcome; implies !wantsIo()
  31     bool successful() const { return category == ioSuccess; }
  32
  33     /// convenience wrapper to detect whether more I/O is needed
  34     bool wantsIo() const { return category == ioWantRead || category == ioWantWrite; }
  35
  36     void print(std::ostream &os) const;
  37
  38     ErrorDetailPointer errorDetail; ///< ioError case details (or nil)
  39
  40     Category category = ioError; ///< primary outcome classification
  41
  42     /* the data members below facilitate human-friendly debugging */
  43     const char *errorDescription = nullptr; ///< a brief description of an error
  44     bool important = false; ///< whether the error was serious/unusual
  45 };
  46
  47 inline std::ostream &
  48 operator <<(std::ostream &os, const IoResult &result)
  49 {
  50     result.print(os);
  51     return os;
  52 }
  53
  54 /// accept a TLS connection over the specified to-Squid transport connection
  55 IoResult Accept(Comm::Connection &transport);
  56
  57 /// establish a TLS connection over the specified from-Squid transport connection
  58 IoResult Connect(Comm::Connection &transport);
  59
  60 /// clear any errors that a TLS library has accumulated in its global storage
  61 void ForgetErrors();
  62
  63 } // namespace Security
  64
  65 #endif /* SQUID_SRC_SECURITY_IO_H */
  66