Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_checksum.h
Go to the documentation of this file.
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 
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. */
49 
50  /** The checksum is (or should be set to) a SHA1 checksum. */
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. */
68 
69 /**
70  * Opaque type for creating checksums of data.
71  */
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  */
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  */
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  */
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.
104  *
105  * @since New in 1.6.
106  */
108 svn_checksum_dup(const svn_checksum_t *checksum,
109  apr_pool_t *pool);
110 
111 
112 /** Return the hex representation of @a checksum, allocating the string
113  * in @a pool.
114  *
115  * @since New in 1.6.
116  */
117 const char *
119  apr_pool_t *pool);
120 
121 
122 /** Return the hex representation of @a checksum, allocating the
123  * string in @a pool. If @a checksum->digest is all zeros (that is,
124  * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL
125  * and NULL will be returned in that case.
126  *
127  * @since New in 1.6.
128  * @note Passing NULL for @a checksum in 1.6 will cause a segfault.
129  */
130 const char *
132  apr_pool_t *pool);
133 
134 
135 /** Return a serialized representation of @a checksum, allocated in
136  * @a result_pool. Temporary allocations are performed in @a scratch_pool.
137  *
138  * Note that @a checksum may not be NULL.
139  *
140  * @since New in 1.7.
141  */
142 const char *
143 svn_checksum_serialize(const svn_checksum_t *checksum,
144  apr_pool_t *result_pool,
145  apr_pool_t *scratch_pool);
146 
147 
148 /** Return @a checksum from the serialized format at @a data. The checksum
149  * will be allocated in @a result_pool, with any temporary allocations
150  * performed in @a scratch_pool.
151  *
152  * @since New in 1.7.
153  */
154 svn_error_t *
156  const char *data,
157  apr_pool_t *result_pool,
158  apr_pool_t *scratch_pool);
159 
160 
161 /** Parse the hex representation @a hex of a checksum of kind @a kind and
162  * set @a *checksum to the result, allocating in @a pool.
163  *
164  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
165  * to @c NULL.
166  *
167  * @since New in 1.6.
168  */
169 svn_error_t *
171  svn_checksum_kind_t kind,
172  const char *hex,
173  apr_pool_t *pool);
174 
175 /**
176  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
177  * at @a data, and going for @a len. @a *checksum is allocated in @a pool.
178  *
179  * @since New in 1.6.
180  */
181 svn_error_t *
182 svn_checksum(svn_checksum_t **checksum,
183  svn_checksum_kind_t kind,
184  const void *data,
185  apr_size_t len,
186  apr_pool_t *pool);
187 
188 
189 /**
190  * Return in @a pool a newly allocated checksum populated with the checksum
191  * of type @a kind for the empty string.
192  *
193  * @since New in 1.6.
194  */
197  apr_pool_t *pool);
198 
199 
200 /**
201  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
202  * calculating checksums of type @a kind. @see svn_checksum_final()
203  *
204  * @since New in 1.6.
205  */
208  apr_pool_t *pool);
209 
210 /**
211  * Update the checksum represented by @a ctx, with @a len bytes starting at
212  * @a data.
213  *
214  * @since New in 1.6.
215  */
216 svn_error_t *
218  const void *data,
219  apr_size_t len);
220 
221 
222 /**
223  * Finalize the checksum used when creating @a ctx, and put the resultant
224  * checksum in @a *checksum, allocated in @a pool.
225  *
226  * @since New in 1.6.
227  */
228 svn_error_t *
230  const svn_checksum_ctx_t *ctx,
231  apr_pool_t *pool);
232 
233 
234 /**
235  * Return the digest size of @a checksum.
236  *
237  * @since New in 1.6.
238  */
239 apr_size_t
240 svn_checksum_size(const svn_checksum_t *checksum);
241 
242 
243 /**
244  * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
245  * @a expected checksums which do not match. Use @a fmt, and the following
246  * parameters to populate the error message.
247  *
248  * @note This function does not actually check for the mismatch, it just
249  * constructs the error.
250  *
251  * @a scratch_pool is used for temporary allocations; the returned error
252  * will be allocated in its own pool (as is typical).
253  *
254  * @since New in 1.7.
255  */
256 svn_error_t *
258  const svn_checksum_t *actual,
259  apr_pool_t *scratch_pool,
260  const char *fmt,
261  ...)
262  __attribute__ ((format(printf, 4, 5)));
263 
264 
265 /**
266  * Internal function for creating a checksum from a binary digest.
267  *
268  * @since New in 1.6
269  */
271 svn_checksum__from_digest(const unsigned char *digest,
272  svn_checksum_kind_t kind,
273  apr_pool_t *result_pool);
274 
275 
276 #ifdef __cplusplus
277 }
278 #endif /* __cplusplus */
279 
280 #endif /* SVN_CHECKSUM_H */
svn_checksum_kind_t
Various types of checksums.
Definition: svn_checksum.h:45
svn_checksum_kind_t kind
The type of the checksum.
Definition: svn_checksum.h:66
svn_error_t * svn_checksum_clear(svn_checksum_t *checksum)
Set checksum-&gt;digest to all zeros, which, by convention, matches all other checksums.
The checksum is (or should be set to) a SHA1 checksum.
Definition: svn_checksum.h:51
svn_error_t * svn_checksum_parse_hex(svn_checksum_t **checksum, svn_checksum_kind_t kind, const char *hex, apr_pool_t *pool)
Parse the hex representation hex of a checksum of kind kind and set *checksum to the result...
apr_size_t svn_checksum_size(const svn_checksum_t *checksum)
Return the digest size of checksum.
svn_boolean_t svn_checksum_match(const svn_checksum_t *checksum1, const svn_checksum_t *checksum2)
Compare checksums checksum1 and checksum2.
svn_checksum_t * svn_checksum_empty_checksum(svn_checksum_kind_t kind, apr_pool_t *pool)
Return in pool a newly allocated checksum populated with the checksum of type kind for the empty stri...
svn_error_t * svn_checksum_final(svn_checksum_t **checksum, const svn_checksum_ctx_t *ctx, apr_pool_t *pool)
Finalize the checksum used when creating ctx, and put the resultant checksum in *checksum, allocated in pool.
Subversion error object.
Definition: svn_types.h:90
const char * svn_checksum_serialize(const svn_checksum_t *checksum, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
Return a serialized representation of checksum, allocated in result_pool.
svn_error_t * svn_checksum_deserialize(const svn_checksum_t **checksum, const char *data, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
Return checksum from the serialized format at data.
svn_checksum_t * svn_checksum_create(svn_checksum_kind_t kind, apr_pool_t *pool)
Return a new checksum structure of type kind, initialized to the all- zeros value, allocated in pool.
The checksum is (or should be set to) an MD5 checksum.
Definition: svn_checksum.h:48
struct svn_checksum_ctx_t svn_checksum_ctx_t
Opaque type for creating checksums of data.
Definition: svn_checksum.h:72
Subversion&#39;s data types.
svn_checksum_t * svn_checksum_dup(const svn_checksum_t *checksum, apr_pool_t *pool)
Return a deep copy of checksum, allocated in pool.
A generic checksum representation.
Definition: svn_checksum.h:59
svn_error_t * svn_checksum(svn_checksum_t **checksum, svn_checksum_kind_t kind, const void *data, apr_size_t len, apr_pool_t *pool)
Return in *checksum the checksum of type kind for the bytes beginning at data, and going for len...
struct svn_checksum_t svn_checksum_t
A generic checksum representation.
svn_error_t * svn_checksum_mismatch_err(const svn_checksum_t *expected, const svn_checksum_t *actual, apr_pool_t *scratch_pool, const char *fmt,...)
Return an error of type SVN_ERR_CHECKSUM_MISMATCH for actual and expected checksums which do not matc...
svn_checksum_ctx_t * svn_checksum_ctx_create(svn_checksum_kind_t kind, apr_pool_t *pool)
Create a new svn_checksum_ctx_t structure, allocated from pool for calculating checksums of type kind...
svn_error_t * svn_checksum_update(svn_checksum_ctx_t *ctx, const void *data, apr_size_t len)
Update the checksum represented by ctx, with len bytes starting at data.
int svn_boolean_t
YABT: Yet Another Boolean Type.
Definition: svn_types.h:370
const char * svn_checksum_to_cstring(const svn_checksum_t *checksum, apr_pool_t *pool)
Return the hex representation of checksum, allocating the string in pool.
const unsigned char * digest
The bytes of the checksum.
Definition: svn_checksum.h:62
svn_checksum_t * svn_checksum__from_digest(const unsigned char *digest, svn_checksum_kind_t kind, apr_pool_t *result_pool)
Internal function for creating a checksum from a binary digest.
const char * svn_checksum_to_cstring_display(const svn_checksum_t *checksum, apr_pool_t *pool)
Return the hex representation of checksum, allocating the string in pool.