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