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  * Copyright (c) 2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_checksum.h
19  * @brief Subversion checksum routines
20  */
21 
22 #ifndef SVN_CHECKSUM_H
23 #define SVN_CHECKSUM_H
24 
25 #include <apr.h> /* for apr_size_t */
26 #include <apr_pools.h> /* for apr_pool_t */
27 
28 #include "svn_types.h" /* for svn_boolean_t, svn_error_t */
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif /* __cplusplus */
33 
34 
35 /**
36  * Various types of checksums.
37  *
38  * @since New in 1.6.
39  */
40 typedef enum
41 {
42  /** The checksum is (or should be set to) an MD5 checksum. */
44 
45  /** The checksum is (or should be set to) a SHA1 checksum. */
48 
49 /**
50  * A generic checksum representation.
51  *
52  * @since New in 1.6.
53  */
54 typedef struct svn_checksum_t
55 {
56  /** The bytes of the checksum. */
57  const unsigned char *digest;
58 
59  /** The type of the checksum. This should never be changed by consumers
60  of the APIs. */
63 
64 /**
65  * Opaque type for creating checksums of data.
66  */
68 
69 /** Return a new checksum structure of type @a kind, initialized to the all-
70  * zeros value, allocated in @a pool.
71  *
72  * @since New in 1.6.
73  */
76  apr_pool_t *pool);
77 
78 /** Set @c checksum->digest to all zeros, which, by convention, matches
79  * all other checksums.
80  *
81  * @since New in 1.6.
82  */
85 
86 /** Compare checksums @a checksum1 and @a checksum2. If their kinds do not
87  * match or if neither is all zeros, and their content does not match, then
88  * return FALSE; else return TRUE.
89  *
90  * @since New in 1.6.
91  */
93 svn_checksum_match(const svn_checksum_t *checksum1,
94  const svn_checksum_t *checksum2);
95 
96 
97 /**
98  * Return a deep copy of @a checksum, allocated in @a pool.
99  *
100  * @since New in 1.6.
101  */
103 svn_checksum_dup(const svn_checksum_t *checksum,
104  apr_pool_t *pool);
105 
106 
107 /** Return the hex representation of @a checksum, allocating the string
108  * in @a pool.
109  *
110  * @since New in 1.6.
111  */
112 const char *
114  apr_pool_t *pool);
115 
116 
117 /** Return the hex representation of @a checksum, allocating the
118  * string in @a pool. If @a checksum->digest is all zeros (that is,
119  * 0, not '0'), then return NULL.
120  *
121  * @since New in 1.6.
122  */
123 const char *
125  apr_pool_t *pool);
126 
127 
128 /** Parse the hex representation @a hex of a checksum of kind @a kind and
129  * set @a *checksum to the result, allocating in @a pool.
130  *
131  * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
132  * to @c NULL.
133  *
134  * @since New in 1.6.
135  */
136 svn_error_t *
138  svn_checksum_kind_t kind,
139  const char *hex,
140  apr_pool_t *pool);
141 
142 /**
143  * Return in @a *checksum the checksum of type @a kind for the bytes beginning
144  * at @a data, and going for @a len. @a *checksum is allocated in @a pool.
145  *
146  * @since New in 1.6.
147  */
148 svn_error_t *
149 svn_checksum(svn_checksum_t **checksum,
150  svn_checksum_kind_t kind,
151  const void *data,
152  apr_size_t len,
153  apr_pool_t *pool);
154 
155 
156 /**
157  * Return in @a pool a newly allocated checksum populated with the checksum
158  * of type @a kind for the empty string.
159  *
160  * @since New in 1.6.
161  */
164  apr_pool_t *pool);
165 
166 
167 /**
168  * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
169  * calculating checksums of type @a kind. @see svn_checksum_final()
170  *
171  * @since New in 1.6.
172  */
175  apr_pool_t *pool);
176 
177 /**
178  * Update the checksum represented by @a ctx, with @a len bytes starting at
179  * @a data.
180  *
181  * @since New in 1.6.
182  */
183 svn_error_t *
185  const void *data,
186  apr_size_t len);
187 
188 
189 /**
190  * Finalize the checksum used when creating @a ctx, and put the resultant
191  * checksum in @a *checksum, allocated in @a pool.
192  *
193  * @since New in 1.6.
194  */
195 svn_error_t *
197  const svn_checksum_ctx_t *ctx,
198  apr_pool_t *pool);
199 
200 
201 /**
202  * Return the digest size of @a checksum.
203  *
204  * @since New in 1.6.
205  */
206 apr_size_t
207 svn_checksum_size(const svn_checksum_t *checksum);
208 
209 
210 /**
211  * Internal function for creating a checksum from a binary digest.
212  *
213  * @since New in 1.6
214  */
216 svn_checksum__from_digest(const unsigned char *digest,
217  svn_checksum_kind_t kind,
218  apr_pool_t *result_pool);
219 
220 
221 #ifdef __cplusplus
222 }
223 #endif /* __cplusplus */
224 
225 #endif /* SVN_CHECKSUM_H */