Subversion
svn_checksum.h
Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  *    Licensed to the Apache Software Foundation (ASF) under one
00005  *    or more contributor license agreements.  See the NOTICE file
00006  *    distributed with this work for additional information
00007  *    regarding copyright ownership.  The ASF licenses this file
00008  *    to you under the Apache License, Version 2.0 (the
00009  *    "License"); you may not use this file except in compliance
00010  *    with the License.  You may obtain a copy of the License at
00011  *
00012  *      http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  *    Unless required by applicable law or agreed to in writing,
00015  *    software distributed under the License is distributed on an
00016  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
00017  *    KIND, either express or implied.  See the License for the
00018  *    specific language governing permissions and limitations
00019  *    under the License.
00020  * ====================================================================
00021  * @endcopyright
00022  *
00023  * @file svn_checksum.h
00024  * @brief Subversion checksum routines
00025  */
00026 
00027 #ifndef SVN_CHECKSUM_H
00028 #define SVN_CHECKSUM_H
00029 
00030 #include <apr.h>        /* for apr_size_t */
00031 #include <apr_pools.h>  /* for apr_pool_t */
00032 
00033 #include "svn_types.h"  /* for svn_boolean_t, svn_error_t */
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif /* __cplusplus */
00038 
00039 
00040 /**
00041  * Various types of checksums.
00042  *
00043  * @since New in 1.6.
00044  */
00045 typedef enum svn_checksum_kind_t
00046 {
00047   /** The checksum is (or should be set to) an MD5 checksum. */
00048   svn_checksum_md5,
00049 
00050   /** The checksum is (or should be set to) a SHA1 checksum. */
00051   svn_checksum_sha1
00052 } svn_checksum_kind_t;
00053 
00054 /**
00055  * A generic checksum representation.
00056  *
00057  * @since New in 1.6.
00058  */
00059 typedef struct svn_checksum_t
00060 {
00061   /** The bytes of the checksum. */
00062   const unsigned char *digest;
00063 
00064   /** The type of the checksum.  This should never be changed by consumers
00065       of the APIs. */
00066   svn_checksum_kind_t kind;
00067 } svn_checksum_t;
00068 
00069 /**
00070  * Opaque type for creating checksums of data.
00071  */
00072 typedef struct svn_checksum_ctx_t svn_checksum_ctx_t;
00073 
00074 /** Return a new checksum structure of type @a kind, initialized to the all-
00075  * zeros value, allocated in @a pool.
00076  *
00077  * @since New in 1.6.
00078  */
00079 svn_checksum_t *
00080 svn_checksum_create(svn_checksum_kind_t kind,
00081                     apr_pool_t *pool);
00082 
00083 /** Set @a checksum->digest to all zeros, which, by convention, matches
00084  * all other checksums.
00085  *
00086  * @since New in 1.6.
00087  */
00088 svn_error_t *
00089 svn_checksum_clear(svn_checksum_t *checksum);
00090 
00091 /** Compare checksums @a checksum1 and @a checksum2.  If their kinds do not
00092  * match or if neither is all zeros, and their content does not match, then
00093  * return FALSE; else return TRUE.
00094  *
00095  * @since New in 1.6.
00096  */
00097 svn_boolean_t
00098 svn_checksum_match(const svn_checksum_t *checksum1,
00099                    const svn_checksum_t *checksum2);
00100 
00101 
00102 /**
00103  * Return a deep copy of @a checksum, allocated in @a pool.
00104  *
00105  * @since New in 1.6.
00106  */
00107 svn_checksum_t *
00108 svn_checksum_dup(const svn_checksum_t *checksum,
00109                  apr_pool_t *pool);
00110 
00111 
00112 /** Return the hex representation of @a checksum, allocating the string
00113  * in @a pool.
00114  *
00115  * @since New in 1.6.
00116  */
00117 const char *
00118 svn_checksum_to_cstring_display(const svn_checksum_t *checksum,
00119                                 apr_pool_t *pool);
00120 
00121 
00122 /** Return the hex representation of @a checksum, allocating the
00123  * string in @a pool.  If @a checksum->digest is all zeros (that is,
00124  * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL
00125  * and NULL will be returned in that case.
00126  *
00127  * @since New in 1.6.
00128  * @note Passing NULL for @a checksum in 1.6 will cause a segfault.
00129  */
00130 const char *
00131 svn_checksum_to_cstring(const svn_checksum_t *checksum,
00132                         apr_pool_t *pool);
00133 
00134 
00135 /** Return a serialized representation of @a checksum, allocated in
00136  * @a result_pool. Temporary allocations are performed in @a scratch_pool.
00137  *
00138  * Note that @a checksum may not be NULL.
00139  *
00140  * @since New in 1.7.
00141  */
00142 const char *
00143 svn_checksum_serialize(const svn_checksum_t *checksum,
00144                        apr_pool_t *result_pool,
00145                        apr_pool_t *scratch_pool);
00146 
00147 
00148 /** Return @a checksum from the serialized format at @a data. The checksum
00149  * will be allocated in @a result_pool, with any temporary allocations
00150  * performed in @a scratch_pool.
00151  *
00152  * @since New in 1.7.
00153  */
00154 svn_error_t *
00155 svn_checksum_deserialize(const svn_checksum_t **checksum,
00156                          const char *data,
00157                          apr_pool_t *result_pool,
00158                          apr_pool_t *scratch_pool);
00159 
00160 
00161 /** Parse the hex representation @a hex of a checksum of kind @a kind and
00162  * set @a *checksum to the result, allocating in @a pool.
00163  *
00164  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
00165  * to @c NULL.
00166  *
00167  * @since New in 1.6.
00168  */
00169 svn_error_t *
00170 svn_checksum_parse_hex(svn_checksum_t **checksum,
00171                        svn_checksum_kind_t kind,
00172                        const char *hex,
00173                        apr_pool_t *pool);
00174 
00175 /**
00176  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
00177  * at @a data, and going for @a len.  @a *checksum is allocated in @a pool.
00178  *
00179  * @since New in 1.6.
00180  */
00181 svn_error_t *
00182 svn_checksum(svn_checksum_t **checksum,
00183              svn_checksum_kind_t kind,
00184              const void *data,
00185              apr_size_t len,
00186              apr_pool_t *pool);
00187 
00188 
00189 /**
00190  * Return in @a pool a newly allocated checksum populated with the checksum
00191  * of type @a kind for the empty string.
00192  *
00193  * @since New in 1.6.
00194  */
00195 svn_checksum_t *
00196 svn_checksum_empty_checksum(svn_checksum_kind_t kind,
00197                             apr_pool_t *pool);
00198 
00199 
00200 /**
00201  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
00202  * calculating checksums of type @a kind.  @see svn_checksum_final()
00203  *
00204  * @since New in 1.6.
00205  */
00206 svn_checksum_ctx_t *
00207 svn_checksum_ctx_create(svn_checksum_kind_t kind,
00208                         apr_pool_t *pool);
00209 
00210 /**
00211  * Update the checksum represented by @a ctx, with @a len bytes starting at
00212  * @a data.
00213  *
00214  * @since New in 1.6.
00215  */
00216 svn_error_t *
00217 svn_checksum_update(svn_checksum_ctx_t *ctx,
00218                     const void *data,
00219                     apr_size_t len);
00220 
00221 
00222 /**
00223  * Finalize the checksum used when creating @a ctx, and put the resultant
00224  * checksum in @a *checksum, allocated in @a pool.
00225  *
00226  * @since New in 1.6.
00227  */
00228 svn_error_t *
00229 svn_checksum_final(svn_checksum_t **checksum,
00230                    const svn_checksum_ctx_t *ctx,
00231                    apr_pool_t *pool);
00232 
00233 
00234 /**
00235  * Return the digest size of @a checksum.
00236  *
00237  * @since New in 1.6.
00238  */
00239 apr_size_t
00240 svn_checksum_size(const svn_checksum_t *checksum);
00241 
00242 
00243 /**
00244  * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
00245  * @a expected checksums which do not match.  Use @a fmt, and the following
00246  * parameters to populate the error message.
00247  *
00248  * @note This function does not actually check for the mismatch, it just
00249  * constructs the error.
00250  *
00251  * @a scratch_pool is used for temporary allocations; the returned error
00252  * will be allocated in its own pool (as is typical).
00253  *
00254  * @since New in 1.7.
00255  */
00256 svn_error_t *
00257 svn_checksum_mismatch_err(const svn_checksum_t *expected,
00258                           const svn_checksum_t *actual,
00259                           apr_pool_t *scratch_pool,
00260                           const char *fmt,
00261                           ...)
00262   __attribute__ ((format(printf, 4, 5)));
00263 
00264 
00265 /**
00266  * Internal function for creating a checksum from a binary digest.
00267  *
00268  * @since New in 1.6
00269  */
00270 svn_checksum_t *
00271 svn_checksum__from_digest(const unsigned char *digest,
00272                           svn_checksum_kind_t kind,
00273                           apr_pool_t *result_pool);
00274 
00275 
00276 #ifdef __cplusplus
00277 }
00278 #endif /* __cplusplus */
00279 
00280 #endif /* SVN_CHECKSUM_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines