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. If @a 00104 * checksum is NULL then NULL is returned. 00105 * 00106 * @since New in 1.6. 00107 */ 00108 svn_checksum_t * 00109 svn_checksum_dup(const svn_checksum_t *checksum, 00110 apr_pool_t *pool); 00111 00112 00113 /** Return the hex representation of @a checksum, allocating the string 00114 * in @a pool. 00115 * 00116 * @since New in 1.6. 00117 */ 00118 const char * 00119 svn_checksum_to_cstring_display(const svn_checksum_t *checksum, 00120 apr_pool_t *pool); 00121 00122 00123 /** Return the hex representation of @a checksum, allocating the 00124 * string in @a pool. If @a checksum->digest is all zeros (that is, 00125 * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL 00126 * and NULL will be returned in that case. 00127 * 00128 * @since New in 1.6. 00129 * @note Passing NULL for @a checksum in 1.6 will cause a segfault. 00130 */ 00131 const char * 00132 svn_checksum_to_cstring(const svn_checksum_t *checksum, 00133 apr_pool_t *pool); 00134 00135 00136 /** Return a serialized representation of @a checksum, allocated in 00137 * @a result_pool. Temporary allocations are performed in @a scratch_pool. 00138 * 00139 * Note that @a checksum may not be NULL. 00140 * 00141 * @since New in 1.7. 00142 */ 00143 const char * 00144 svn_checksum_serialize(const svn_checksum_t *checksum, 00145 apr_pool_t *result_pool, 00146 apr_pool_t *scratch_pool); 00147 00148 00149 /** Return @a checksum from the serialized format at @a data. The checksum 00150 * will be allocated in @a result_pool, with any temporary allocations 00151 * performed in @a scratch_pool. 00152 * 00153 * @since New in 1.7. 00154 */ 00155 svn_error_t * 00156 svn_checksum_deserialize(const svn_checksum_t **checksum, 00157 const char *data, 00158 apr_pool_t *result_pool, 00159 apr_pool_t *scratch_pool); 00160 00161 00162 /** Parse the hex representation @a hex of a checksum of kind @a kind and 00163 * set @a *checksum to the result, allocating in @a pool. 00164 * 00165 * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum 00166 * to @c NULL. 00167 * 00168 * @since New in 1.6. 00169 */ 00170 svn_error_t * 00171 svn_checksum_parse_hex(svn_checksum_t **checksum, 00172 svn_checksum_kind_t kind, 00173 const char *hex, 00174 apr_pool_t *pool); 00175 00176 /** 00177 * Return in @a *checksum the checksum of type @a kind for the bytes beginning 00178 * at @a data, and going for @a len. @a *checksum is allocated in @a pool. 00179 * 00180 * @since New in 1.6. 00181 */ 00182 svn_error_t * 00183 svn_checksum(svn_checksum_t **checksum, 00184 svn_checksum_kind_t kind, 00185 const void *data, 00186 apr_size_t len, 00187 apr_pool_t *pool); 00188 00189 00190 /** 00191 * Return in @a pool a newly allocated checksum populated with the checksum 00192 * of type @a kind for the empty string. 00193 * 00194 * @since New in 1.6. 00195 */ 00196 svn_checksum_t * 00197 svn_checksum_empty_checksum(svn_checksum_kind_t kind, 00198 apr_pool_t *pool); 00199 00200 00201 /** 00202 * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for 00203 * calculating checksums of type @a kind. @see svn_checksum_final() 00204 * 00205 * @since New in 1.6. 00206 */ 00207 svn_checksum_ctx_t * 00208 svn_checksum_ctx_create(svn_checksum_kind_t kind, 00209 apr_pool_t *pool); 00210 00211 /** 00212 * Update the checksum represented by @a ctx, with @a len bytes starting at 00213 * @a data. 00214 * 00215 * @since New in 1.6. 00216 */ 00217 svn_error_t * 00218 svn_checksum_update(svn_checksum_ctx_t *ctx, 00219 const void *data, 00220 apr_size_t len); 00221 00222 00223 /** 00224 * Finalize the checksum used when creating @a ctx, and put the resultant 00225 * checksum in @a *checksum, allocated in @a pool. 00226 * 00227 * @since New in 1.6. 00228 */ 00229 svn_error_t * 00230 svn_checksum_final(svn_checksum_t **checksum, 00231 const svn_checksum_ctx_t *ctx, 00232 apr_pool_t *pool); 00233 00234 00235 /** 00236 * Return the digest size of @a checksum. 00237 * 00238 * @since New in 1.6. 00239 */ 00240 apr_size_t 00241 svn_checksum_size(const svn_checksum_t *checksum); 00242 00243 /** 00244 * Return @c TRUE iff @a checksum matches the checksum for the empty 00245 * string. 00246 * 00247 * @since New in 1.8. 00248 */ 00249 svn_boolean_t 00250 svn_checksum_is_empty_checksum(svn_checksum_t *checksum); 00251 00252 00253 /** 00254 * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and 00255 * @a expected checksums which do not match. Use @a fmt, and the following 00256 * parameters to populate the error message. 00257 * 00258 * @note This function does not actually check for the mismatch, it just 00259 * constructs the error. 00260 * 00261 * @a scratch_pool is used for temporary allocations; the returned error 00262 * will be allocated in its own pool (as is typical). 00263 * 00264 * @since New in 1.7. 00265 */ 00266 svn_error_t * 00267 svn_checksum_mismatch_err(const svn_checksum_t *expected, 00268 const svn_checksum_t *actual, 00269 apr_pool_t *scratch_pool, 00270 const char *fmt, 00271 ...) 00272 __attribute__ ((format(printf, 4, 5))); 00273 00274 #ifdef __cplusplus 00275 } 00276 #endif /* __cplusplus */ 00277 00278 #endif /* SVN_CHECKSUM_H */