contrib/subversion/subversion/include/private/svn_ra_private.h

   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_ra_private.h
  24  * @brief The Subversion repository access library - Internal routines
  25  */
  26
  27 #ifndef SVN_RA_PRIVATE_H
  28 #define SVN_RA_PRIVATE_H
  29
  30 #include <apr_pools.h>
  31
  32 #include "svn_error.h"
  33 #include "svn_ra.h"
  34 #include "svn_delta.h"
  35 #include "svn_editor.h"
  36 #include "svn_io.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif /* __cplusplus */
  41
  42
  43
  44 /**
  45  * Open a new ra session @a *new_session to the same repository as an existing
  46  * ra session @a old_session, copying the callbacks, auth baton, etc. from the
  47  * old session. This essentially limits the lifetime of the new, duplicated
  48  * session to the lifetime of the old session. If the new session should
  49  * outlive the new session, creating a new session using svn_ra_open4() is
  50  * recommended.
  51  *
  52  * If @a session_url is not NULL, parent the new session at session_url. Note
  53  * that @a session_url MUST BE in the same repository as @a old_session or an
  54  * error will be returned. When @a session_url NULL the same session root
  55  * will be used.
  56  *
  57  * Allocate @a new_session in @a result_pool. Perform temporary allocations
  58  * in @a scratch_pool.
  59  *
  60  * @since New in 1.9.
  61  */
  62 svn_error_t *
  63 svn_ra__dup_session(svn_ra_session_t **new_session,
  64                     svn_ra_session_t *old_session,
  65                     const char *session_url,
  66                     apr_pool_t *result_pool,
  67                     apr_pool_t *scratch_pool);
  68
  69 /* Equivalent to svn_ra__assert_capable_server()
  70    for SVN_RA_CAPABILITY_MERGEINFO. */
  71 svn_error_t *
  72 svn_ra__assert_mergeinfo_capable_server(svn_ra_session_t *ra_session,
  73                                         const char *path_or_url,
  74                                         apr_pool_t *pool);
  75
  76 /* Return an error with code SVN_ERR_UNSUPPORTED_FEATURE, and an error
  77    message referencing PATH_OR_URL, if the "server" pointed to by
  78    RA_SESSION doesn't support CAPABILITY (an SVN_RA_CAPABILITY_* constant).
  79    Perform temporary allocations in POOL. */
  80 svn_error_t *
  81 svn_ra__assert_capable_server(svn_ra_session_t *ra_session,
  82                               const char *capability,
  83                               const char *path_or_url,
  84                               apr_pool_t *pool);
  85
  86 \f
  87 /*** Operational Locks ***/
  88
  89 /** This is a function type which allows svn_ra__get_operational_lock()
  90  * to report lock attempt failures.  If non-NULL, @a locktoken is the
  91  * preexisting lock which prevented lock acquisition.
  92  *
  93  * @since New in 1.7.
  94  */
  95 typedef svn_error_t *(*svn_ra__lock_retry_func_t)(void *baton,
  96                                                   const svn_string_t *locktoken,
  97                                                   apr_pool_t *pool);
  98
  99 /** Acquire a lock (of sorts) on the repository associated with the
 100  * given RA @a session, retrying as necessary up to @a num_retries
 101  * times, and set @a *lock_string_p to the value of the acquired lock
 102  * token.  Allocate the returned token from @a pool.  (See this
 103  * function's counterpart svn_ra__release_operational_lock() for your
 104  * lock removal needs.)
 105  *
 106  * @a lock_revprop_name is the name of the revision-0 property used to
 107  * store the lock.
 108  *
 109  * If @a steal_lock is set, then replace any pre-existing lock on the
 110  * repository with our own.  Iff such a theft occurs and
 111  * @a stolen_lock_p is non-NULL, set @a *stolen_lock_p to the token of
 112  * the lock we stole.
 113  *
 114  * Call @a retry_func with @a retry_baton each time the retry loop
 115  * fails to acquire a lock.
 116  *
 117  * Use @a cancel_func and @a cancel_baton to check for early
 118  * cancellation.
 119  *
 120  * @note If the server does not support #SVN_RA_CAPABILITY_ATOMIC_REVPROPS
 121  * (i.e., is a pre-1.7 server), then this function makes a "best effort"
 122  * attempt to obtain the lock, but is susceptible to a race condition; see
 123  * issue #3546.
 124  *
 125  * @since New in 1.7.
 126  */
 127 svn_error_t *
 128 svn_ra__get_operational_lock(const svn_string_t **lock_string_p,
 129                              const svn_string_t **stolen_lock_p,
 130                              svn_ra_session_t *session,
 131                              const char *lock_revprop_name,
 132                              svn_boolean_t steal_lock,
 133                              int num_retries,
 134                              svn_ra__lock_retry_func_t retry_func,
 135                              void *retry_baton,
 136                              svn_cancel_func_t cancel_func,
 137                              void *cancel_baton,
 138                              apr_pool_t *pool);
 139
 140 /** Release an operational lock (whose value is @a mylocktoken) on the
 141  * repository associated with RA @a session.  (This is the counterpart
 142  * to svn_ra__get_operational_lock().)
 143  *
 144  * @a lock_revprop_name is the name of the revision-0 property used to
 145  * store the lock.
 146  *
 147  * Use @a scratch_pool for temporary allocations.
 148  *
 149  * @since New in 1.7.
 150  */
 151 svn_error_t *
 152 svn_ra__release_operational_lock(svn_ra_session_t *session,
 153                                  const char *lock_revprop_name,
 154                                  const svn_string_t *mylocktoken,
 155                                  apr_pool_t *scratch_pool);
 156
 157 /** Register CALLBACKS to be used with the Ev2 shims in RA_SESSION. */
 158 svn_error_t *
 159 svn_ra__register_editor_shim_callbacks(svn_ra_session_t *ra_session,
 160                                        svn_delta_shim_callbacks_t *callbacks);
 161
 162
 163 /* Using information from BATON, provide the (file's) pristine contents
 164    for REPOS_RELPATH. They are returned in *CONTENTS, and correspond to
 165    *REVISION.
 166
 167    If a pristine is not available (ie. a locally-added node), then set
 168    *CONTENTS to NULL; *REVISION will not be examined in this case.
 169
 170    These are allocated in RESULT_POOL. SCRATCH_POOL can be used
 171    for temporary allocations.  */
 172 typedef svn_error_t *(*svn_ra__provide_base_cb_t)(
 173   svn_stream_t **contents,
 174   svn_revnum_t *revision,
 175   void *baton,
 176   const char *repos_relpath,
 177   apr_pool_t *result_pool,
 178   apr_pool_t *scratch_pool);
 179
 180 /* Using information from BATON, provide the pristine properties for
 181    REPOS_RELPATH. They are returned in *PROPS, and correspond to *REVISION.
 182
 183    If properties are not available (ie. a locally-added node), then set
 184    *PROPS to NULL; *REVISION will not be examined in this case.
 185
 186    The properties are allocated in RESULT_POOL. SCRATCH_POOL can be used
 187    for temporary allocations.  */
 188 typedef svn_error_t *(*svn_ra__provide_props_cb_t)(
 189   apr_hash_t **props,
 190   svn_revnum_t *revision,
 191   void *baton,
 192   const char *repos_relpath,
 193   apr_pool_t *result_pool,
 194   apr_pool_t *scratch_pool);
 195
 196 /* Using information from BATON, fetch the kind of REPOS_RELPATH at revision
 197    SRC_REVISION, returning it in *KIND.
 198
 199    If the kind cannot be determined, then set *KIND to svn_node_unknown.
 200
 201    Temporary allocations can be made in SCRATCH_POOL.  */
 202 typedef svn_error_t *(*svn_ra__get_copysrc_kind_cb_t)(
 203   svn_node_kind_t *kind,
 204   void *baton,
 205   const char *repos_relpath,
 206   svn_revnum_t src_revision,
 207   apr_pool_t *scratch_pool);
 208
 209
 210 /* Return an Ev2-based editor for performing commits.
 211
 212    The editor is associated with the given SESSION, and its implied target
 213    repository.
 214
 215    REVPROPS contains all the revision properties that should be stored onto
 216    the newly-committed revision. SVN_PROP_REVISION_AUTHOR will be set to
 217    the username as determined by the session; overwriting any prior value
 218    that may be present in REVPROPS.
 219
 220    COMMIT_CB/BATON contain the callback to receive post-commit information.
 221
 222    LOCK_TOKENS should contain all lock tokens necessary to modify paths
 223    within the commit. If KEEP_LOCKS is FALSE, then the paths associated
 224    with these tokens will be unlocked.
 225    ### today, LOCK_TOKENS is session_relpath:token_value. in the future,
 226    ### it should be repos_relpath:token_value.
 227
 228    PROVIDE_BASE_CB is a callback to fetch pristine contents, used to send
 229    an svndiff over the wire to the server. This may be NULL, indicating
 230    pristine contents are not available (eg. URL-based operations or import).
 231
 232    PROVIDE_PROPS_CB is a callback to fetch pristine properties, used to
 233    send property deltas over the wire to the server. This may be NULL,
 234    indicating pristine properties are not available (eg. URL-based operations
 235    or an import).
 236
 237    GET_COPYSRC_KIND_CB is a callback to determine the kind of a copy-source.
 238    This is necessary when an Ev2/Ev1 shim is required by the RA provider,
 239    in order to determine whether to use delta->add_directory() or the
 240    delta->add_file() vtable entry to perform the copy.
 241    ### unclear on impact if this is NULL.
 242    ### this callback will disappear when "everything" is running Ev2
 243
 244    CB_BATON is the baton used/shared by the above three callbacks.
 245
 246    Cancellation is handled through the callbacks provided when SESSION
 247    is initially opened.
 248
 249    *EDITOR will be allocated in RESULT_POOL, and all temporary allocations
 250    will be performed in SCRATCH_POOL.
 251 */
 252 svn_error_t *
 253 svn_ra__get_commit_ev2(svn_editor_t **editor,
 254                        svn_ra_session_t *session,
 255                        apr_hash_t *revprops,
 256                        svn_commit_callback2_t commit_cb,
 257                        void *commit_baton,
 258                        apr_hash_t *lock_tokens,
 259                        svn_boolean_t keep_locks,
 260                        svn_ra__provide_base_cb_t provide_base_cb,
 261                        svn_ra__provide_props_cb_t provide_props_cb,
 262                        svn_ra__get_copysrc_kind_cb_t get_copysrc_kind_cb,
 263                        void *cb_baton,
 264                        apr_pool_t *result_pool,
 265                        apr_pool_t *scratch_pool);
 266
 267
 268 /* Similar to #svn_ra_replay_revstart_callback_t, but with an Ev2 editor. */
 269 typedef svn_error_t *(*svn_ra__replay_revstart_ev2_callback_t)(
 270   svn_revnum_t revision,
 271   void *replay_baton,
 272   svn_editor_t **editor,
 273   apr_hash_t *rev_props,
 274   apr_pool_t *pool);
 275
 276 /* Similar to #svn_ra_replay_revfinish_callback_t, but with an Ev2 editor. */
 277 typedef svn_error_t *(*svn_ra__replay_revfinish_ev2_callback_t)(
 278   svn_revnum_t revision,
 279   void *replay_baton,
 280   svn_editor_t *editor,
 281   apr_hash_t *rev_props,
 282   apr_pool_t *pool);
 283
 284 /* Similar to svn_ra_replay_range(), but uses Ev2 versions of the callback
 285    functions. */
 286 svn_error_t *
 287 svn_ra__replay_range_ev2(svn_ra_session_t *session,
 288                          svn_revnum_t start_revision,
 289                          svn_revnum_t end_revision,
 290                          svn_revnum_t low_water_mark,
 291                          svn_boolean_t send_deltas,
 292                          svn_ra__replay_revstart_ev2_callback_t revstart_func,
 293                          svn_ra__replay_revfinish_ev2_callback_t revfinish_func,
 294                          void *replay_baton,
 295                          svn_ra__provide_base_cb_t provide_base_cb,
 296                          svn_ra__provide_props_cb_t provide_props_cb,
 297                          svn_ra__get_copysrc_kind_cb_t get_copysrc_kind_cb,
 298                          void *cb_baton,
 299                          apr_pool_t *scratch_pool);
 300
 301 /* Similar to svn_ra_replay(), but with an Ev2 editor. */
 302 svn_error_t *
 303 svn_ra__replay_ev2(svn_ra_session_t *session,
 304                    svn_revnum_t revision,
 305                    svn_revnum_t low_water_mark,
 306                    svn_boolean_t send_deltas,
 307                    svn_editor_t *editor,
 308                    apr_pool_t *scratch_pool);
 309
 310
 311 #ifdef __cplusplus
 312 }
 313 #endif /* __cplusplus */
 314
 315 #endif /* SVN_RA_PRIVATE_H */