Subversion 1.6.16

svn_checksum.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2008 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_checksum.h
00019  * @brief Subversion checksum routines
00020  */
00021 
00022 #ifndef SVN_CHECKSUM_H
00023 #define SVN_CHECKSUM_H
00024 
00025 #include <apr.h>        /* for apr_size_t */
00026 #include <apr_pools.h>  /* for apr_pool_t */
00027 
00028 #include "svn_types.h"  /* for svn_boolean_t, svn_error_t */
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif /* __cplusplus */
00033 
00034 
00035 /**
00036  * Various types of checksums.
00037  *
00038  * @since New in 1.6.
00039  */
00040 typedef enum
00041 {
00042   /** The checksum is (or should be set to) an MD5 checksum. */
00043   svn_checksum_md5,
00044 
00045   /** The checksum is (or should be set to) a SHA1 checksum. */
00046   svn_checksum_sha1
00047 } svn_checksum_kind_t;
00048 
00049 /**
00050  * A generic checksum representation.
00051  *
00052  * @since New in 1.6.
00053  */
00054 typedef struct svn_checksum_t
00055 {
00056   /** The bytes of the checksum. */
00057   const unsigned char *digest;
00058 
00059   /** The type of the checksum.  This should never be changed by consumers
00060       of the APIs. */
00061   svn_checksum_kind_t kind;
00062 } svn_checksum_t;
00063 
00064 /**
00065  * Opaque type for creating checksums of data.
00066  */
00067 typedef struct svn_checksum_ctx_t svn_checksum_ctx_t;
00068 
00069 /** Return a new checksum structure of type @a kind, initialized to the all-
00070  * zeros value, allocated in @a pool.
00071  *
00072  * @since New in 1.6.
00073  */
00074 svn_checksum_t *
00075 svn_checksum_create(svn_checksum_kind_t kind,
00076                     apr_pool_t *pool);
00077 
00078 /** Set @c checksum->digest to all zeros, which, by convention, matches
00079  * all other checksums.
00080  *
00081  * @since New in 1.6.
00082  */
00083 svn_error_t *
00084 svn_checksum_clear(svn_checksum_t *checksum);
00085 
00086 /** Compare checksums @a checksum1 and @a checksum2.  If their kinds do not
00087  * match or if neither is all zeros, and their content does not match, then
00088  * return FALSE; else return TRUE.
00089  *
00090  * @since New in 1.6.
00091  */
00092 svn_boolean_t
00093 svn_checksum_match(const svn_checksum_t *checksum1,
00094                    const svn_checksum_t *checksum2);
00095 
00096 
00097 /**
00098  * Return a deep copy of @a checksum, allocated in @a pool.
00099  *
00100  * @since New in 1.6.
00101  */
00102 svn_checksum_t *
00103 svn_checksum_dup(const svn_checksum_t *checksum,
00104                  apr_pool_t *pool);
00105 
00106 
00107 /** Return the hex representation of @a checksum, allocating the string
00108  * in @a pool.
00109  *
00110  * @since New in 1.6.
00111  */
00112 const char *
00113 svn_checksum_to_cstring_display(const svn_checksum_t *checksum,
00114                                 apr_pool_t *pool);
00115 
00116 
00117 /** Return the hex representation of @a checksum, allocating the
00118  * string in @a pool.  If @a checksum->digest is all zeros (that is,
00119  * 0, not '0'), then return NULL.
00120  *
00121  * @since New in 1.6.
00122  */
00123 const char *
00124 svn_checksum_to_cstring(const svn_checksum_t *checksum,
00125                         apr_pool_t *pool);
00126 
00127 
00128 /** Parse the hex representation @a hex of a checksum of kind @a kind and
00129  * set @a *checksum to the result, allocating in @a pool.
00130  *
00131  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
00132  * to @c NULL.
00133  *
00134  * @since New in 1.6.
00135  */
00136 svn_error_t *
00137 svn_checksum_parse_hex(svn_checksum_t **checksum,
00138                        svn_checksum_kind_t kind,
00139                        const char *hex,
00140                        apr_pool_t *pool);
00141 
00142 /**
00143  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
00144  * at @a data, and going for @a len.  @a *checksum is allocated in @a pool.
00145  *
00146  * @since New in 1.6.
00147  */
00148 svn_error_t *
00149 svn_checksum(svn_checksum_t **checksum,
00150              svn_checksum_kind_t kind,
00151              const void *data,
00152              apr_size_t len,
00153              apr_pool_t *pool);
00154 
00155 
00156 /**
00157  * Return in @a pool a newly allocated checksum populated with the checksum
00158  * of type @a kind for the empty string.
00159  *
00160  * @since New in 1.6.
00161  */
00162 svn_checksum_t *
00163 svn_checksum_empty_checksum(svn_checksum_kind_t kind,
00164                             apr_pool_t *pool);
00165 
00166 
00167 /**
00168  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
00169  * calculating checksums of type @a kind.  @see svn_checksum_final()
00170  *
00171  * @since New in 1.6.
00172  */
00173 svn_checksum_ctx_t *
00174 svn_checksum_ctx_create(svn_checksum_kind_t kind,
00175                         apr_pool_t *pool);
00176 
00177 /**
00178  * Update the checksum represented by @a ctx, with @a len bytes starting at
00179  * @a data.
00180  *
00181  * @since New in 1.6.
00182  */
00183 svn_error_t *
00184 svn_checksum_update(svn_checksum_ctx_t *ctx,
00185                     const void *data,
00186                     apr_size_t len);
00187 
00188 
00189 /**
00190  * Finalize the checksum used when creating @a ctx, and put the resultant
00191  * checksum in @a *checksum, allocated in @a pool.
00192  *
00193  * @since New in 1.6.
00194  */
00195 svn_error_t *
00196 svn_checksum_final(svn_checksum_t **checksum,
00197                    const svn_checksum_ctx_t *ctx,
00198                    apr_pool_t *pool);
00199 
00200 
00201 /**
00202  * Return the digest size of @a checksum.
00203  *
00204  * @since New in 1.6.
00205  */
00206 apr_size_t
00207 svn_checksum_size(const svn_checksum_t *checksum);
00208 
00209 
00210 /**
00211  * Internal function for creating a checksum from a binary digest.
00212  *
00213  * @since New in 1.6
00214  */
00215 svn_checksum_t *
00216 svn_checksum__from_digest(const unsigned char *digest,
00217                           svn_checksum_kind_t kind,
00218                           apr_pool_t *result_pool);
00219 
00220 
00221 #ifdef __cplusplus
00222 }
00223 #endif /* __cplusplus */
00224 
00225 #endif /* SVN_CHECKSUM_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines