contrib/subversion/subversion/include/private/svn_subr_private.h

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