Source/cmProcessOutput.h

   1 /* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2    file Copyright.txt or https://cmake.org/licensing for details.  */
   3 #pragma once
   4
   5 #include "cmConfigure.h" // IWYU pragma: keep
   6
   7 #include <cstddef>
   8 #include <string>
   9 #include <vector>
  10
  11 /** \class cmProcessOutput
  12  * \brief Decode text data to internal encoding.
  13  *
  14  * cmProcessOutput is used to decode text output from external process
  15  * using external encoding to our internal encoding.
  16  */
  17 class cmProcessOutput
  18 {
  19 public:
  20   enum Encoding
  21   {
  22     None,
  23     Auto,
  24     UTF8,
  25     ANSI,
  26     OEM
  27   };
  28
  29   /**
  30    * Find encoding enum value for given encoding \a name.
  31    * \param name a encoding name.
  32    * \return encoding enum value or Auto if \a name was not found.
  33    */
  34   static Encoding FindEncoding(std::string const& name);
  35
  36   /// The code page that is used as internal encoding to which we will encode.
  37   static unsigned int defaultCodepage;
  38
  39   /**
  40    * A class constructor.
  41    * \param encoding external process encoding from which we will decode.
  42    * \param maxSize a maximal size for process output buffer. It should match
  43    * to KWSYSPE_PIPE_BUFFER_SIZE. If text we decode is same size as \a maxSize
  44    * then we will check for incomplete character at end of buffer and
  45    * we will not return last incomplete character. This character will be
  46    * returned with next DecodeText() call. To disable this behavior specify
  47    * 0 as \a maxSize.
  48    */
  49   cmProcessOutput(Encoding encoding = Auto, unsigned int maxSize = 1024);
  50   ~cmProcessOutput() = default;
  51   /**
  52    * Decode \a raw string using external encoding to internal
  53    * encoding in \a decoded.
  54    * \a id specifies which internal buffer to use. This is important when we
  55    * are decoding both stdout and stderr from process output and we need to
  56    * keep incomplete characters in separate buffers for each stream.
  57    * \return true if successfully decoded \a raw to \a decoded or false if not.
  58    */
  59   bool DecodeText(std::string raw, std::string& decoded, size_t id = 0);
  60   /**
  61    * Decode \a data with \a length from external encoding to internal
  62    * encoding in \a decoded.
  63    * \param data a pointer to process output text data.
  64    * \param length a size of data buffer.
  65    * \param decoded a string which will contain decoded text.
  66    * \param id an internal buffer id to use.
  67    * \return true if successfully decoded \a data to \a decoded or false if
  68    * not.
  69    */
  70   bool DecodeText(const char* data, size_t length, std::string& decoded,
  71                   size_t id = 0);
  72   /**
  73    * \overload
  74    */
  75   bool DecodeText(std::vector<char> raw, std::vector<char>& decoded,
  76                   size_t id = 0);
  77
  78 private:
  79 #if defined(_WIN32)
  80   unsigned int codepage;
  81   unsigned int bufferSize;
  82   std::vector<std::string> rawparts;
  83   bool DoDecodeText(std::string raw, std::string& decoded, wchar_t* lastChar);
  84 #endif
  85 };