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 output 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* EncodeString(char* buf, ui32_t buf_len) const {
 280         return bin2UUIDhex(m_Value, Size(), buf, buf_len);
 281       }
 282
 283       inline const char* EncodeHex(char* buf, ui32_t buf_len) const {
 284         return bin2UUIDhex(m_Value, Size(), buf, buf_len);
 285       }
 286     };
 287
 288   void GenRandomUUID(byte_t* buf); // buf must be UUID_Length or longer
 289   void GenRandomValue(UUID&);
 290
 291   // a self-wiping key container
 292   //
 293   const ui32_t SymmetricKey_Length = 16;
 294   const byte_t NilKey[SymmetricKey_Length] = {
 295     0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce,
 296     0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce, 0xfa, 0xce
 297   };
 298
 299   class SymmetricKey : public Identifier<SymmetricKey_Length>
 300     {
 301     public:
 302       SymmetricKey() {}
 303       SymmetricKey(const byte_t* value) : Identifier<SymmetricKey_Length>(value) {}
 304       SymmetricKey(const UUID& rhs) : Identifier<SymmetricKey_Length>(rhs) {}
 305       virtual ~SymmetricKey() { memcpy(m_Value, NilKey, 16); m_HasValue = false; }
 306     };
 307
 308   void GenRandomValue(SymmetricKey&);
 309
 310   //
 311   // 2004-05-01T13:20:00-00:00
 312   const ui32_t DateTimeLen = 25; //  the number of chars in the xs:dateTime format (sans milliseconds)
 313
 314   // UTC time+date representation
 315   class Timestamp : public IArchive
 316     {
 317     public:
 318       ui16_t Year;
 319       ui8_t  Month;
 320       ui8_t  Day;
 321       ui8_t  Hour;
 322       ui8_t  Minute;
 323       ui8_t  Second;
 324
 325       Timestamp();
 326       Timestamp(const Timestamp& rhs);
 327       Timestamp(const char* datestr);
 328       virtual ~Timestamp();
 329
 330       const Timestamp& operator=(const Timestamp& rhs);
 331       bool operator<(const Timestamp& rhs) const;
 332       bool operator>(const Timestamp& rhs) const;
 333       bool operator==(const Timestamp& rhs) const;
 334       bool operator!=(const Timestamp& rhs) const;
 335
 336       // Write the timestamp value to the given buffer in the form 2004-05-01T13:20:00-00:00
 337       // returns 0 if the buffer is smaller than DateTimeLen
 338       const char* EncodeString(char* str_buf, ui32_t buf_len) const;
 339
 340       // decode and set value from string formatted by EncodeString
 341       bool        DecodeString(const char* datestr);
 342
 343       // Add the given number of days or hours to the timestamp value.
 344       // Values less than zero will cause the timestamp to decrease
 345       void AddDays(i32_t);
 346       void AddHours(i32_t);
 347
 348       // Read and write the timestamp value as a byte string having
 349       // the following format:
 350       // | 16 bits int, big-endian |    8 bits   |   8 bits  |   8 bits   |    8 bits    |    8 bits    |
 351       // |        Year A.D         | Month(1-12) | Day(1-31) | Hour(0-23) | Minute(0-59) | Second(0-59) |
 352       //
 353       virtual bool HasValue() const;
 354       virtual bool Archive(MemIOWriter* Writer) const;
 355       virtual bool Unarchive(MemIOReader* Reader);
 356     };
 357
 358   //
 359   class ByteString : public IArchive
 360     {
 361       KM_NO_COPY_CONSTRUCT(ByteString);
 362
 363     protected:
 364       byte_t* m_Data;          // pointer to memory area containing frame data
 365       ui32_t  m_Capacity;      // size of memory area pointed to by m_Data
 366       ui32_t  m_Length;        // length of byte string in memory area pointed to by m_Data
 367
 368     public:
 369       ByteString();
 370       ByteString(ui32_t cap);
 371       virtual ~ByteString();
 372
 373       // Sets the size of the internally allocated buffer.
 374       // Resets content Size to zero.
 375       Result_t Capacity(ui32_t cap);
 376
 377       Result_t Append(const ByteString&);
 378       Result_t Append(const byte_t* buf, ui32_t buf_len);
 379
 380       // returns the size of the buffer
 381       inline ui32_t  Capacity() const { return m_Capacity; }
 382
 383       // returns a const pointer to the essence data
 384       inline const byte_t* RoData() const { assert(m_Data); return m_Data; }
 385
 386       // returns a non-const pointer to the essence data
 387       inline byte_t* Data() { assert(m_Data); return m_Data; }
 388
 389       // set the length of the buffer's contents
 390       inline ui32_t  Length(ui32_t l) { return m_Length = l; }
 391
 392       // returns the length of the buffer's contents
 393       inline ui32_t  Length() const { return m_Length; }
 394
 395       // copy the given data into the ByteString, set Length value.
 396       // Returns error if the ByteString is too small.
 397       Result_t Set(const byte_t* buf, ui32_t buf_len);
 398
 399       inline virtual bool HasValue() const { return m_Length > 0; }
 400
 401       inline virtual bool Archive(MemIOWriter* Writer) const {
 402         assert(Writer);
 403         if ( ! Writer->WriteUi32BE(m_Length) ) return false;
 404         if ( ! Writer->WriteRaw(m_Data, m_Length) ) return false;
 405         return true;
 406       }
 407
 408       inline virtual bool Unarchive(MemIOReader* Reader) {
 409         assert(Reader);
 410         if ( ! Reader->ReadUi32BE(&m_Length) ) return false;
 411         if ( KM_FAILURE(Capacity(m_Length)) ) return false;
 412         if ( ! Reader->ReadRaw(m_Data, m_Length) ) return false;
 413         return true;
 414       }
 415     };
 416
 417 } // namespace Kumu
 418
 419
 420 #endif // _KM_UTIL_H_
 421
 422 //
 423 // end KM_util.h
 424 //