svn_ra_private.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_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
39extern "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 */
62svn_error_t *
63svn_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. */
71svn_error_t *
72svn_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. */
80svn_error_t *
81svn_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
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 */
95typedef 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 */
127svn_error_t *
128svn_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 */
151svn_error_t *
152svn_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. */
158svn_error_t *
159svn_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.  */
172typedef 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.  */
188typedef 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.  */
202typedef 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*/
252svn_error_t *
253svn_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. */
269typedef 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. */
277typedef 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. */
286svn_error_t *
287svn_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. */
302svn_error_t *
303svn_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 */
316