svn_iter.h revision 299742
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_iter.h 24 * @brief The Subversion Iteration drivers helper routines 25 * 26 */ 27 28#ifndef SVN_ITER_H 29#define SVN_ITER_H 30 31#include <apr.h> /* for apr_ssize_t */ 32#include <apr_pools.h> /* for apr_pool_t */ 33#include <apr_hash.h> /* for apr_hash_t */ 34#include <apr_tables.h> /* for apr_array_header_t */ 35 36#include "svn_types.h" 37 38#ifdef __cplusplus 39extern "C" { 40#endif /* __cplusplus */ 41 42 43/** Callback function for use with svn_iter_apr_hash(). 44 * Use @a pool for temporary allocation, it's cleared between invocations. 45 * 46 * @a key, @a klen and @a val are the values normally retrieved with 47 * apr_hash_this(). 48 * 49 * @a baton is the baton passed into svn_iter_apr_hash(). 50 * 51 * @since New in 1.5. 52 */ 53typedef svn_error_t *(*svn_iter_apr_hash_cb_t)(void *baton, 54 const void *key, 55 apr_ssize_t klen, 56 void *val, apr_pool_t *pool); 57 58/** Iterate over the elements in @a hash, calling @a func for each one until 59 * there are no more elements or @a func returns an error. 60 * 61 * Uses @a pool for temporary allocations. 62 * 63 * If @a completed is not NULL, then on return - if @a func returns no 64 * errors - @a *completed will be set to @c TRUE. 65 * 66 * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that 67 * error is returned. When @a func returns @c SVN_ERR_ITER_BREAK, 68 * iteration is interrupted, but no error is returned and @a *completed is 69 * set to @c FALSE (even if this iteration was the last one). 70 * 71 * @since New in 1.5. 72 */ 73svn_error_t * 74svn_iter_apr_hash(svn_boolean_t *completed, 75 apr_hash_t *hash, 76 svn_iter_apr_hash_cb_t func, 77 void *baton, 78 apr_pool_t *pool); 79 80/** Iteration callback used in conjunction with svn_iter_apr_array(). 81 * 82 * Use @a pool for temporary allocation, it's cleared between invocations. 83 * 84 * @a baton is the baton passed to svn_iter_apr_array(). @a item 85 * is a pointer to the item written to the array with the APR_ARRAY_PUSH() 86 * macro. 87 * 88 * @since New in 1.5. 89 */ 90typedef svn_error_t *(*svn_iter_apr_array_cb_t)(void *baton, 91 void *item, 92 apr_pool_t *pool); 93 94/** Iterate over the elements in @a array calling @a func for each one until 95 * there are no more elements or @a func returns an error. 96 * 97 * Uses @a pool for temporary allocations. 98 * 99 * If @a completed is not NULL, then on return - if @a func returns no 100 * errors - @a *completed will be set to @c TRUE. 101 * 102 * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that 103 * error is returned. When @a func returns @c SVN_ERR_ITER_BREAK, 104 * iteration is interrupted, but no error is returned and @a *completed is 105 * set to @c FALSE (even if this iteration was the last one). 106 * 107 * @since New in 1.5. 108 */ 109svn_error_t * 110svn_iter_apr_array(svn_boolean_t *completed, 111 const apr_array_header_t *array, 112 svn_iter_apr_array_cb_t func, 113 void *baton, 114 apr_pool_t *pool); 115 116 117/** Internal routine used by svn_iter_break() macro. 118 */ 119svn_error_t * 120svn_iter__break(void); 121 122 123/** Helper macro to break looping in svn_iter_apr_array() and 124 * svn_iter_apr_hash() driven loops. 125 * 126 * @note The error is just a means of communicating between 127 * driver and callback. There is no need for it to exist 128 * past the lifetime of the iterpool. 129 * 130 * @since New in 1.5. 131 */ 132#define svn_iter_break(pool) return svn_iter__break() 133 134 135#ifdef __cplusplus 136} 137#endif /* __cplusplus */ 138 139#endif /* SVN_ITER_H */ 140