contrib/subversion/subversion/include/private/svn_fs_private.h

   1 /*
   2  * svn_fs_private.h: Private declarations for the filesystem layer to
   3  * be consumed by libsvn_fs* and non-libsvn_fs* modules.
   4  *
   5  * ====================================================================
   6  *    Licensed to the Apache Software Foundation (ASF) under one
   7  *    or more contributor license agreements.  See the NOTICE file
   8  *    distributed with this work for additional information
   9  *    regarding copyright ownership.  The ASF licenses this file
  10  *    to you under the Apache License, Version 2.0 (the
  11  *    "License"); you may not use this file except in compliance
  12  *    with the License.  You may obtain a copy of the License at
  13  *
  14  *      http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  *    Unless required by applicable law or agreed to in writing,
  17  *    software distributed under the License is distributed on an
  18  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  19  *    KIND, either express or implied.  See the License for the
  20  *    specific language governing permissions and limitations
  21  *    under the License.
  22  * ====================================================================
  23  */
  24
  25 #ifndef SVN_FS_PRIVATE_H
  26 #define SVN_FS_PRIVATE_H
  27
  28 #include "svn_fs.h"
  29 #include "private/svn_editor.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif /* __cplusplus */
  34
  35 /* The maximum length of a transaction name.  The Berkeley DB backend
  36    generates transaction names from a sequence expressed as a base 36
  37    number with a maximum of MAX_KEY_SIZE (currently 200) bytes.  The
  38    FSFS backend generates transaction names of the form
  39    <rev>-<base 36-number> where the base 36 number is a sequence value
  40    with a maximum length of MAX_KEY_SIZE bytes.  The maximum length is
  41    212, but use 220 just to have some extra space:
  42      10   -> 32 bit revision number
  43      1    -> '-'
  44      200  -> 200 digit base 36 number
  45      1    -> '\0'
  46  */
  47 #define SVN_FS__TXN_MAX_LEN 220
  48
  49 /** Retrieve the lock-tokens associated in the context @a access_ctx.
  50  * The tokens are in a hash keyed with <tt>const char *</tt> tokens,
  51  * and with <tt>const char *</tt> values for the paths associated.
  52  *
  53  * You should always use svn_fs_access_add_lock_token2() if you intend
  54  * to use this function.  The result of the function is not guaranteed
  55  * if you use it with the deprecated svn_fs_access_add_lock_token()
  56  * API.
  57  *
  58  * @since New in 1.6. */
  59 apr_hash_t *
  60 svn_fs__access_get_lock_tokens(svn_fs_access_t *access_ctx);
  61
  62
  63 /* Check whether PATH is valid for a filesystem, following (most of) the
  64  * requirements in svn_fs.h:"Directory entry names and directory paths".
  65  *
  66  * Return SVN_ERR_FS_PATH_SYNTAX if PATH is not valid.
  67  */
  68 svn_error_t *
  69 svn_fs__path_valid(const char *path, apr_pool_t *pool);
  70
  71
  72 \f
  73 /** Editors
  74  *
  75  * ### docco
  76  *
  77  * @defgroup svn_fs_editor Transaction editors
  78  * @{
  79  */
  80
  81 /**
  82  * Create a new filesystem transaction, based on based on the youngest
  83  * revision of @a fs, and return its name @a *txn_name and an @a *editor
  84  * that can be used to make changes into it.
  85  *
  86  * @a flags determines transaction enforcement behaviors, and is composed
  87  * from the constants SVN_FS_TXN_* (#SVN_FS_TXN_CHECK_OOD etc.). It is a
  88  * property of the underlying transaction, and will not change if multiple
  89  * editors are used to refer to that transaction (see @a autocommit, below).
  90  *
  91  * @note If you're building a txn for committing, you probably don't want
  92  * to call this directly.  Instead, call svn_repos__get_commit_ev2(), which
  93  * honors the repository's hook configurations.
  94  *
  95  * When svn_editor_complete() is called for @a editor, internal resources
  96  * will be cleaned and nothing more will happen. If you wish to commit the
  97  * transaction, call svn_fs_editor_commit() instead. It is illegal to call
  98  * both; the second call will return #SVN_ERR_FS_INCORRECT_EDITOR_COMPLETION.
  99  *
 100  * @see svn_fs_commit_txn()
 101  *
 102  * @since New in 1.8.
 103  */
 104 svn_error_t *
 105 svn_fs__editor_create(svn_editor_t **editor,
 106                       const char **txn_name,
 107                       svn_fs_t *fs,
 108                       apr_uint32_t flags,
 109                       svn_cancel_func_t cancel_func,
 110                       void *cancel_baton,
 111                       apr_pool_t *result_pool,
 112                       apr_pool_t *scratch_pool);
 113
 114
 115 /**
 116  * Like svn_fs__editor_create(), but open an existing transaction
 117  * @a txn_name and continue editing it.
 118  *
 119  * @since New in 1.8.
 120  */
 121 svn_error_t *
 122 svn_fs__editor_create_for(svn_editor_t **editor,
 123                           svn_fs_t *fs,
 124                           const char *txn_name,
 125                           svn_cancel_func_t cancel_func,
 126                           void *cancel_baton,
 127                           apr_pool_t *result_pool,
 128                           apr_pool_t *scratch_pool);
 129
 130
 131 /**
 132  * Commit the transaction represented by @a editor.
 133  *
 134  * If the commit to the filesystem succeeds, then @a *revision will be set
 135  * to the resulting revision number. Note that further errors may occur,
 136  * as described below. If the commit process does not succeed, for whatever
 137  * reason, then @a *revision will be set to #SVN_INVALID_REVNUM.
 138  *
 139  * If a conflict occurs during the commit, then @a *conflict_path will
 140  * be set to a path that caused the conflict. #SVN_NO_ERROR will be returned.
 141  * Callers may want to construct an #SVN_ERR_FS_CONFLICT error with a
 142  * message that incorporates @a *conflict_path.
 143  *
 144  * If a non-conflict error occurs during the commit, then that error will
 145  * be returned.
 146  * As is standard with any Subversion API, @a revision, @a post_commit_err,
 147  * and @a conflict_path (the OUT parameters) have an indeterminate value if
 148  * an error is returned.
 149  *
 150  * If the commit completes (and a revision is returned in @a *revision), then
 151  * it is still possible for an error to occur during the cleanup process.
 152  * Any such error will be returned in @a *post_commit_err. The caller must
 153  * properly use or clear that error.
 154  *
 155  * If svn_editor_complete() has already been called on @a editor, then
 156  * #SVN_ERR_FS_INCORRECT_EDITOR_COMPLETION will be returned.
 157  *
 158  * @note After calling this function, @a editor will be marked as completed
 159  * and no further operations may be performed on it. The underlying
 160  * transaction will either be committed or aborted once this function is
 161  * called. It cannot be recovered for additional work.
 162  *
 163  * @a result_pool will be used to allocate space for @a conflict_path.
 164  * @a scratch_pool will be used for all temporary allocations.
 165  *
 166  * @note To summarize, there are three possible outcomes of this function:
 167  * successful commit (with or without an associated @a *post_commit_err);
 168  * failed commit due to a conflict (reported via @a *conflict_path); and
 169  * failed commit for some other reason (reported via the returned error.)
 170  *
 171  * @since New in 1.8.
 172  */
 173 svn_error_t *
 174 svn_fs__editor_commit(svn_revnum_t *revision,
 175                       svn_error_t **post_commit_err,
 176                       const char **conflict_path,
 177                       svn_editor_t *editor,
 178                       apr_pool_t *result_pool,
 179                       apr_pool_t *scratch_pool);
 180
 181
 182 /** @} */
 183
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif /* __cplusplus */
 188
 189 #endif /* SVN_FS_PRIVATE_H */