src/KM_util.h

   1 /*
   2 Copyright (c) 2005-2006, John Hurst
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions
   7 are met:
   8 1. Redistributions of source code must retain the above copyright
   9    notice, this list of conditions and the following disclaimer.
  10 2. Redistributions in binary form must reproduce the above copyright
  11    notice, this list of conditions and the following disclaimer in the
  12    documentation and/or other materials provided with the distribution.
  13 3. The name of the author may not be used to endorse or promote products
  14    derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27   /*! \file    KM_util.h
  28     \version $Id$
  29     \brief   Utility functions
  30   */
  31
  32 #ifndef _KM_UTIL_H_
  33 #define _KM_UTIL_H_
  34
  35 #include <KM_memio.h>
  36 #include <KM_error.h>
  37 #include <string.h>
  38 #include <string>
  39
  40 namespace Kumu
  41 {
  42
  43   // a class that represents the string form of a value
  44   template <class T, int SIZE = 16>
  45     class IntPrinter : public std::string
  46   {
  47     KM_NO_COPY_CONSTRUCT(IntPrinter);
  48     IntPrinter();
  49
  50     protected:
  51     const char* m_format;
  52     char m_strbuf[SIZE];
  53
  54     public:
  55     IntPrinter(const char* format, T value) {
  56       assert(format);
  57       m_format = format;
  58       snprintf(m_strbuf, SIZE, m_format, value);
  59     }
  60
  61     inline operator const char*() { return m_strbuf; }
  62     inline const char* c_str() { return m_strbuf; }
  63     inline const char* set_value(T value) {
  64       snprintf(m_strbuf, SIZE, m_format, value);
  65       return m_strbuf;
  66     }
  67   };
  68
  69   struct i8Printer : public IntPrinter<i8_t> {
  70     i8Printer(i8_t value) : IntPrinter<i8_t>("%hd", value) {}
  71   };
  72
  73   struct ui8Printer : public IntPrinter<ui8_t> {
  74     ui8Printer(ui8_t value) : IntPrinter<ui8_t>("%hu", value) {}
  75   };
  76
  77   struct i16Printer : public IntPrinter<i16_t> {
  78     i16Printer(i16_t value) : IntPrinter<i16_t>("%hd", value) {}
  79   };
  80
  81   struct ui16Printer : public IntPrinter<ui16_t> {
  82     ui16Printer(ui16_t value) : IntPrinter<ui16_t>("%hu", value) {}
  83   };
  84
  85   struct i32Printer : public IntPrinter<i32_t> {
  86     i32Printer(i32_t value) : IntPrinter<i32_t>("%d", value) {}
  87   };
  88
  89   struct ui32Printer : public IntPrinter<ui32_t> {
  90     ui32Printer(ui32_t value) : IntPrinter<ui32_t>("%u", value) {}
  91   };
  92
  93 #ifdef KM_WIN32
  94   struct i64Printer : public IntPrinter<i64_t, 32> {
  95     i64Printer(i64_t value) : IntPrinter<i64_t, 32>("%I64d", value) {}
  96   };
  97
  98   struct ui64Printer : public IntPrinter<ui64_t, 32> {
  99     ui64Printer(ui64_t value) : IntPrinter<ui64_t, 32>("%I64u", value) {}
 100   };
 101 #else
 102   struct i64Printer : public IntPrinter<i64_t, 32> {
 103     i64Printer(i64_t value) : IntPrinter<i64_t, 32>("%qd", value) {}
 104   };
 105
 106   struct ui64Printer : public IntPrinter<ui64_t, 32> {
 107     ui64Printer(ui64_t value) : IntPrinter<ui64_t, 32>("%qu", value) {}
 108   };
 109 #endif
 110
 111   // Convert NULL-terminated UTF-8 hexadecimal string to binary, returns 0 if
 112   // the binary buffer was large enough to hold the result. The output parameter
 113   // 'char_count' will contain the length of the converted string. If the output
 114   // buffer is too small or any of the pointer arguments are NULL, the subroutine
 115   // will return -1 and set 'char_count' to the required buffer size. No data will
 116   // be written to 'buf' if the subroutine fails.
 117   i32_t       hex2bin(const char* str, byte_t* buf, ui32_t buf_len, ui32_t* char_count);
 118
 119   // Convert a binary string to NULL-terminated UTF-8 hexadecimal, returns the buffer
 120   // if the binary buffer was large enough to hold the result. If the output buffer
 121   // is too small or any of the pointer arguments are NULL, the subroutine will
 122   // return 0.
 123   //
 124   const char* bin2hex(const byte_t* bin_buf, ui32_t bin_len, char* str_buf, ui32_t str_len);
 125
 126   const char* bin2UUIDhex(const byte_t* bin_buf, ui32_t bin_len, char* str_buf, ui32_t str_len);
 127
 128   // same as above for base64 text
 129   i32_t       base64decode(const char* str, byte_t* buf, ui32_t buf_len, ui32_t* char_count);
 130   const char* base64encode(const byte_t* bin_buf, ui32_t bin_len, char* str_buf, ui32_t str_len);
 131
 132   // returns the length of a Base64 encoding of a buffer of the given length
 133   inline ui32_t base64_encode_length(ui32_t length) {
 134     while ( ( length % 3 ) != 0 )
 135       length++;
 136
 137     return ( length / 3 ) * 4;
 138   }
 139
 140   // print buffer contents to a stream as hexadecimal values in numbered
 141   // rows of 16-bytes each.
 142   //
 143   void hexdump(const byte_t* buf, ui32_t dump_len, FILE* stream = 0);
 144
 145   // Return the length in bytes of a BER encoded value
 146   inline ui32_t BER_length(const byte_t* buf)
 147     {
 148       if ( buf == 0 || (*buf & 0xf0) != 0x80 )
 149         return 0;
 150
 151       return (*buf & 0x0f) + 1;
 152     }
 153
 154   // read a BER value
 155   bool read_BER(const byte_t* buf, ui64_t* val);
 156
 157   // decode a ber value and compare it to a test value
 158   bool read_test_BER(byte_t **buf, ui64_t test_value);
 159
 160   // create BER encoding of integer value
 161   bool write_BER(byte_t* buf, ui64_t val, ui32_t ber_len = 0);
 162
 163   //----------------------------------------------------------------
 164   //
 165
 166   // an abstract base class that objects implement to serialize state
 167   // to and from a binary stream.
 168   class IArchive
 169     {
 170     public:
 171       virtual ~IArchive(){}
 172       virtual bool HasValue() const = 0;
 173       virtual bool Archive(MemIOWriter* Writer) const = 0;
 174       virtual bool Unarchive(MemIOReader* Reader) = 0;
 175     };
 176
 177
 178   //
 179   // the base of all identifier classes, Identifier is not usually used directly
 180   // see UUID and SymmetricKey below for more detail.
 181   //
 182   template <ui32_t SIZE>
 183     class Identifier : public IArchive
 184     {
 185     protected:
 186       bool   m_HasValue;
 187       byte_t m_Value[SIZE];
 188
 189     public:
 190       Identifier() : m_HasValue(false) { memset(m_Value, 0, SIZE); }
 191       Identifier(const byte_t* value) : m_HasValue(true) { memcpy(m_Value, value, SIZE); }
 192       Identifier(const Identifier& rhs) {
 193         m_HasValue = rhs.m_HasValue;
 194         memcpy(m_Value, rhs.m_Value, SIZE);
 195       }
 196
 197       virtual ~Identifier() {}
 198
 199       const Identifier& operator=(const Identifier& rhs) {
 200         m_HasValue = rhs.m_HasValue;
 201         memcpy(m_Value, rhs.m_Value, SIZE);
 202         return *this;
 203       }
 204
 205       inline void Set(const byte_t* value) { m_HasValue = true; memcpy(m_Value, value, SIZE); }
 206       inline const byte_t* Value() const { return m_Value; }
 207       inline ui32_t Size() const { return SIZE; }
 208
 209       inline bool operator<(const Identifier& rhs) const {
 210         ui32_t test_size = xmin(rhs.Size(), SIZE);
 211
 212         for ( ui32_t i = 0; i < test_size; i++ )
 213           {
 214             if ( m_Value[i] != rhs.m_Value[i] )
 215               return m_Value[i] < rhs.m_Value[i];
 216           }
 217
 218         return false;
 219       }
 220
 221       inline bool operator==(const Identifier& rhs) const {
 222         if ( rhs.Size() != SIZE ) return false;
 223         return ( memcmp(m_Value, rhs.m_Value, SIZE) == 0 );
 224       }
 225
 226       inline bool operator!=(const Identifier& rhs) const {
 227         if ( rhs.Size() != SIZE ) return true;
 228         return ( memcmp(m_Value, rhs.m_Value, SIZE) != 0 );
 229       }
 230
 231       inline bool DecodeHex(const char* str) {
 232         ui32_t char_count;
 233         m_HasValue = ( hex2bin(str, m_Value, SIZE, &char_count) == 0 );
 234         return m_HasValue;
 235       }
 236
 237       inline const char* EncodeHex(char* buf, ui32_t buf_len) const {
 238         return bin2hex(m_Value, SIZE, buf, buf_len);
 239       }
 240
 241       inline const char* EncodeString(char* str_buf, ui32_t buf_len) const {
 242         return EncodeHex(str_buf, buf_len);
 243       }
 244
 245       inline bool DecodeBase64(const char* str) {
 246         ui32_t char_count;
 247         m_HasValue = ( base64decode(str, m_Value, SIZE, &char_count) == 0 );
 248         return m_HasValue;
 249       }
 250
 251       inline const char* EncodeBase64(char* buf, ui32_t buf_len) const {
 252         return base64encode(m_Value, SIZE, buf, buf_len);
 253       }
 254
 255       inline bool HasValue() const { return m_HasValue; }
 256
 257       inline bool Unarchive(Kumu::MemIOReader* Reader) {
 258         m_HasValue = Reader->ReadRaw(m_Value, SIZE);
 259         return m_HasValue;
 260       }
 261
 262       inline bool Archive(Kumu::MemIOWriter* Writer) const {
 263         return Writer->WriteRaw(m_Value, SIZE);
 264       }
 265     };
 266
 267
 268   // UUID
 269   //
 270   const ui32_t UUID_Length = 16;
 271   class UUID : public Identifier<UUID_Length>
 272     {
 273     public:
 274       UUID() {}
 275       UUID(const byte_t* value) : Identifier<UUID_Length>(value) {}
 276       UUID(const UUID& rhs) : Identifier<UUID_Length>(rhs) {}
 277       virtual ~UUID() {}
 278
 279       inline const char* EncodeHex(char* buf, ui32_t buf_len) const {
 280         return bin2UUIDhex(m_Value, Size(), buf, buf_len);
 281       }
 282     };
 283
 284   void GenRandomUUID(byte_t* buf); // buf must be UUID_Length or longer
 285   void GenRandomValue(UUID&);
 286
 287   // a self-wiping key container
 288   //
 289   const ui32_t SymmetricKey_Length = 16;
 290   const byte_t NilKey[SymmetricKey_Length] = {
 291     0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce,
 292     0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce
 293   };
 294
 295   class SymmetricKey : public Identifier<SymmetricKey_Length>
 296     {
 297     public:
 298       SymmetricKey() {}
 299       SymmetricKey(const byte_t* value) : Identifier<SymmetricKey_Length>(value) {}
 300       SymmetricKey(const UUID& rhs) : Identifier<SymmetricKey_Length>(rhs) {}
 301       virtual ~SymmetricKey() { memcpy(m_Value, NilKey, 16); m_HasValue = false; }
 302     };
 303
 304   void GenRandomValue(SymmetricKey&);
 305
 306   //
 307   // 2004-05-01T13:20:00-00:00
 308   const ui32_t DateTimeLen = 25; //  the number of chars in the xs:dateTime format (sans milliseconds)
 309
 310   // UTC time+date representation
 311   class Timestamp : public IArchive
 312     {
 313     public:
 314       ui16_t Year;
 315       ui8_t  Month;
 316       ui8_t  Day;
 317       ui8_t  Hour;
 318       ui8_t  Minute;
 319       ui8_t  Second;
 320
 321       Timestamp();
 322       Timestamp(const Timestamp& rhs);
 323       Timestamp(const char* datestr);
 324       virtual ~Timestamp();
 325
 326       const Timestamp& operator=(const Timestamp& rhs);
 327       bool operator<(const Timestamp& rhs) const;
 328       bool operator==(const Timestamp& rhs) const;
 329       bool operator!=(const Timestamp& rhs) const;
 330
 331       // Write the timestamp value to the given buffer in the form 2004-05-01T13:20:00-00:00
 332       // returns 0 if the buffer is smaller than DateTimeLen
 333       const char* EncodeString(char* str_buf, ui32_t buf_len) const;
 334
 335       // decode and set value from string formatted by EncodeString
 336       bool        DecodeString(const char* datestr);
 337
 338       // Add the given number of days or hours to the timestamp value.
 339       // Values less than zero will cause the timestamp to decrease
 340       void AddDays(i32_t);
 341       void AddHours(i32_t);
 342
 343       // Read and write the timestamp value as a byte string having
 344       // the following format:
 345       // | 16 bits int, big-endian |    8 bits   |   8 bits  |   8 bits   |    8 bits    |    8 bits    |
 346       // |        Year A.D         | Month(1-12) | Day(1-31) | Hour(0-23) | Minute(0-59) | Second(0-59) |
 347       //
 348       virtual bool HasValue() const;
 349       virtual bool Archive(MemIOWriter* Writer) const;
 350       virtual bool Unarchive(MemIOReader* Reader);
 351     };
 352
 353   //
 354   class ByteString : public IArchive
 355     {
 356       KM_NO_COPY_CONSTRUCT(ByteString);
 357
 358     protected:
 359       byte_t* m_Data;          // pointer to memory area containing frame data
 360       ui32_t  m_Capacity;      // size of memory area pointed to by m_Data
 361       ui32_t  m_Length;        // length of byte string in memory area pointed to by m_Data
 362
 363     public:
 364       ByteString();
 365       ByteString(ui32_t cap);
 366       virtual ~ByteString();
 367
 368       // Sets the size of the internally allocated buffer.
 369       // Resets content Size to zero.
 370       Result_t Capacity(ui32_t cap);
 371
 372       Result_t Append(const ByteString&);
 373       Result_t Append(const byte_t* buf, ui32_t buf_len);
 374
 375       // returns the size of the buffer
 376       inline ui32_t  Capacity() const { return m_Capacity; }
 377
 378       // returns a const pointer to the essence data
 379       inline const byte_t* RoData() const { return m_Data; }
 380
 381       // returns a non-const pointer to the essence data
 382       inline byte_t* Data() { return m_Data; }
 383
 384       // set the length of the buffer's contents
 385       inline ui32_t  Length(ui32_t l) { return m_Length = l; }
 386
 387       // returns the length of the buffer's contents
 388       inline ui32_t  Length() const { return m_Length; }
 389
 390       // copy the given data into the ByteString, set Length value.
 391       // Returns error if the ByteString is too small.
 392       Result_t Set(const byte_t* buf, ui32_t buf_len);
 393
 394       inline virtual bool HasValue() const { return m_Length > 0; }
 395
 396       inline virtual bool Archive(MemIOWriter* Writer) const {
 397         assert(Writer);
 398         if ( ! Writer->WriteUi32BE(m_Length) ) return false;
 399         if ( ! Writer->WriteRaw(m_Data, m_Length) ) return false;
 400         return true;
 401       }
 402
 403       inline virtual bool Unarchive(MemIOReader* Reader) {
 404         assert(Reader);
 405         if ( ! Reader->ReadUi32BE(&m_Length) ) return false;
 406         if ( KM_FAILURE(Capacity(m_Length)) ) return false;
 407         if ( ! Reader->ReadRaw(m_Data, m_Length) ) return false;
 408         return true;
 409       }
 410     };
 411
 412 } // namespace Kumu
 413
 414
 415 #endif // _KM_UTIL_H_
 416
 417 //
 418 // end KM_util.h
 419 //