Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_iter.h
Go to the documentation of this file.
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
39 extern "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  */
53 typedef 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  */
75  apr_hash_t *hash,
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  */
90 typedef 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  */
109 svn_error_t *
111  const apr_array_header_t *array,
113  void *baton,
114  apr_pool_t *pool);
115 
116 
117 /** Internal routine used by svn_iter_break() macro.
118  */
119 svn_error_t *
120 svn_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 */