libs/glibmm2/glib/src/checksum.hg

   1 /* $Id$ */
   2
   3 /* Copyright (C) 2002 The gtkmm Development Team
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 _DEFS(glibmm,glib)
  21
  22 #include <glib.h>
  23 #include <string>
  24
  25 #ifndef DOXYGEN_SHOUD_SKIP_THIS
  26 extern "C" { typedef struct _GChecksum GChecksum; }
  27 #endif
  28
  29 namespace Glib
  30 {
  31
  32 /** Computes the checksum for data.
  33  * This is a generic API for computing checksums (or "digests") for a sequence of arbitrary bytes,
  34  * using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
  35  *
  36  * glibmm supports incremental checksums by calling update() as long as there's data available and then using get_string()
  37  * or get_digest() to compute the checksum and return it either as a string in hexadecimal form, or as a raw sequence of bytes.
  38  * To compute the checksum for binary blobs and NULL-terminated strings in one go, use the static compute_checksum() convenience functions().
  39  *
  40  * @newin2p16
  41  */
  42 class Checksum
  43 {
  44   _CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)
  45   _IGNORE(g_checksum_copy, g_checksum_free)
  46 public:
  47
  48   /**
  49    * @class ChecksumType:
  50    * @a CHECKSUM_MD5: Use the MD5 hashing algorithm
  51    * @a CHECKSUM_SHA1: Use the SHA-1 hashing algorithm
  52    * @a CHECKSUM_SHA256: Use the SHA-256 hashing algorithm
  53    *
  54    * The hashing algorithm to be used by Checksum when performing the
  55    * digest of some data.
  56    *
  57    * Note that the ChecksumType enumeration may be extended at a later
  58    * date to include new hashing algorithm types.
  59    *
  60    * @newin2p16
  61    */
  62   _WRAP_ENUM(ChecksumType, GChecksumType, NO_GTYPE)
  63
  64 #m4 _CONVERSION(`ChecksumType', `GChecksumType', `(($2)$3)')
  65
  66   /** Creates a new Checksum, using the checksum algorithm @a checksum_type.
  67    * If the checksum_type is not known, then operator bool() will return false.
  68    *
  69    * @param type checksum type, one of defined above.
  70    */
  71   explicit Checksum(ChecksumType checksum_type);
  72
  73   /** Returns true if the Checksum object is valid.
  74    * This will return false, for instance, if an unsupported checksum type was provided to the constructor.
  75    */
  76   operator bool() const;
  77
  78   _WRAP_METHOD(void reset(), g_checksum_reset)
  79
  80   _WRAP_METHOD(void update(const guchar* data, gsize length), g_checksum_update)
  81
  82   /** Feeds data into an existing Checksum.
  83    * The checksum must still be open, that is get_string() or get_digest() must not have been called on the checksum.
  84    *
  85    * @param data Buffer used to compute the checksum
  86    */
  87   void update(const std::string& data);
  88
  89   _WRAP_METHOD(void get_digest(guint8 *buffer, gsize *digest_len) const, g_checksum_get_digest)
  90
  91   _WRAP_METHOD(std::string get_string() const, g_checksum_get_string)
  92
  93
  94   _WRAP_METHOD(static std::string compute_checksum(ChecksumType type, const guchar* data, gsize length), g_compute_checksum_for_data)
  95
  96   /** Computes the checksum of a string.
  97    *
  98    * @param checksum_type A ChecksumType
  99    * @param str The string to compute the checksum of.
 100    * @result The checksum as a hexadecimal string.
 101    */
 102   static std::string compute_checksum(ChecksumType type, const std::string& str);
 103   _IGNORE(g_compute_checksum_for_string)
 104
 105
 106   //We don't use _WRAP_METHOD because this is not really a GCheckSum function:
 107   /** Gets the length in bytes of digests of type @a checksum_type.
 108    *
 109    * @param checksum_type A ChecksumType.
 110    * @result The checksum length, or -1 if @a checksum_type is not supported.
 111    */
 112   static gssize get_length(ChecksumType checksum_type);
 113 };
 114
 115 } //namespace Glib
 116