contrib/subversion/subversion/include/svn_checksum.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_checksum.h
  24  * @brief Subversion checksum routines
  25  */
  26
  27 #ifndef SVN_CHECKSUM_H
  28 #define SVN_CHECKSUM_H
  29
  30 #include <apr.h>        /* for apr_size_t */
  31 #include <apr_pools.h>  /* for apr_pool_t */
  32
  33 #include "svn_types.h"  /* for svn_boolean_t, svn_error_t */
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 \f
  40 /**
  41  * Various types of checksums.
  42  *
  43  * @since New in 1.6.
  44  */
  45 typedef enum svn_checksum_kind_t
  46 {
  47   /** The checksum is (or should be set to) an MD5 checksum. */
  48   svn_checksum_md5,
  49
  50   /** The checksum is (or should be set to) a SHA1 checksum. */
  51   svn_checksum_sha1
  52 } svn_checksum_kind_t;
  53
  54 /**
  55  * A generic checksum representation.
  56  *
  57  * @since New in 1.6.
  58  */
  59 typedef struct svn_checksum_t
  60 {
  61   /** The bytes of the checksum. */
  62   const unsigned char *digest;
  63
  64   /** The type of the checksum.  This should never be changed by consumers
  65       of the APIs. */
  66   svn_checksum_kind_t kind;
  67 } svn_checksum_t;
  68
  69 /**
  70  * Opaque type for creating checksums of data.
  71  */
  72 typedef struct svn_checksum_ctx_t svn_checksum_ctx_t;
  73
  74 /** Return a new checksum structure of type @a kind, initialized to the all-
  75  * zeros value, allocated in @a pool.
  76  *
  77  * @since New in 1.6.
  78  */
  79 svn_checksum_t *
  80 svn_checksum_create(svn_checksum_kind_t kind,
  81                     apr_pool_t *pool);
  82
  83 /** Set @a checksum->digest to all zeros, which, by convention, matches
  84  * all other checksums.
  85  *
  86  * @since New in 1.6.
  87  */
  88 svn_error_t *
  89 svn_checksum_clear(svn_checksum_t *checksum);
  90
  91 /** Compare checksums @a checksum1 and @a checksum2.  If their kinds do not
  92  * match or if neither is all zeros, and their content does not match, then
  93  * return FALSE; else return TRUE.
  94  *
  95  * @since New in 1.6.
  96  */
  97 svn_boolean_t
  98 svn_checksum_match(const svn_checksum_t *checksum1,
  99                    const svn_checksum_t *checksum2);
 100
 101
 102 /**
 103  * Return a deep copy of @a checksum, allocated in @a pool.  If @a
 104  * checksum is NULL then NULL is returned.
 105  *
 106  * @since New in 1.6.
 107  */
 108 svn_checksum_t *
 109 svn_checksum_dup(const svn_checksum_t *checksum,
 110                  apr_pool_t *pool);
 111
 112
 113 /** Return the hex representation of @a checksum, allocating the string
 114  * in @a pool.
 115  *
 116  * @since New in 1.6.
 117  */
 118 const char *
 119 svn_checksum_to_cstring_display(const svn_checksum_t *checksum,
 120                                 apr_pool_t *pool);
 121
 122
 123 /** Return the hex representation of @a checksum, allocating the
 124  * string in @a pool.  If @a checksum->digest is all zeros (that is,
 125  * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL
 126  * and NULL will be returned in that case.
 127  *
 128  * @since New in 1.6.
 129  * @note Passing NULL for @a checksum in 1.6 will cause a segfault.
 130  */
 131 const char *
 132 svn_checksum_to_cstring(const svn_checksum_t *checksum,
 133                         apr_pool_t *pool);
 134
 135
 136 /** Return a serialized representation of @a checksum, allocated in
 137  * @a result_pool. Temporary allocations are performed in @a scratch_pool.
 138  *
 139  * Note that @a checksum may not be NULL.
 140  *
 141  * @since New in 1.7.
 142  */
 143 const char *
 144 svn_checksum_serialize(const svn_checksum_t *checksum,
 145                        apr_pool_t *result_pool,
 146                        apr_pool_t *scratch_pool);
 147
 148
 149 /** Return @a checksum from the serialized format at @a data. The checksum
 150  * will be allocated in @a result_pool, with any temporary allocations
 151  * performed in @a scratch_pool.
 152  *
 153  * @since New in 1.7.
 154  */
 155 svn_error_t *
 156 svn_checksum_deserialize(const svn_checksum_t **checksum,
 157                          const char *data,
 158                          apr_pool_t *result_pool,
 159                          apr_pool_t *scratch_pool);
 160
 161
 162 /** Parse the hex representation @a hex of a checksum of kind @a kind and
 163  * set @a *checksum to the result, allocating in @a pool.
 164  *
 165  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
 166  * to @c NULL.
 167  *
 168  * @since New in 1.6.
 169  */
 170 svn_error_t *
 171 svn_checksum_parse_hex(svn_checksum_t **checksum,
 172                        svn_checksum_kind_t kind,
 173                        const char *hex,
 174                        apr_pool_t *pool);
 175
 176 /**
 177  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
 178  * at @a data, and going for @a len.  @a *checksum is allocated in @a pool.
 179  *
 180  * @since New in 1.6.
 181  */
 182 svn_error_t *
 183 svn_checksum(svn_checksum_t **checksum,
 184              svn_checksum_kind_t kind,
 185              const void *data,
 186              apr_size_t len,
 187              apr_pool_t *pool);
 188
 189
 190 /**
 191  * Return in @a pool a newly allocated checksum populated with the checksum
 192  * of type @a kind for the empty string.
 193  *
 194  * @since New in 1.6.
 195  */
 196 svn_checksum_t *
 197 svn_checksum_empty_checksum(svn_checksum_kind_t kind,
 198                             apr_pool_t *pool);
 199
 200
 201 /**
 202  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
 203  * calculating checksums of type @a kind.  @see svn_checksum_final()
 204  *
 205  * @since New in 1.6.
 206  */
 207 svn_checksum_ctx_t *
 208 svn_checksum_ctx_create(svn_checksum_kind_t kind,
 209                         apr_pool_t *pool);
 210
 211 /**
 212  * Update the checksum represented by @a ctx, with @a len bytes starting at
 213  * @a data.
 214  *
 215  * @since New in 1.6.
 216  */
 217 svn_error_t *
 218 svn_checksum_update(svn_checksum_ctx_t *ctx,
 219                     const void *data,
 220                     apr_size_t len);
 221
 222
 223 /**
 224  * Finalize the checksum used when creating @a ctx, and put the resultant
 225  * checksum in @a *checksum, allocated in @a pool.
 226  *
 227  * @since New in 1.6.
 228  */
 229 svn_error_t *
 230 svn_checksum_final(svn_checksum_t **checksum,
 231                    const svn_checksum_ctx_t *ctx,
 232                    apr_pool_t *pool);
 233
 234
 235 /**
 236  * Return the digest size of @a checksum.
 237  *
 238  * @since New in 1.6.
 239  */
 240 apr_size_t
 241 svn_checksum_size(const svn_checksum_t *checksum);
 242
 243 /**
 244  * Return @c TRUE iff @a checksum matches the checksum for the empty
 245  * string.
 246  *
 247  * @since New in 1.8.
 248  */
 249 svn_boolean_t
 250 svn_checksum_is_empty_checksum(svn_checksum_t *checksum);
 251
 252
 253 /**
 254  * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
 255  * @a expected checksums which do not match.  Use @a fmt, and the following
 256  * parameters to populate the error message.
 257  *
 258  * @note This function does not actually check for the mismatch, it just
 259  * constructs the error.
 260  *
 261  * @a scratch_pool is used for temporary allocations; the returned error
 262  * will be allocated in its own pool (as is typical).
 263  *
 264  * @since New in 1.7.
 265  */
 266 svn_error_t *
 267 svn_checksum_mismatch_err(const svn_checksum_t *expected,
 268                           const svn_checksum_t *actual,
 269                           apr_pool_t *scratch_pool,
 270                           const char *fmt,
 271                           ...)
 272   __attribute__ ((format(printf, 4, 5)));
 273
 274 #ifdef __cplusplus
 275 }
 276 #endif /* __cplusplus */
 277
 278 #endif /* SVN_CHECKSUM_H */