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. */
52 
53  /** The checksum is (or should be set to) a FNV-1a 32 bit checksum,
54  * in big endian byte order.
55  * @since New in 1.9. */
57 
58  /** The checksum is (or should be set to) a modified FNV-1a 32 bit,
59  * in big endian byte order.
60  * @since New in 1.9. */
63 
64 /**
65  * A generic checksum representation.
66  *
67  * @since New in 1.6.
68  */
69 typedef struct svn_checksum_t
70 {
71  /** The bytes of the checksum. */
72  const unsigned char *digest;
73 
74  /** The type of the checksum. This should never be changed by consumers
75  of the APIs. */
78 
79 /**
80  * Opaque type for creating checksums of data.
81  */
83 
84 /** Return a new checksum structure of type @a kind, initialized to the all-
85  * zeros value, allocated in @a pool.
86  *
87  * @since New in 1.6.
88  */
91  apr_pool_t *pool);
92 
93 /** Set @a checksum->digest to all zeros, which, by convention, matches
94  * all other checksums.
95  *
96  * @since New in 1.6.
97  */
100 
101 /** Compare checksums @a checksum1 and @a checksum2. If their kinds do not
102  * match or if neither is all zeros, and their content does not match, then
103  * return FALSE; else return TRUE.
104  *
105  * @since New in 1.6.
106  */
108 svn_checksum_match(const svn_checksum_t *checksum1,
109  const svn_checksum_t *checksum2);
110 
111 
112 /**
113  * Return a deep copy of @a checksum, allocated in @a pool. If @a
114  * checksum is NULL then NULL is returned.
115  *
116  * @since New in 1.6.
117  */
119 svn_checksum_dup(const svn_checksum_t *checksum,
120  apr_pool_t *pool);
121 
122 
123 /** Return the hex representation of @a checksum, allocating the string
124  * in @a pool.
125  *
126  * @since New in 1.6.
127  */
128 const char *
130  apr_pool_t *pool);
131 
132 
133 /** Return the hex representation of @a checksum, allocating the
134  * string in @a pool. If @a checksum->digest is all zeros (that is,
135  * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL
136  * and NULL will be returned in that case.
137  *
138  * @since New in 1.6.
139  * @note Passing NULL for @a checksum in 1.6 will cause a segfault.
140  */
141 const char *
143  apr_pool_t *pool);
144 
145 
146 /** Return a serialized representation of @a checksum, allocated in
147  * @a result_pool. Temporary allocations are performed in @a scratch_pool.
148  *
149  * Note that @a checksum may not be NULL.
150  *
151  * @since New in 1.7.
152  */
153 const char *
154 svn_checksum_serialize(const svn_checksum_t *checksum,
155  apr_pool_t *result_pool,
156  apr_pool_t *scratch_pool);
157 
158 
159 /** Return @a checksum from the serialized format at @a data. The checksum
160  * will be allocated in @a result_pool, with any temporary allocations
161  * performed in @a scratch_pool.
162  *
163  * @since New in 1.7.
164  */
165 svn_error_t *
167  const char *data,
168  apr_pool_t *result_pool,
169  apr_pool_t *scratch_pool);
170 
171 
172 /** Parse the hex representation @a hex of a checksum of kind @a kind and
173  * set @a *checksum to the result, allocating in @a pool.
174  *
175  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
176  * to @c NULL.
177  *
178  * @since New in 1.6.
179  */
180 svn_error_t *
182  svn_checksum_kind_t kind,
183  const char *hex,
184  apr_pool_t *pool);
185 
186 /**
187  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
188  * at @a data, and going for @a len. @a *checksum is allocated in @a pool.
189  *
190  * @since New in 1.6.
191  */
192 svn_error_t *
193 svn_checksum(svn_checksum_t **checksum,
194  svn_checksum_kind_t kind,
195  const void *data,
196  apr_size_t len,
197  apr_pool_t *pool);
198 
199 
200 /**
201  * Return in @a pool a newly allocated checksum populated with the checksum
202  * of type @a kind for the empty string.
203  *
204  * @since New in 1.6.
205  */
208  apr_pool_t *pool);
209 
210 
211 /**
212  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
213  * calculating checksums of type @a kind. @see svn_checksum_final()
214  *
215  * @since New in 1.6.
216  */
219  apr_pool_t *pool);
220 
221 /**
222  * Update the checksum represented by @a ctx, with @a len bytes starting at
223  * @a data.
224  *
225  * @since New in 1.6.
226  */
227 svn_error_t *
229  const void *data,
230  apr_size_t len);
231 
232 
233 /**
234  * Finalize the checksum used when creating @a ctx, and put the resultant
235  * checksum in @a *checksum, allocated in @a pool.
236  *
237  * @since New in 1.6.
238  */
239 svn_error_t *
241  const svn_checksum_ctx_t *ctx,
242  apr_pool_t *pool);
243 
244 
245 /**
246  * Return the digest size of @a checksum.
247  *
248  * @since New in 1.6.
249  */
250 apr_size_t
251 svn_checksum_size(const svn_checksum_t *checksum);
252 
253 /**
254  * Return @c TRUE iff @a checksum matches the checksum for the empty
255  * string.
256  *
257  * @since New in 1.8.
258  */
261 
262 
263 /**
264  * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
265  * @a expected checksums which do not match. Use @a fmt, and the following
266  * parameters to populate the error message.
267  *
268  * @note This function does not actually check for the mismatch, it just
269  * constructs the error.
270  *
271  * @a scratch_pool is used for temporary allocations; the returned error
272  * will be allocated in its own pool (as is typical).
273  *
274  * @since New in 1.7.
275  */
276 svn_error_t *
278  const svn_checksum_t *actual,
279  apr_pool_t *scratch_pool,
280  const char *fmt,
281  ...)
282  __attribute__ ((format(printf, 4, 5)));
283 
284 #ifdef __cplusplus
285 }
286 #endif /* __cplusplus */
287 
288 #endif /* SVN_CHECKSUM_H */