1/*
2 * svn_subr_private.h : private definitions from libsvn_subr
3 *
4 * ====================================================================
5 *    Licensed to the Apache Software Foundation (ASF) under one
6 *    or more contributor license agreements.  See the NOTICE file
7 *    distributed with this work for additional information
8 *    regarding copyright ownership.  The ASF licenses this file
9 *    to you under the Apache License, Version 2.0 (the
10 *    "License"); you may not use this file except in compliance
11 *    with the License.  You may obtain a copy of the License at
12 *
13 *      http://www.apache.org/licenses/LICENSE-2.0
14 *
15 *    Unless required by applicable law or agreed to in writing,
16 *    software distributed under the License is distributed on an
17 *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 *    KIND, either express or implied.  See the License for the
19 *    specific language governing permissions and limitations
20 *    under the License.
21 * ====================================================================
22 */
23
24#ifndef SVN_SUBR_PRIVATE_H
25#define SVN_SUBR_PRIVATE_H
26
27#include "svn_types.h"
28#include "svn_io.h"
29
30
31#ifdef __cplusplus
32extern "C" {
33#endif /* __cplusplus */
34
35
36/** Spill-to-file Buffers
37 *
38 * @defgroup svn_spillbuf_t Spill-to-file Buffers
39 * @{
40 */
41
42/** A buffer that collects blocks of content, possibly using a file.
43 *
44 * The spill-buffer is created with two basic parameters: the size of the
45 * blocks that will be written into the spill-buffer ("blocksize"), and
46 * the (approximate) maximum size that will be allowed in memory ("maxsize").
47 * Once the maxsize is reached, newly written content will be "spilled"
48 * into a temporary file.
49 *
50 * When writing, content will be buffered into memory unless a given write
51 * will cause the amount of in-memory content to exceed the specified
52 * maxsize. At that point, the file is created, and the content will be
53 * written to that file.
54 *
55 * To read information back out of a spill buffer, there are two approaches
56 * available to the application:
57 *
58 *   *) reading blocks using svn_spillbuf_read() (a "pull" model)
59 *   *) having blocks passed to a callback via svn_spillbuf_process()
60 *      (a "push" model to your application)
61 *
62 * In both cases, the spill-buffer will provide you with a block of N bytes
63 * that you must fully consume before asking for more data. The callback
64 * style provides for a "stop" parameter to temporarily pause the reading
65 * until another read is desired. The two styles of reading may be mixed,
66 * as the caller desires. Generally, N will be the blocksize, and will be
67 * less when the end of the content is reached.
68 *
69 * For a more stream-oriented style of reading, where the caller specifies
70 * the number of bytes to read into a caller-provided buffer, please see
71 * svn_spillbuf_reader_t. That overlaid type will cause more memory copies
72 * to be performed (whereas the bare spill-buffer type hands you a buffer
73 * to consume).
74 *
75 * Writes may be interleaved with reading, and content will be returned
76 * in a FIFO manner. Thus, if content has been placed into the spill-buffer
77 * you will always read the earliest-written data, and any newly-written
78 * content will be appended to the buffer.
79 *
80 * Note: the file is created in the same pool where the spill-buffer was
81 * created. If the content is completely read from that file, it will be
82 * closed and deleted. Should writing further content cause another spill
83 * file to be created, that will increase the size of the pool. There is
84 * no bound on the amount of file-related resources that may be consumed
85 * from the pool. It is entirely related to the read/write pattern and
86 * whether spill files are repeatedly created.
87 */
88typedef struct svn_spillbuf_t svn_spillbuf_t;
89
90
91/* Create a spill buffer.  */
92svn_spillbuf_t *
93svn_spillbuf__create(apr_size_t blocksize,
94                     apr_size_t maxsize,
95                     apr_pool_t *result_pool);
96
97
98/* Determine how much content is stored in the spill buffer.  */
99svn_filesize_t
100svn_spillbuf__get_size(const svn_spillbuf_t *buf);
101
102
103/* Write some data into the spill buffer.  */
104svn_error_t *
105svn_spillbuf__write(svn_spillbuf_t *buf,
106                    const char *data,
107                    apr_size_t len,
108                    apr_pool_t *scratch_pool);
109
110
111/* Read a block of memory from the spill buffer. @a *data will be set to
112   NULL if no content remains. Otherwise, @a data and @a len will point to
113   data that must be fully-consumed by the caller. This data will remain
114   valid until another call to svn_spillbuf_write(), svn_spillbuf_read(),
115   or svn_spillbuf_process(), or if the spill buffer's pool is cleared.  */
116svn_error_t *
117svn_spillbuf__read(const char **data,
118                   apr_size_t *len,
119                   svn_spillbuf_t *buf,
120                   apr_pool_t *scratch_pool);
121
122
123/* Callback for reading content out of the spill buffer. Set @a stop if
124   you want to stop the processing (and will call svn_spillbuf_process
125   again, at a later time).  */
126typedef svn_error_t * (*svn_spillbuf_read_t)(svn_boolean_t *stop,
127                                             void *baton,
128                                             const char *data,
129                                             apr_size_t len,
130                                             apr_pool_t *scratch_pool);
131
132
133/* Process the content stored in the spill buffer. @a exhausted will be
134   set to TRUE if all of the content is processed by @a read_func. This
135   function may return early if the callback returns TRUE for its 'stop'
136   parameter.  */
137svn_error_t *
138svn_spillbuf__process(svn_boolean_t *exhausted,
139                      svn_spillbuf_t *buf,
140                      svn_spillbuf_read_t read_func,
141                      void *read_baton,
142                      apr_pool_t *scratch_pool);
143
144
145/** Classic stream reading layer on top of spill-buffers.
146 *
147 * This type layers upon a spill-buffer to enable a caller to read a
148 * specified number of bytes into the caller's provided buffer. This
149 * implies more memory copies than the standard spill-buffer reading
150 * interface, but is sometimes required by spill-buffer users.
151 */
152typedef struct svn_spillbuf_reader_t svn_spillbuf_reader_t;
153
154
155/* Create a spill-buffer and a reader for it.  */
156svn_spillbuf_reader_t *
157svn_spillbuf__reader_create(apr_size_t blocksize,
158                            apr_size_t maxsize,
159                            apr_pool_t *result_pool);
160
161
162/* Read @a len bytes from @a reader into @a data. The number of bytes
163   actually read is stored in @a amt. If the content is exhausted, then
164   @a amt is set to zero. It will always be non-zero if the spill-buffer
165   contains content.
166
167   If @a len is zero, then SVN_ERR_INCORRECT_PARAMS is returned.  */
168svn_error_t *
169svn_spillbuf__reader_read(apr_size_t *amt,
170                          svn_spillbuf_reader_t *reader,
171                          char *data,
172                          apr_size_t len,
173                          apr_pool_t *scratch_pool);
174
175
176/* Read a single character from @a reader, and place it in @a c. If there
177   is no content in the spill-buffer, then SVN_ERR_STREAM_UNEXPECTED_EOF
178   is returned.  */
179svn_error_t *
180svn_spillbuf__reader_getc(char *c,
181                          svn_spillbuf_reader_t *reader,
182                          apr_pool_t *scratch_pool);
183
184
185/* Write @a len bytes from @a data into the spill-buffer in @a reader.  */
186svn_error_t *
187svn_spillbuf__reader_write(svn_spillbuf_reader_t *reader,
188                           const char *data,
189                           apr_size_t len,
190                           apr_pool_t *scratch_pool);
191
192
193/* Return a stream built on top of a spillbuf, using the same arguments as
194   svn_spillbuf__create().  This stream can be used for reading and writing,
195   but implements the same basic sematics of a spillbuf for the underlying
196   storage. */
197svn_stream_t *
198svn_stream__from_spillbuf(apr_size_t blocksize,
199                          apr_size_t maxsize,
200                          apr_pool_t *result_pool);
201
202/** @} */
203
204/**
205 * Internal function for creating a MD5 checksum from a binary digest.
206 *
207 * @since New in 1.8
208 */
209svn_checksum_t *
210svn_checksum__from_digest_md5(const unsigned char *digest,
211                              apr_pool_t *result_pool);
212
213/**
214 * Internal function for creating a SHA1 checksum from a binary
215 * digest.
216 *
217 * @since New in 1.8
218 */
219svn_checksum_t *
220svn_checksum__from_digest_sha1(const unsigned char *digest,
221                               apr_pool_t *result_pool);
222
223
224/**
225 * @defgroup svn_hash_support Hash table serialization support
226 * @{
227 */
228
229/*----------------------------------------------------*/
230
231/**
232 * @defgroup svn_hash_misc Miscellaneous hash APIs
233 * @{
234 */
235
236/** @} */
237
238
239/**
240 * @defgroup svn_hash_getters Specialized getter APIs for hashes
241 * @{
242 */
243
244/** Find the value of a @a key in @a hash, return the value.
245 *
246 * If @a hash is @c NULL or if the @a key cannot be found, the
247 * @a default_value will be returned.
248 *
249 * @since New in 1.7.
250 */
251const char *
252svn_hash__get_cstring(apr_hash_t *hash,
253                      const char *key,
254                      const char *default_value);
255
256/** Like svn_hash_get_cstring(), but for boolean values.
257 *
258 * Parses the value as a boolean value. The recognized representations
259 * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not
260 * matter.
261 *
262 * @since New in 1.7.
263 */
264svn_boolean_t
265svn_hash__get_bool(apr_hash_t *hash,
266                   const char *key,
267                   svn_boolean_t default_value);
268
269/** @} */
270
271/**
272 * @defgroup svn_hash_create Create optimized APR hash tables
273 * @{
274 */
275
276/** Returns a hash table, allocated in @a pool, with the same ordering of
277 * elements as APR 1.4.5 or earlier (using apr_hashfunc_default) but uses
278 * a faster hash function implementation.
279 *
280 * @since New in 1.8.
281 */
282apr_hash_t *
283svn_hash__make(apr_pool_t *pool);
284
285/** @} */
286
287/** @} */
288
289
290/** Apply the changes described by @a prop_changes to @a original_props and
291 * return the result.  The inverse of svn_prop_diffs().
292 *
293 * Allocate the resulting hash from @a pool, but allocate its keys and
294 * values from @a pool and/or by reference to the storage of the inputs.
295 *
296 * Note: some other APIs use an array of pointers to svn_prop_t.
297 *
298 * @since New in 1.8.
299 */
300apr_hash_t *
301svn_prop__patch(const apr_hash_t *original_props,
302                const apr_array_header_t *prop_changes,
303                apr_pool_t *pool);
304
305
306/**
307 * @defgroup svn_version Version number dotted triplet parsing
308 * @{
309 */
310
311/* Set @a *version to a version structure parsed from the version
312 * string representation in @a version_string.  Return
313 * @c SVN_ERR_MALFORMED_VERSION_STRING if the string fails to parse
314 * cleanly.
315 *
316 * @since New in 1.8.
317 */
318svn_error_t *
319svn_version__parse_version_string(svn_version_t **version,
320                                  const char *version_string,
321                                  apr_pool_t *result_pool);
322
323/* Return true iff @a version represents a version number of at least
324 * the level represented by @a major, @a minor, and @a patch.
325 *
326 * @since New in 1.8.
327 */
328svn_boolean_t
329svn_version__at_least(svn_version_t *version,
330                      int major,
331                      int minor,
332                      int patch);
333
334/** @} */
335
336#ifdef __cplusplus
337}
338#endif /* __cplusplus */
339
340#endif /* SVN_SUBR_PRIVATE_H */
341