Subversion 1.6.16

svn_iter.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2007 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_iter.h
00019  * @brief The Subversion Iteration drivers helper routines
00020  *
00021  */
00022 
00023 #ifndef SVN_ITER_H
00024 #define SVN_ITER_H
00025 
00026 #include <apr.h>         /* for apr_ssize_t */
00027 #include <apr_pools.h>   /* for apr_pool_t */
00028 #include <apr_hash.h>    /* for apr_hash_t */
00029 #include <apr_tables.h>  /* for apr_array_header_t */
00030 
00031 #include "svn_types.h"
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif /* __cplusplus */
00036 
00037 
00038 /** Callback function for use with svn_iter_apr_hash().
00039  * Use @a pool for temporary allocation, it's cleared between invocations.
00040  *
00041  * @a key, @a klen and @a val are the values normally retrieved with
00042  * apr_hash_this().
00043  *
00044  * @a baton is the baton passed into svn_iter_apr_hash().
00045  *
00046  * @since New in 1.5.
00047  */
00048 typedef svn_error_t *(*svn_iter_apr_hash_cb_t)(void *baton,
00049                                                const void *key,
00050                                                apr_ssize_t klen,
00051                                                void *val, apr_pool_t *pool);
00052 
00053 /** Iterate over the elements in @a hash, calling @a func for each one until
00054  * there are no more elements or @a func returns an error.
00055  *
00056  * Uses @a pool for temporary allocations.
00057  *
00058  * If @a completed is not NULL, then on return - if @a func returns no
00059  * errors - @a *completed will be set to @c TRUE.
00060  *
00061  * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
00062  * error is returned.  When @a func returns @c SVN_ERR_ITER_BREAK,
00063  * iteration is interrupted, but no error is returned and @a *completed is
00064  * set to @c FALSE.
00065  *
00066  * @since New in 1.5.
00067  */
00068 svn_error_t *
00069 svn_iter_apr_hash(svn_boolean_t *completed,
00070                   apr_hash_t *hash,
00071                   svn_iter_apr_hash_cb_t func,
00072                   void *baton,
00073                   apr_pool_t *pool);
00074 
00075 /** Iteration callback used in conjuction with svn_iter_apr_array().
00076  *
00077  * Use @a pool for temporary allocation, it's cleared between invocations.
00078  *
00079  * @a baton is the baton passed to svn_iter_apr_array().  @a item
00080  * is a pointer to the item written to the array with the APR_ARRAY_PUSH()
00081  * macro.
00082  *
00083  * @since New in 1.5.
00084  */
00085 typedef svn_error_t *(*svn_iter_apr_array_cb_t)(void *baton,
00086                                                 void *item,
00087                                                 apr_pool_t *pool);
00088 
00089 /** Iterate over the elements in @a array calling @a func for each one until
00090  * there are no more elements or @a func returns an error.
00091  *
00092  * Uses @a pool for temporary allocations.
00093  *
00094  * If @a completed is not NULL, then on return - if @a func returns no
00095  * errors - @a *completed will be set to @c TRUE.
00096  *
00097  * If @a func returns an error other than @c SVN_ERR_ITER_BREAK, that
00098  * error is returned.  When @a func returns @c SVN_ERR_ITER_BREAK,
00099  * iteration is interrupted, but no error is returned and @a *completed is
00100  * set to @c FALSE.
00101  *
00102  * @since New in 1.5.
00103  */
00104 svn_error_t *
00105 svn_iter_apr_array(svn_boolean_t *completed,
00106                    const apr_array_header_t *array,
00107                    svn_iter_apr_array_cb_t func,
00108                    void *baton,
00109                    apr_pool_t *pool);
00110 
00111 
00112 /** Internal routine used by svn_iter_break() macro.
00113  */
00114 svn_error_t *
00115 svn_iter__break(void);
00116 
00117 
00118 /** Helper macro to break looping in svn_iter_apr_array() and
00119  * svn_iter_apr_hash() driven loops.
00120  *
00121  * @note The error is just a means of communicating between
00122  *       driver and callback.  There is no need for it to exist
00123  *       past the lifetime of the iterpool.
00124  *
00125  * @since New in 1.5.
00126  */
00127 #define svn_iter_break(pool) return svn_iter__break()
00128 
00129 
00130 #ifdef __cplusplus
00131 }
00132 #endif /* __cplusplus */
00133 
00134 #endif /* SVN_ITER_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines