- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# 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