Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_ra.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_ra.h
24  * @brief Repository Access
25  */
26 
27 #ifndef SVN_RA_H
28 #define SVN_RA_H
29 
30 #include <apr.h>
31 #include <apr_pools.h>
32 #include <apr_hash.h>
33 #include <apr_tables.h>
34 #include <apr_time.h>
35 #include <apr_file_io.h> /* for apr_file_t */
36 
37 #include "svn_types.h"
38 #include "svn_string.h"
39 #include "svn_delta.h"
40 #include "svn_auth.h"
41 #include "svn_mergeinfo.h"
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif /* __cplusplus */
46 
47 
48 
49 /* Misc. declarations */
50 
51 /**
52  * Get libsvn_ra version information.
53  *
54  * @since New in 1.1.
55  */
56 const svn_version_t *
57 svn_ra_version(void);
58 
59 
60 /** This is a function type which allows the RA layer to fetch working
61  * copy (WC) properties.
62  *
63  * The @a baton is provided along with the function pointer and should
64  * be passed back in. This will be the @a callback_baton or the
65  * @a close_baton as appropriate.
66  *
67  * @a path is relative to the "root" of the session, defined by the
68  * @a repos_URL passed to svn_ra_open4() vtable call.
69  *
70  * @a name is the name of the property to fetch. If the property is present,
71  * then it is returned in @a value. Otherwise, @a *value is set to @c NULL.
72  */
73 typedef svn_error_t *(*svn_ra_get_wc_prop_func_t)(void *baton,
74  const char *path,
75  const char *name,
76  const svn_string_t **value,
77  apr_pool_t *pool);
78 
79 /** This is a function type which allows the RA layer to store new
80  * working copy properties during update-like operations. See the
81  * comments for @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and
82  * @a name. The @a value is the value that will be stored for the property;
83  * a NULL @a value means the property will be deleted.
84  */
85 typedef svn_error_t *(*svn_ra_set_wc_prop_func_t)(void *baton,
86  const char *path,
87  const char *name,
88  const svn_string_t *value,
89  apr_pool_t *pool);
90 
91 /** This is a function type which allows the RA layer to store new
92  * working copy properties as part of a commit. See the comments for
93  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.
94  * The @a value is the value that will be stored for the property; a
95  * @c NULL @a value means the property will be deleted.
96  *
97  * Note that this might not actually store the new property before
98  * returning, but instead schedule it to be changed as part of
99  * post-commit processing (in which case a successful commit means the
100  * properties got written). Thus, during the commit, it is possible
101  * to invoke this function to set a new value for a wc prop, then read
102  * the wc prop back from the working copy and get the *old* value.
103  * Callers beware.
104  */
105 typedef svn_error_t *(*svn_ra_push_wc_prop_func_t)(void *baton,
106  const char *path,
107  const char *name,
108  const svn_string_t *value,
109  apr_pool_t *pool);
110 
111 /** This is a function type which allows the RA layer to invalidate
112  * (i.e., remove) wcprops recursively. See the documentation for
113  * @c svn_ra_get_wc_prop_func_t for @a baton, @a path, and @a name.
114  *
115  * Unlike @c svn_ra_push_wc_prop_func_t, this has immediate effect. If
116  * it returns success, the wcprops have been removed.
117  */
118 typedef svn_error_t *(*svn_ra_invalidate_wc_props_func_t)(void *baton,
119  const char *path,
120  const char *name,
121  apr_pool_t *pool);
122 
123 /** This is a function type which allows the RA layer to fetch the
124  * cached pristine file contents whose checksum is @a checksum, if
125  * any. @a *contents will be a read stream containing those contents
126  * if they are found; NULL otherwise.
127  *
128  * @since New in 1.8.
129  */
130 typedef svn_error_t *
131 (*svn_ra_get_wc_contents_func_t)(void *baton,
132  svn_stream_t **contents,
133  const svn_checksum_t *checksum,
134  apr_pool_t *pool);
135 
136 
137 /** A function type for retrieving the youngest revision from a repos.
138  * @deprecated Provided for backward compatibility with the 1.8 API.
139  */
140 /* ### It seems this type was never used by the API, since 1.0.0. */
141 typedef svn_error_t *(*svn_ra_get_latest_revnum_func_t)(
142  void *session_baton,
143  svn_revnum_t *latest_revnum);
144 
145 /** A function type which allows the RA layer to ask about any
146  * customizations to the client name string. This is primarily used
147  * by HTTP-based RA layers wishing to extend the string reported to
148  * Apache/mod_dav_svn via the User-agent HTTP header.
149  *
150  * @since New in 1.5.
151  */
152 typedef svn_error_t *(*svn_ra_get_client_string_func_t)(void *baton,
153  const char **name,
154  apr_pool_t *pool);
155 
156 
157 
158 /**
159  * A callback function type for use in @c get_file_revs.
160  * @a baton is provided by the caller, @a path is the pathname of the file
161  * in revision @a rev and @a rev_props are the revision properties.
162  * If @a delta_handler and @a delta_baton are non-NULL, they may be set to a
163  * handler/baton which will be called with the delta between the previous
164  * revision and this one after the return of this callback. They may be
165  * left as NULL/NULL.
166  * @a prop_diffs is an array of svn_prop_t elements indicating the property
167  * delta for this and the previous revision.
168  * @a pool may be used for temporary allocations, but you can't rely
169  * on objects allocated to live outside of this particular call and the
170  * immediately following calls to @a *delta_handler, if any.
171  *
172  * @since New in 1.1.
173  */
174 typedef svn_error_t *(*svn_ra_file_rev_handler_t)(
175  void *baton,
176  const char *path,
177  svn_revnum_t rev,
178  apr_hash_t *rev_props,
179  svn_txdelta_window_handler_t *delta_handler,
180  void **delta_baton,
181  apr_array_header_t *prop_diffs,
182  apr_pool_t *pool);
183 
184 /**
185  * Callback function type for locking and unlocking actions.
186  *
187  * @since New in 1.2.
188  *
189  * @a do_lock is TRUE when locking @a path, and FALSE
190  * otherwise.
191  *
192  * @a lock is a lock for @a path or NULL if @a do_lock is FALSE or @a ra_err is
193  * non-NULL.
194  *
195  * @a ra_err is NULL unless the ra layer encounters a locking related
196  * error which it passes back for notification purposes. The caller
197  * is responsible for clearing @a ra_err after the callback is run.
198  *
199  * @a baton is a closure object; it should be provided by the
200  * implementation, and passed by the caller. @a pool may be used for
201  * temporary allocation.
202  */
203 typedef svn_error_t *(*svn_ra_lock_callback_t)(void *baton,
204  const char *path,
205  svn_boolean_t do_lock,
206  const svn_lock_t *lock,
207  svn_error_t *ra_err,
208  apr_pool_t *pool);
209 
210 /**
211  * Callback function type for progress notification.
212  *
213  * @a progress is the number of bytes already transferred, @a total is
214  * the total number of bytes to transfer or -1 if it's not known, @a
215  * baton is the callback baton.
216  *
217  * @since New in 1.3.
218  */
219 typedef void (*svn_ra_progress_notify_func_t)(apr_off_t progress,
220  apr_off_t total,
221  void *baton,
222  apr_pool_t *pool);
223 
224 /**
225  * Callback function type for replay_range actions.
226  *
227  * This callback function should provide replay_range with an editor which
228  * will be driven with the received replay reports from the master repository.
229  *
230  * @a revision is the target revision number of the received replay report.
231  *
232  * @a editor and @a edit_baton should provided by the callback implementation.
233  *
234  * @a replay_baton is the baton as originally passed to replay_range.
235  *
236  * @a revprops contains key/value pairs for each revision properties for this
237  * revision.
238  *
239  * @since New in 1.5.
240  */
241 typedef svn_error_t *(*svn_ra_replay_revstart_callback_t)(
242  svn_revnum_t revision,
243  void *replay_baton,
244  const svn_delta_editor_t **editor,
245  void **edit_baton,
246  apr_hash_t *rev_props,
247  apr_pool_t *pool);
248 
249 /**
250  * Callback function type for replay_range actions.
251  *
252  * This callback function should close the editor.
253  *
254  * @a revision is the target revision number of the received replay report.
255  *
256  * @a editor and @a edit_baton should provided by the callback implementation.
257  *
258  * @a replay_baton is the baton as originally passed to replay_range.
259  *
260  * @a revprops contains key/value pairs for each revision properties for this
261  * revision.
262  *
263  * @since New in 1.5.
264  */
265 typedef svn_error_t *(*svn_ra_replay_revfinish_callback_t)(
266  svn_revnum_t revision,
267  void *replay_baton,
268  const svn_delta_editor_t *editor,
269  void *edit_baton,
270  apr_hash_t *rev_props,
271  apr_pool_t *pool);
272 
273 
274 /**
275  * Callback function that checks if an ra_svn tunnel called
276  * @a tunnel_name is handled by the callbakcs or the default
277  * implementation.
278  *
279  * @a tunnel_baton is the baton as originally passed to ra_open.
280  *
281  * @since New in 1.9.
282  */
284  void *tunnel_baton, const char *tunnel_name);
285 
286 /**
287  * Callback function for closing a tunnel in ra_svn.
288  *
289  * This function will be called when the pool that owns the tunnel
290  * connection is cleared or destroyed.
291  *
292  * @a close_baton is the baton as returned from the
293  * svn_ra_open_tunnel_func_t.
294  *
295  * @a tunnel_baton was returned by the open-tunnel callback.
296  *
297  * @since New in 1.9.
298  */
300  void *close_baton, void *tunnel_baton);
301 
302 /**
303  * Callback function for opening a tunnel in ra_svn.
304  *
305  * Given the @a tunnel_name, tunnel @a user and server @a hostname and
306  * @a port, open a tunnel to the server and return its file handles,
307  * which are owned by @a pool, in @a request and @a response.
308  *
309  * @a request and @a response represent the standard input and output,
310  * respectively, of the process on the other end of the tunnel.
311  *
312  * If @a *close_func is set it will be called with @a close_baton when
313  * the tunnel is closed.
314  *
315  * The optional @a cancel_func callback can be invoked as usual to allow
316  * the user to preempt potentially lengthy operations.
317  *
318  * @a tunnel_baton is the baton as set in the callbacks.
319  *
320  * @since New in 1.9.
321  */
322 typedef svn_error_t *(*svn_ra_open_tunnel_func_t)(
323  svn_stream_t **request, svn_stream_t **response,
324  svn_ra_close_tunnel_func_t *close_func, void **close_baton,
325  void *tunnel_baton,
326  const char *tunnel_name, const char *user,
327  const char *hostname, int port,
328  svn_cancel_func_t cancel_func, void *cancel_baton,
329  apr_pool_t *pool);
330 
331 
332 /**
333  * The update Reporter.
334  *
335  * A vtable structure which allows a working copy to describe a subset
336  * (or possibly all) of its working-copy to an RA layer, for the
337  * purposes of an update, switch, status, or diff operation.
338  *
339  * Paths for report calls are relative to the target (not the anchor)
340  * of the operation. Report calls must be made in depth-first order:
341  * parents before children, all children of a parent before any
342  * siblings of the parent. The first report call must be a set_path
343  * with a @a path argument of "" and a valid revision. (If the target
344  * of the operation is locally deleted or missing, use the anchor's
345  * revision.) If the target of the operation is deleted or switched
346  * relative to the anchor, follow up the initial set_path call with a
347  * link_path or delete_path call with a @a path argument of "" to
348  * indicate that. In no other case may there be two report
349  * descriptions for the same path. If the target of the operation is
350  * a locally added file or directory (which previously did not exist),
351  * it may be reported as having revision 0 or as having the parent
352  * directory's revision.
353  *
354  * @since New in 1.5.
355  */
356 typedef struct svn_ra_reporter3_t
357 {
358  /** Describe a working copy @a path as being at a particular
359  * @a revision and having depth @a depth.
360  *
361  * @a revision may be SVN_INVALID_REVNUM if (for example) @a path
362  * represents a locally-added path with no revision number, or @a
363  * depth is @c svn_depth_exclude.
364  *
365  * @a path may not be underneath a path on which set_path() was
366  * previously called with @c svn_depth_exclude in this report.
367  *
368  * If @a start_empty is set and @a path is a directory, the
369  * implementor should assume the directory has no entries or props.
370  *
371  * This will *override* any previous set_path() calls made on parent
372  * paths. @a path is relative to the URL specified in svn_ra_open4().
373  *
374  * If @a lock_token is non-NULL, it is the lock token for @a path in the WC.
375  *
376  * All temporary allocations are done in @a pool.
377  */
378  svn_error_t *(*set_path)(void *report_baton,
379  const char *path,
380  svn_revnum_t revision,
381  svn_depth_t depth,
382  svn_boolean_t start_empty,
383  const char *lock_token,
384  apr_pool_t *pool);
385 
386  /** Describing a working copy @a path as missing.
387  *
388  * @a path may not be underneath a path on which set_path() was
389  * previously called with @c svn_depth_exclude in this report.
390  *
391  * All temporary allocations are done in @a pool.
392  */
393  svn_error_t *(*delete_path)(void *report_baton,
394  const char *path,
395  apr_pool_t *pool);
396 
397  /** Like set_path(), but differs in that @a path in the working copy
398  * (relative to the root of the report driver) isn't a reflection of
399  * @a path in the repository (relative to the URL specified when
400  * opening the RA layer), but is instead a reflection of a different
401  * repository @a url at @a revision, and has depth @a depth.
402  *
403  * @a path may not be underneath a path on which set_path() was
404  * previously called with @c svn_depth_exclude in this report.
405  *
406  * If @a start_empty is set and @a path is a directory,
407  * the implementor should assume the directory has no entries or props.
408  *
409  * If @a lock_token is non-NULL, it is the lock token for @a path in the WC.
410  *
411  * All temporary allocations are done in @a pool.
412  */
413  svn_error_t *(*link_path)(void *report_baton,
414  const char *path,
415  const char *url,
416  svn_revnum_t revision,
417  svn_depth_t depth,
418  svn_boolean_t start_empty,
419  const char *lock_token,
420  apr_pool_t *pool);
421 
422  /** WC calls this when the state report is finished; any directories
423  * or files not explicitly `set' are assumed to be at the
424  * baseline revision originally passed into do_update(). No other
425  * reporting functions, including abort_report, should be called after
426  * calling this function.
427  */
428  svn_error_t *(*finish_report)(void *report_baton,
429  apr_pool_t *pool);
430 
431  /** If an error occurs during a report, this routine should cause the
432  * filesystem transaction to be aborted & cleaned up. No other reporting
433  * functions should be called after calling this function.
434  */
435  svn_error_t *(*abort_report)(void *report_baton,
436  apr_pool_t *pool);
437 
439 
440 /**
441  * Similar to @c svn_ra_reporter3_t, but without support for depths.
442  *
443  * @deprecated Provided for backward compatibility with the 1.4 API.
444  */
445 typedef struct svn_ra_reporter2_t
446 {
447  /** Similar to the corresponding field in @c svn_ra_reporter3_t, but
448  * with @a depth always set to @c svn_depth_infinity. */
449  svn_error_t *(*set_path)(void *report_baton,
450  const char *path,
451  svn_revnum_t revision,
452  svn_boolean_t start_empty,
453  const char *lock_token,
454  apr_pool_t *pool);
455 
456  /** Same as the corresponding field in @c svn_ra_reporter3_t. */
457  svn_error_t *(*delete_path)(void *report_baton,
458  const char *path,
459  apr_pool_t *pool);
460 
461  /** Similar to the corresponding field in @c svn_ra_reporter3_t, but
462  * with @a depth always set to @c svn_depth_infinity. */
463  svn_error_t *(*link_path)(void *report_baton,
464  const char *path,
465  const char *url,
466  svn_revnum_t revision,
467  svn_boolean_t start_empty,
468  const char *lock_token,
469  apr_pool_t *pool);
470 
471  /** Same as the corresponding field in @c svn_ra_reporter3_t. */
472  svn_error_t *(*finish_report)(void *report_baton,
473  apr_pool_t *pool);
474 
475  /** Same as the corresponding field in @c svn_ra_reporter3_t. */
476  svn_error_t *(*abort_report)(void *report_baton,
477  apr_pool_t *pool);
478 
480 
481 /**
482  * Similar to @c svn_ra_reporter2_t, but without support for lock tokens.
483  *
484  * @deprecated Provided for backward compatibility with the 1.1 API.
485  */
486 typedef struct svn_ra_reporter_t
487 {
488  /** Similar to the corresponding field in @c svn_ra_reporter2_t, but
489  * with @a lock_token always set to NULL. */
490  svn_error_t *(*set_path)(void *report_baton,
491  const char *path,
492  svn_revnum_t revision,
493  svn_boolean_t start_empty,
494  apr_pool_t *pool);
495 
496  /** Same as the corresponding field in @c svn_ra_reporter2_t. */
497  svn_error_t *(*delete_path)(void *report_baton,
498  const char *path,
499  apr_pool_t *pool);
500 
501  /** Similar to the corresponding field in @c svn_ra_reporter2_t, but
502  * with @a lock_token always set to NULL. */
503  svn_error_t *(*link_path)(void *report_baton,
504  const char *path,
505  const char *url,
506  svn_revnum_t revision,
507  svn_boolean_t start_empty,
508  apr_pool_t *pool);
509 
510  /** Same as the corresponding field in @c svn_ra_reporter2_t. */
511  svn_error_t *(*finish_report)(void *report_baton,
512  apr_pool_t *pool);
513 
514  /** Same as the corresponding field in @c svn_ra_reporter2_t. */
515  svn_error_t *(*abort_report)(void *report_baton,
516  apr_pool_t *pool);
518 
519 
520 /** A collection of callbacks implemented by libsvn_client which allows
521  * an RA layer to "pull" information from the client application, or
522  * possibly store information. libsvn_client passes this vtable to
523  * svn_ra_open4().
524  *
525  * Each routine takes a @a callback_baton originally provided with the
526  * vtable.
527  *
528  * Clients must use svn_ra_create_callbacks() to allocate and
529  * initialize this structure.
530  *
531  * @since New in 1.3.
532  */
533 typedef struct svn_ra_callbacks2_t
534 {
535  /** Open a unique temporary file for writing in the working copy.
536  * This file will be automatically deleted when @a fp is closed.
537  *
538  * @deprecated This callback should no longer be used by RA layers.
539  */
540  svn_error_t *(*open_tmp_file)(apr_file_t **fp,
541  void *callback_baton,
542  apr_pool_t *pool);
543 
544  /** An authentication baton, created by the application, which is
545  * capable of retrieving all known types of credentials.
546  */
548 
549  /*** The following items may be set to NULL to disallow the RA layer
550  to perform the respective operations of the vtable functions.
551  Perhaps WC props are not defined or are in invalid for this
552  session, or perhaps the commit operation this RA session will
553  perform is a server-side only one that shouldn't do post-commit
554  processing on a working copy path. ***/
555 
556  /** Fetch working copy properties.
557  *
558  *<pre> ### we might have a problem if the RA layer ever wants a property
559  * ### that corresponds to a different revision of the file than
560  * ### what is in the WC. we'll cross that bridge one day...</pre>
561  */
563 
564  /** Immediately set new values for working copy properties. */
566 
567  /** Schedule new values for working copy properties. */
569 
570  /** Invalidate working copy properties. */
572 
573  /** Notification callback used for progress information.
574  * May be NULL if not used.
575  */
577 
578  /** Notification callback baton, used with progress_func. */
580 
581  /** Cancellation function
582  *
583  * As its baton, the general callback baton is used
584  *
585  * @since New in 1.5
586  */
588 
589  /** Client string customization callback function
590  * @since New in 1.5
591  */
593 
594  /** Working copy file content fetching function.
595  * @since New in 1.8.
596  */
598 
599  /** Check-tunnel callback
600  *
601  * If not @c NULL, and open_tunnel_func is also not @c NULL, this
602  * callback will be invoked to check if open_tunnel_func should be
603  * used to create a specific tunnel, or if the default tunnel
604  * implementation (either built-in or configured in the client
605  * configuration file) should be used instead.
606  * @since New in 1.9.
607  */
609 
610  /** Open-tunnel callback
611  *
612  * If not @c NULL, this callback will be invoked to create a tunnel
613  * for a ra_svn connection that needs one, overriding any tunnel
614  * definitions in the client config file. This callback is used only
615  * for ra_svn and ignored by the other RA modules.
616  * @since New in 1.9.
617  */
619 
620  /** A baton used with open_tunnel_func and close_tunnel_func.
621  * @since New in 1.9.
622  */
625 
626 /** Similar to svn_ra_callbacks2_t, except that the progress
627  * notification function and baton is missing.
628  *
629  * @deprecated Provided for backward compatibility with the 1.2 API.
630  */
631 typedef struct svn_ra_callbacks_t
632 {
633  svn_error_t *(*open_tmp_file)(apr_file_t **fp,
634  void *callback_baton,
635  apr_pool_t *pool);
636 
637  svn_auth_baton_t *auth_baton;
638 
639  svn_ra_get_wc_prop_func_t get_wc_prop;
640 
641  svn_ra_set_wc_prop_func_t set_wc_prop;
642 
643  svn_ra_push_wc_prop_func_t push_wc_prop;
644 
645  svn_ra_invalidate_wc_props_func_t invalidate_wc_props;
646 
648 
649 
650 
651 /*----------------------------------------------------------------------*/
652 
653 /* Public Interfaces. */
654 
655 /**
656  * Initialize the RA library. This function must be called before using
657  * any function in this header, except the deprecated APIs based on
658  * @c svn_ra_plugin_t, or svn_ra_version(). This function must not be called
659  * simultaneously in multiple threads. @a pool must live
660  * longer than any open RA sessions.
661  *
662  * @since New in 1.2.
663  */
664 svn_error_t *
665 svn_ra_initialize(apr_pool_t *pool);
666 
667 /** Initialize a callback structure.
668 * Set @a *callbacks to a ra callbacks object, allocated in @a pool.
669 *
670 * Clients must use this function to allocate and initialize @c
671 * svn_ra_callbacks2_t structures.
672 *
673 * @since New in 1.3.
674 */
675 svn_error_t *
677  apr_pool_t *pool);
678 
679 /**
680  * A repository access session. This object is used to perform requests
681  * to a repository, identified by a URL.
682  *
683  * @since New in 1.2.
684  */
686 
687 /**
688  * Open a repository access session to the repository at @a repos_URL,
689  * or inform the caller regarding a correct URL by which to access
690  * that repository.
691  *
692  * If @a repos_URL can be used successfully to access the repository,
693  * set @a *session_p to an opaque object representing a repository
694  * session for the repository and (if @a corrected_url is non-NULL)
695  * set @a *corrected_url to NULL. If there's a better URL that the
696  * caller should try and @a corrected_url is non-NULL, set
697  * @a *session_p to NULL and @a *corrected_url to the corrected URL. If
698  * there's a better URL that the caller should try, and @a
699  * corrected_url is NULL, return an #SVN_ERR_RA_SESSION_URL_MISMATCH
700  * error. Allocate all returned items in @a pool.
701  *
702  * The @a repos_URL need not point to the root of the repository: subject
703  * to authorization, it may point to any path within the repository, even
704  * a path at which no node exists in the repository. The session will
705  * remember this URL as its "session URL" (also called "session root URL"),
706  * until changed by svn_ra_reparent(). Many RA functions take or return
707  * paths that are relative to the session URL.
708  *
709  * If a @a corrected_url is returned, it will point to the same path
710  * within the new repository root URL that @a repos_URL pointed to within
711  * the old repository root URL.
712  *
713  * Return @c SVN_ERR_RA_UUID_MISMATCH if @a uuid is non-NULL and not equal
714  * to the UUID of the repository at @c repos_URL.
715  *
716  * @a callbacks/@a callback_baton is a table of callbacks provided by the
717  * client; see @c svn_ra_callbacks2_t.
718  *
719  * @a config is a hash mapping <tt>const char *</tt> keys to
720  * @c svn_config_t * values. For example, the @c svn_config_t for the
721  * "~/.subversion/config" file is under the key "config". @a config may
722  * be NULL. This function examines some config settings under the
723  * "servers" key (if present) before loading the required RA module, and
724  * the RA module may also examine any config settings.
725  *
726  * All RA requests require a session; they will continue to
727  * use @a pool for memory allocation.
728  *
729  * @see svn_client_open_ra_session().
730  *
731  * @since New in 1.7.
732  */
733 svn_error_t *
734 svn_ra_open4(svn_ra_session_t **session_p,
735  const char **corrected_url,
736  const char *repos_URL,
737  const char *uuid,
738  const svn_ra_callbacks2_t *callbacks,
739  void *callback_baton,
740  apr_hash_t *config,
741  apr_pool_t *pool);
742 
743 /** Similar to svn_ra_open4(), but with @a corrected_url always passed
744  * as @c NULL.
745  *
746  * @since New in 1.5.
747  * @deprecated Provided for backward compatibility with the 1.6 API.
748  */
750 svn_error_t *
751 svn_ra_open3(svn_ra_session_t **session_p,
752  const char *repos_URL,
753  const char *uuid,
754  const svn_ra_callbacks2_t *callbacks,
755  void *callback_baton,
756  apr_hash_t *config,
757  apr_pool_t *pool);
758 
759 /**
760  * Similar to svn_ra_open3(), but with @a uuid set to @c NULL.
761  *
762  * @since New in 1.3.
763  * @deprecated Provided for backward compatibility with the 1.4 API.
764  */
766 svn_error_t *
767 svn_ra_open2(svn_ra_session_t **session_p,
768  const char *repos_URL,
769  const svn_ra_callbacks2_t *callbacks,
770  void *callback_baton,
771  apr_hash_t *config,
772  apr_pool_t *pool);
773 
774 /**
775  * @see svn_ra_open2().
776  * @since New in 1.2.
777  * @deprecated Provided for backward compatibility with the 1.2 API.
778  */
780 svn_error_t *
781 svn_ra_open(svn_ra_session_t **session_p,
782  const char *repos_URL,
783  const svn_ra_callbacks_t *callbacks,
784  void *callback_baton,
785  apr_hash_t *config,
786  apr_pool_t *pool);
787 
788 /** Change the root URL of an open @a ra_session to point to a new path in the
789  * same repository. @a url is the new root URL. Use @a pool for
790  * temporary allocations.
791  *
792  * If @a url has a different repository root than the current session
793  * URL, return @c SVN_ERR_RA_ILLEGAL_URL.
794  *
795  * @since New in 1.4.
796  */
797 svn_error_t *
799  const char *url,
800  apr_pool_t *pool);
801 
802 /** Set @a *url to the session URL -- the URL to which @a ra_session was
803  * opened or most recently reparented.
804  *
805  * @since New in 1.5.
806  */
807 svn_error_t *
809  const char **url,
810  apr_pool_t *pool);
811 
812 
813 /** Convert @a url into a path relative to the session URL of @a ra_session,
814  * setting @a *rel_path to that value. If @a url is not
815  * a child of the session URL, return @c SVN_ERR_RA_ILLEGAL_URL.
816  *
817  * The returned path is uri decoded to allow using it with the ra or other
818  * apis as a valid relpath.
819  *
820  * @since New in 1.7.
821  */
822 svn_error_t *
824  const char **rel_path,
825  const char *url,
826  apr_pool_t *pool);
827 
828 /** Convert @a url into a path relative to the repository root URL of
829  * the repository with which @a ra_session is associated, setting @a
830  * *rel_path to that value. If @a url is not a child of repository
831  * root URL, return @c SVN_ERR_RA_ILLEGAL_URL.
832  *
833  * The returned path is uri decoded to allow using it with the ra or other
834  * apis as a valid relpath.
835  *
836  * @since New in 1.7.
837  */
838 svn_error_t *
840  const char **rel_path,
841  const char *url,
842  apr_pool_t *pool);
843 
844 /**
845  * Get the latest revision number from the repository of @a session.
846  *
847  * Use @a pool for memory allocation.
848  *
849  * @since New in 1.2.
850  */
851 svn_error_t *
853  svn_revnum_t *latest_revnum,
854  apr_pool_t *pool);
855 
856 /**
857  * Get the latest revision number at time @a tm in the repository of
858  * @a session.
859  *
860  * Use @a pool for memory allocation.
861  *
862  * @since New in 1.2.
863  */
864 svn_error_t *
866  svn_revnum_t *revision,
867  apr_time_t tm,
868  apr_pool_t *pool);
869 
870 /**
871  * Set the property @a name to @a value on revision @a rev in the repository
872  * of @a session.
873  *
874  * If @a value is @c NULL, delete the named revision property.
875  *
876  * If the server advertises the #SVN_RA_CAPABILITY_ATOMIC_REVPROPS capability
877  * and @a old_value_p is not @c NULL, then changing the property will fail with
878  * an error chain that contains #SVN_ERR_FS_PROP_BASEVALUE_MISMATCH if the
879  * present value of the property is not @a *old_value_p. (This is an atomic
880  * test-and-set).
881  * @a *old_value_p may be @c NULL, representing that the property must be not
882  * already set.
883  *
884  * If the capability is not advertised, then @a old_value_p MUST be @c NULL.
885  *
886  * Please note that properties attached to revisions are @em unversioned.
887  *
888  * Use @a pool for memory allocation.
889  *
890  * @see svn_fs_change_rev_prop2(), svn_error_find_cause().
891  *
892  * @since New in 1.7.
893  */
894 svn_error_t *
896  svn_revnum_t rev,
897  const char *name,
898  const svn_string_t *const *old_value_p,
899  const svn_string_t *value,
900  apr_pool_t *pool);
901 
902 /**
903  * Similar to svn_ra_change_rev_prop2(), but with @a old_value_p set
904  * to @c NULL.
905  *
906  * @since New in 1.2.
907  * @deprecated Provided for backward compatibility with the 1.6 API.
908  */
910 svn_error_t *
912  svn_revnum_t rev,
913  const char *name,
914  const svn_string_t *value,
915  apr_pool_t *pool);
916 
917 /**
918  * Set @a *props to the list of unversioned properties attached to revision
919  * @a rev in the repository of @a session. The hash maps
920  * (<tt>const char *</tt>) names to (<tt>@c svn_string_t *</tt>) values.
921  *
922  * Use @a pool for memory allocation.
923  *
924  * @since New in 1.2.
925  */
926 svn_error_t *
928  svn_revnum_t rev,
929  apr_hash_t **props,
930  apr_pool_t *pool);
931 
932 /**
933  * Set @a *value to the value of unversioned property @a name attached to
934  * revision @a rev in the repository of @a session. If @a rev has no
935  * property by that name, set @a *value to @c NULL.
936  *
937  * Use @a pool for memory allocation.
938  *
939  * @since New in 1.2.
940  */
941 svn_error_t *
943  svn_revnum_t rev,
944  const char *name,
945  svn_string_t **value,
946  apr_pool_t *pool);
947 
948 /**
949  * Set @a *editor and @a *edit_baton to an editor for committing
950  * changes to the repository of @a session, setting the revision
951  * properties from @a revprop_table. The revisions being committed
952  * against are passed to the editor functions, starting with the rev
953  * argument to @c open_root. The path root of the commit is the @a
954  * session's URL.
955  *
956  * @a revprop_table is a hash mapping <tt>const char *</tt> property
957  * names to @c svn_string_t property values. The commit log message
958  * is expected to be in the @c SVN_PROP_REVISION_LOG element. @a
959  * revprop_table can not contain either of @c SVN_PROP_REVISION_DATE
960  * or @c SVN_PROP_REVISION_AUTHOR.
961  *
962  * Before @c close_edit returns, but after the commit has succeeded,
963  * it will invoke @a commit_callback (if non-NULL) with filled-in
964  * #svn_commit_info_t *, @a commit_baton, and @a pool or some subpool
965  * thereof as arguments. If @a commit_callback returns an error, that error
966  * will be returned from @c * close_edit, otherwise @c close_edit will return
967  * successfully (unless it encountered an error before invoking
968  * @a commit_callback).
969  *
970  * The callback will not be called if the commit was a no-op
971  * (i.e. nothing was committed);
972  *
973  * @a lock_tokens, if non-NULL, is a hash mapping <tt>const char
974  * *</tt> paths (relative to the URL of @a session) to <tt>
975  * const char *</tt> lock tokens. The server checks that the
976  * correct token is provided for each committed, locked path. @a lock_tokens
977  * must live during the whole commit operation.
978  *
979  * If @a keep_locks is @c TRUE, then do not release locks on
980  * committed objects. Else, automatically release such locks.
981  *
982  * The caller may not perform any RA operations using @a session before
983  * finishing the edit.
984  *
985  * Use @a pool for memory allocation.
986  *
987  * @since New in 1.5.
988  *
989  * @note Like most commit editors, the returned editor requires that the
990  * @c copyfrom_path parameter passed to its @c add_file and @c add_directory
991  * methods is a URL, not a relative path.
992  */
993 svn_error_t *
995  const svn_delta_editor_t **editor,
996  void **edit_baton,
997  apr_hash_t *revprop_table,
998  svn_commit_callback2_t commit_callback,
999  void *commit_baton,
1000  apr_hash_t *lock_tokens,
1001  svn_boolean_t keep_locks,
1002  apr_pool_t *pool);
1003 
1004 /**
1005  * Same as svn_ra_get_commit_editor3(), but with @c revprop_table set
1006  * to a hash containing the @c SVN_PROP_REVISION_LOG property set
1007  * to the value of @a log_msg.
1008  *
1009  * @since New in 1.4.
1010  *
1011  * @deprecated Provided for backward compatibility with the 1.4 API.
1012  */
1014 svn_error_t *
1016  const svn_delta_editor_t **editor,
1017  void **edit_baton,
1018  const char *log_msg,
1019  svn_commit_callback2_t commit_callback,
1020  void *commit_baton,
1021  apr_hash_t *lock_tokens,
1022  svn_boolean_t keep_locks,
1023  apr_pool_t *pool);
1024 
1025 /**
1026  * Same as svn_ra_get_commit_editor2(), but uses @c svn_commit_callback_t.
1027  *
1028  * @since New in 1.2.
1029  *
1030  * @deprecated Provided for backward compatibility with the 1.3 API.
1031  */
1033 svn_error_t *
1035  const svn_delta_editor_t **editor,
1036  void **edit_baton,
1037  const char *log_msg,
1038  svn_commit_callback_t callback,
1039  void *callback_baton,
1040  apr_hash_t *lock_tokens,
1041  svn_boolean_t keep_locks,
1042  apr_pool_t *pool);
1043 
1044 /**
1045  * Fetch the contents and properties of file @a path at @a revision.
1046  * @a revision may be SVN_INVALID_REVNUM, indicating that the HEAD
1047  * revision should be used. Interpret @a path relative to the URL in
1048  * @a session. Use @a pool for all allocations.
1049  *
1050  * If @a revision is @c SVN_INVALID_REVNUM and @a fetched_rev is not
1051  * @c NULL, then set @a *fetched_rev to the actual revision that was
1052  * retrieved.
1053  *
1054  * If @a stream is non @c NULL, push the contents of the file at @a
1055  * stream, do not call svn_stream_close() when finished.
1056  *
1057  * If @a props is non @c NULL, set @a *props to contain the properties of
1058  * the file. This means @em all properties: not just ones controlled by
1059  * the user and stored in the repository fs, but non-tweakable ones
1060  * generated by the SCM system itself (e.g. 'wcprops', 'entryprops',
1061  * etc.) The keys are <tt>const char *</tt>, values are
1062  * <tt>@c svn_string_t *</tt>.
1063  *
1064  * The stream handlers for @a stream may not perform any RA
1065  * operations using @a session.
1066  *
1067  * @since New in 1.2.
1068  */
1069 svn_error_t *
1071  const char *path,
1072  svn_revnum_t revision,
1073  svn_stream_t *stream,
1074  svn_revnum_t *fetched_rev,
1075  apr_hash_t **props,
1076  apr_pool_t *pool);
1077 
1078 /**
1079  * If @a dirents is non @c NULL, set @a *dirents to contain all the entries
1080  * of directory @a path at @a revision. The keys of @a dirents will be
1081  * entry names (<tt>const char *</tt>), and the values dirents
1082  * (<tt>@c svn_dirent_t *</tt>). Use @a pool for all allocations.
1083  *
1084  * @a dirent_fields controls which portions of the <tt>@c svn_dirent_t</tt>
1085  * objects are filled in. To have them completely filled in just pass
1086  * @c SVN_DIRENT_ALL, otherwise pass the bitwise OR of all the @c SVN_DIRENT_
1087  * fields you would like to have returned to you.
1088  *
1089  * @a path is interpreted relative to the URL in @a session.
1090  *
1091  * If @a revision is @c SVN_INVALID_REVNUM (meaning 'head') and
1092  * @a *fetched_rev is not @c NULL, then this function will set
1093  * @a *fetched_rev to the actual revision that was retrieved. (Some
1094  * callers want to know, and some don't.)
1095  *
1096  * If @a props is non @c NULL, set @a *props to contain the properties of
1097  * the directory, including properties that are non-tweakable and
1098  * generated by the SCM system itself (such as #svn_prop_wc_kind and
1099  * #svn_prop_entry_kind properties). The keys are <tt>const char *</tt>,
1100  * values are <tt>@c svn_string_t *</tt>.
1101  *
1102  * @since New in 1.4.
1103  */
1104 svn_error_t *
1106  apr_hash_t **dirents,
1107  svn_revnum_t *fetched_rev,
1108  apr_hash_t **props,
1109  const char *path,
1110  svn_revnum_t revision,
1111  apr_uint32_t dirent_fields,
1112  apr_pool_t *pool);
1113 
1114 /**
1115  * Similar to @c svn_ra_get_dir2, but with @c SVN_DIRENT_ALL for the
1116  * @a dirent_fields parameter.
1117  *
1118  * @since New in 1.2.
1119  *
1120  * @deprecated Provided for compatibility with the 1.3 API.
1121  */
1123 svn_error_t *
1125  const char *path,
1126  svn_revnum_t revision,
1127  apr_hash_t **dirents,
1128  svn_revnum_t *fetched_rev,
1129  apr_hash_t **props,
1130  apr_pool_t *pool);
1131 
1132 /**
1133  * Set @a *catalog to a mergeinfo catalog for the paths in @a paths.
1134  * If no mergeinfo is available, set @a *catalog to @c NULL. The
1135  * requested mergeinfo hashes are for @a paths (which are relative to
1136  * @a session's URL) in @a revision. If one of the paths does not exist
1137  * in that revision, return SVN_ERR_FS_NOT_FOUND.
1138  *
1139  * @a inherit indicates whether explicit, explicit or inherited, or
1140  * only inherited mergeinfo for @a paths is retrieved.
1141  *
1142  * If @a include_descendants is TRUE, then additionally return the
1143  * mergeinfo for any descendant of any element of @a paths which has
1144  * the @c SVN_PROP_MERGEINFO property explicitly set on it. (Note
1145  * that inheritance is only taken into account for the elements in @a
1146  * paths; descendants of the elements in @a paths which get their
1147  * mergeinfo via inheritance are not included in @a *catalog.)
1148  *
1149  * Allocate the returned values in @a pool.
1150  *
1151  * If @a revision is @c SVN_INVALID_REVNUM, it defaults to youngest.
1152  *
1153  * If the server doesn't support retrieval of mergeinfo (which can
1154  * happen even for file:// URLs, if the repository itself hasn't been
1155  * upgraded), return @c SVN_ERR_UNSUPPORTED_FEATURE in preference to
1156  * any other error that might otherwise be returned.
1157  *
1158  * @since New in 1.5.
1159  */
1160 svn_error_t *
1162  svn_mergeinfo_catalog_t *catalog,
1163  const apr_array_header_t *paths,
1164  svn_revnum_t revision,
1166  svn_boolean_t include_descendants,
1167  apr_pool_t *pool);
1168 
1169 /**
1170  * Ask the RA layer to update a working copy to a new revision.
1171  *
1172  * The client initially provides an @a update_editor/@a update_baton to the
1173  * RA layer; this editor contains knowledge of where the change will
1174  * begin in the working copy (when @c open_root() is called).
1175  *
1176  * In return, the client receives a @a reporter/@a report_baton. The
1177  * client then describes its working copy by making calls into the
1178  * @a reporter.
1179  *
1180  * When finished, the client calls @a reporter->finish_report(). The
1181  * RA layer then does a complete drive of @a update_editor, ending with
1182  * @a update_editor->close_edit(), to update the working copy.
1183  *
1184  * @a update_target is an optional single path component to restrict
1185  * the scope of the update to just that entry (in the directory
1186  * represented by the @a session's URL). If @a update_target is the
1187  * empty string, the entire directory is updated.
1188  *
1189  * Update the target only as deeply as @a depth indicates.
1190  *
1191  * If @a send_copyfrom_args is TRUE, then ask the server to send
1192  * copyfrom arguments to add_file() and add_directory() when possible.
1193  * (Note: this means that any subsequent txdeltas coming from the
1194  * server are presumed to apply against the copied file!)
1195  *
1196  * Use @a ignore_ancestry to control whether or not items being
1197  * updated will be checked for relatedness first. Unrelated items
1198  * are typically transmitted to the editor as a deletion of one thing
1199  * and the addition of another, but if this flag is @c TRUE,
1200  * unrelated items will be diffed as if they were related.
1201  *
1202  * The working copy will be updated to @a revision_to_update_to, or the
1203  * "latest" revision if this arg is invalid.
1204  *
1205  * The caller may not perform any RA operations using @a session before
1206  * finishing the report, and may not perform any RA operations using
1207  * @a session from within the editing operations of @a update_editor.
1208  *
1209  * Allocate @a *reporter and @a *report_baton in @a result_pool. Use
1210  * @a scratch_pool for temporary allocations.
1211  *
1212  * @note The reporter provided by this function does NOT supply copy-
1213  * from information to the diff editor callbacks.
1214  *
1215  * @note In order to prevent pre-1.5 servers from doing more work than
1216  * needed, and sending too much data back, a pre-1.5 'recurse'
1217  * directive may be sent to the server, based on @a depth.
1218  *
1219  * @note Pre Subversion 1.8 svnserve based servers never ignore ancestry.
1220  *
1221  * @note This differs from calling svn_ra_do_switch3() with the current
1222  * URL of the target node. Update changes only the revision numbers,
1223  * leaving any switched subtrees still switched, whereas switch changes
1224  * every node in the tree to a child of the same URL.
1225  *
1226  * @since New in 1.8.
1227  */
1228 svn_error_t *
1230  const svn_ra_reporter3_t **reporter,
1231  void **report_baton,
1232  svn_revnum_t revision_to_update_to,
1233  const char *update_target,
1234  svn_depth_t depth,
1235  svn_boolean_t send_copyfrom_args,
1236  svn_boolean_t ignore_ancestry,
1237  const svn_delta_editor_t *update_editor,
1238  void *update_baton,
1239  apr_pool_t *result_pool,
1240  apr_pool_t *scratch_pool);
1241 
1242 /**
1243  * Similar to svn_ra_do_update3(), but always ignoring ancestry.
1244  *
1245  * @since New in 1.5.
1246  * @deprecated Provided for compatibility with the 1.4 API.
1247  */
1249 svn_error_t *
1251  const svn_ra_reporter3_t **reporter,
1252  void **report_baton,
1253  svn_revnum_t revision_to_update_to,
1254  const char *update_target,
1255  svn_depth_t depth,
1256  svn_boolean_t send_copyfrom_args,
1257  const svn_delta_editor_t *update_editor,
1258  void *update_baton,
1259  apr_pool_t *pool);
1260 
1261 /**
1262  * Similar to svn_ra_do_update2(), but taking @c svn_ra_reporter2_t
1263  * instead of @c svn_ra_reporter3_t; if @a recurse is true, pass @c
1264  * svn_depth_infinity for @a depth, else pass @c svn_depth_files; and
1265  * with @a send_copyfrom_args always false.
1266  *
1267  * @deprecated Provided for compatibility with the 1.4 API.
1268  */
1270 svn_error_t *
1272  const svn_ra_reporter2_t **reporter,
1273  void **report_baton,
1274  svn_revnum_t revision_to_update_to,
1275  const char *update_target,
1276  svn_boolean_t recurse,
1277  const svn_delta_editor_t *update_editor,
1278  void *update_baton,
1279  apr_pool_t *pool);
1280 
1281 
1282 /**
1283  * Ask the RA layer to switch a working copy to a new revision and URL.
1284  *
1285  * This is similar to svn_ra_do_update3(), but also changes the URL of
1286  * every node in the target tree to a child of the @a switch_url. In
1287  * contrast, update changes only the revision numbers, leaving any
1288  * switched subtrees still switched.
1289  *
1290  * @note Pre Subversion 1.8 svnserve based servers always ignore ancestry
1291  * and never send copyfrom data.
1292  *
1293  * @since New in 1.8.
1294  */
1295 svn_error_t *
1297  const svn_ra_reporter3_t **reporter,
1298  void **report_baton,
1299  svn_revnum_t revision_to_switch_to,
1300  const char *switch_target,
1301  svn_depth_t depth,
1302  const char *switch_url,
1303  svn_boolean_t send_copyfrom_args,
1304  svn_boolean_t ignore_ancestry,
1305  const svn_delta_editor_t *switch_editor,
1306  void *switch_baton,
1307  apr_pool_t *result_pool,
1308  apr_pool_t *scratch_pool);
1309 
1310 /**
1311  * Similar to svn_ra_do_switch3(), but always ignoring ancestry and
1312  * never sending copyfrom_args.
1313  *
1314  * @since New in 1.5.
1315  * @deprecated Provided for compatibility with the 1.7 API.
1316  */
1318 svn_error_t *
1320  const svn_ra_reporter3_t **reporter,
1321  void **report_baton,
1322  svn_revnum_t revision_to_switch_to,
1323  const char *switch_target,
1324  svn_depth_t depth,
1325  const char *switch_url,
1326  const svn_delta_editor_t *switch_editor,
1327  void *switch_baton,
1328  apr_pool_t *pool);
1329 
1330 /**
1331  * Similar to svn_ra_do_switch2(), but taking @c svn_ra_reporter2_t
1332  * instead of @c svn_ra_reporter3_t, and therefore only able to report
1333  * @c svn_depth_infinity for depths. The switch itself is performed
1334  * according to @a recurse: if TRUE, then use @c svn_depth_infinity
1335  * for @a depth, else use @c svn_depth_files.
1336  *
1337  * @deprecated Provided for compatibility with the 1.4 API.
1338  */
1340 svn_error_t *
1342  const svn_ra_reporter2_t **reporter,
1343  void **report_baton,
1344  svn_revnum_t revision_to_switch_to,
1345  const char *switch_target,
1346  svn_boolean_t recurse,
1347  const char *switch_url,
1348  const svn_delta_editor_t *switch_editor,
1349  void *switch_baton,
1350  apr_pool_t *pool);
1351 
1352 /**
1353  * Ask the RA layer to describe the status of a working copy with respect
1354  * to @a revision of the repository (or HEAD, if @a revision is invalid).
1355  *
1356  * The client initially provides a @a status_editor/@a status_baton to the RA
1357  * layer; this editor contains knowledge of where the change will
1358  * begin in the working copy (when open_root() is called).
1359  *
1360  * In return, the client receives a @a reporter/@a report_baton. The
1361  * client then describes its working copy by making calls into the
1362  * @a reporter.
1363  *
1364  * When finished, the client calls @a reporter->finish_report(). The RA
1365  * layer then does a complete drive of @a status_editor, ending with
1366  * close_edit(), to report, essentially, what would be modified in
1367  * the working copy were the client to call do_update().
1368  * @a status_target is an optional single path component will restrict
1369  * the scope of the status report to an entry in the directory
1370  * represented by the @a session's URL, or empty if the entire directory
1371  * is meant to be examined.
1372  *
1373  * Get status as deeply as @a depth indicates. If @a depth is
1374  * #svn_depth_unknown, get the status down to the ambient depth of the
1375  * working copy. If @a depth is deeper than the working copy, include changes
1376  * that would be needed to populate the working copy to that depth.
1377  *
1378  * The caller may not perform any RA operations using @a session
1379  * before finishing the report, and may not perform any RA operations
1380  * using @a session from within the editing operations of @a status_editor.
1381  *
1382  * Use @a pool for memory allocation.
1383  *
1384  * @note The reporter provided by this function does NOT supply copy-
1385  * from information to the diff editor callbacks.
1386  *
1387  * @note In order to prevent pre-1.5 servers from doing more work than
1388  * needed, and sending too much data back, a pre-1.5 'recurse'
1389  * directive may be sent to the server, based on @a depth.
1390  *
1391  * @since New in 1.5.
1392  */
1393 svn_error_t *
1395  const svn_ra_reporter3_t **reporter,
1396  void **report_baton,
1397  const char *status_target,
1398  svn_revnum_t revision,
1399  svn_depth_t depth,
1400  const svn_delta_editor_t *status_editor,
1401  void *status_baton,
1402  apr_pool_t *pool);
1403 
1404 
1405 /**
1406  * Similar to svn_ra_do_status2(), but taking @c svn_ra_reporter2_t
1407  * instead of @c svn_ra_reporter3_t, and therefore only able to report
1408  * @c svn_depth_infinity for depths. The status operation itself is
1409  * performed according to @a recurse: if TRUE, then @a depth is
1410  * @c svn_depth_infinity, else it is @c svn_depth_immediates.
1411  *
1412  * @deprecated Provided for compatibility with the 1.4 API.
1413  */
1415 svn_error_t *
1417  const svn_ra_reporter2_t **reporter,
1418  void **report_baton,
1419  const char *status_target,
1420  svn_revnum_t revision,
1421  svn_boolean_t recurse,
1422  const svn_delta_editor_t *status_editor,
1423  void *status_baton,
1424  apr_pool_t *pool);
1425 
1426 /**
1427  * Ask the RA layer to 'diff' a working copy against @a versus_url;
1428  * it's another form of svn_ra_do_update2().
1429  *
1430  * @note This function cannot be used to diff a single file, only a
1431  * working copy directory. See the svn_ra_do_switch3() function
1432  * for more details.
1433  *
1434  * The client initially provides a @a diff_editor/@a diff_baton to the RA
1435  * layer; this editor contains knowledge of where the common diff
1436  * root is in the working copy (when open_root() is called).
1437  *
1438  * In return, the client receives a @a reporter/@a report_baton. The
1439  * client then describes its working copy by making calls into the
1440  * @a reporter.
1441  *
1442  * When finished, the client calls @a reporter->finish_report(). The
1443  * RA layer then does a complete drive of @a diff_editor, ending with
1444  * close_edit(), to transmit the diff.
1445  *
1446  * @a diff_target is an optional single path component will restrict
1447  * the scope of the diff to an entry in the directory represented by
1448  * the @a session's URL, or empty if the entire directory is meant to be
1449  * one of the diff paths.
1450  *
1451  * The working copy will be diffed against @a versus_url as it exists
1452  * in revision @a revision, or as it is in head if @a revision is
1453  * @c SVN_INVALID_REVNUM.
1454  *
1455  * Use @a ignore_ancestry to control whether or not items being
1456  * diffed will be checked for relatedness first. Unrelated items
1457  * are typically transmitted to the editor as a deletion of one thing
1458  * and the addition of another, but if this flag is @c TRUE,
1459  * unrelated items will be diffed as if they were related.
1460  *
1461  * Diff only as deeply as @a depth indicates.
1462  *
1463  * The caller may not perform any RA operations using @a session before
1464  * finishing the report, and may not perform any RA operations using
1465  * @a session from within the editing operations of @a diff_editor.
1466  *
1467  * @a text_deltas instructs the driver of the @a diff_editor to enable
1468  * the generation of text deltas. If @a text_deltas is FALSE the window
1469  * handler returned by apply_textdelta will be called once with a NULL
1470  * @c svn_txdelta_window_t pointer.
1471  *
1472  * Use @a pool for memory allocation.
1473  *
1474  * @note The reporter provided by this function does NOT supply copy-
1475  * from information to the diff editor callbacks.
1476  *
1477  * @note In order to prevent pre-1.5 servers from doing more work than
1478  * needed, and sending too much data back, a pre-1.5 'recurse'
1479  * directive may be sent to the server, based on @a depth.
1480  *
1481  * @since New in 1.5.
1482  */
1483 svn_error_t *
1485  const svn_ra_reporter3_t **reporter,
1486  void **report_baton,
1487  svn_revnum_t revision,
1488  const char *diff_target,
1489  svn_depth_t depth,
1490  svn_boolean_t ignore_ancestry,
1491  svn_boolean_t text_deltas,
1492  const char *versus_url,
1493  const svn_delta_editor_t *diff_editor,
1494  void *diff_baton,
1495  apr_pool_t *pool);
1496 
1497 /**
1498  * Similar to svn_ra_do_diff3(), but taking @c svn_ra_reporter2_t
1499  * instead of @c svn_ra_reporter3_t, and therefore only able to report
1500  * @c svn_depth_infinity for depths. Perform the diff according to
1501  * @a recurse: if TRUE, then @a depth is @c svn_depth_infinity, else
1502  * it is @c svn_depth_files.
1503  *
1504  * @deprecated Provided for compatibility with the 1.4 API.
1505  */
1507 svn_error_t *
1509  const svn_ra_reporter2_t **reporter,
1510  void **report_baton,
1511  svn_revnum_t revision,
1512  const char *diff_target,
1513  svn_boolean_t recurse,
1514  svn_boolean_t ignore_ancestry,
1515  svn_boolean_t text_deltas,
1516  const char *versus_url,
1517  const svn_delta_editor_t *diff_editor,
1518  void *diff_baton,
1519  apr_pool_t *pool);
1520 
1521 
1522 /**
1523  * Similar to svn_ra_do_diff2(), but with @a text_deltas set to @c TRUE.
1524  *
1525  * @deprecated Provided for backward compatibility with the 1.3 API.
1526  */
1528 svn_error_t *
1530  const svn_ra_reporter2_t **reporter,
1531  void **report_baton,
1532  svn_revnum_t revision,
1533  const char *diff_target,
1534  svn_boolean_t recurse,
1535  svn_boolean_t ignore_ancestry,
1536  const char *versus_url,
1537  const svn_delta_editor_t *diff_editor,
1538  void *diff_baton,
1539  apr_pool_t *pool);
1540 
1541 /**
1542  * Invoke @a receiver with @a receiver_baton on each log message from
1543  * @a start to @a end. @a start may be greater or less than @a end;
1544  * this just controls whether the log messages are processed in descending
1545  * or ascending revision number order.
1546  *
1547  * If @a start or @a end is @c SVN_INVALID_REVNUM, it defaults to youngest.
1548  *
1549  * If @a paths is non-NULL and has one or more elements, then only show
1550  * revisions in which at least one of @a paths was changed (i.e., if
1551  * file, text or props changed; if dir, props changed or an entry
1552  * was added or deleted). Each path is an <tt>const char *</tt>, relative
1553  * to the repository root of @a session.
1554  *
1555  * If @a limit is greater than zero only invoke @a receiver on the first
1556  * @a limit logs.
1557  *
1558  * If @a discover_changed_paths, then each call to @a receiver passes a
1559  * <tt>const apr_hash_t *</tt> for the receiver's @a changed_paths argument;
1560  * the hash's keys are all the paths committed in that revision, the hash's
1561  * values are <tt>const svn_log_changed_path2_t *</tt> for each committed
1562  * path. Otherwise, each call to receiver passes NULL for @a changed_paths.
1563  *
1564  * If @a strict_node_history is set, copy history will not be traversed
1565  * (if any exists) when harvesting the revision logs for each path.
1566  *
1567  * If @a include_merged_revisions is set, log information for revisions
1568  * which have been merged to @a targets will also be returned.
1569  *
1570  * If @a revprops is NULL, retrieve all revision properties; else, retrieve
1571  * only the revision properties named by the (const char *) array elements
1572  * (i.e. retrieve none if the array is empty).
1573  *
1574  * If any invocation of @a receiver returns error, return that error
1575  * immediately and without wrapping it.
1576  *
1577  * If @a start or @a end is a non-existent revision, return the error
1578  * @c SVN_ERR_FS_NO_SUCH_REVISION, without ever invoking @a receiver.
1579  *
1580  * See also the documentation for @c svn_log_message_receiver_t.
1581  *
1582  * The caller may not invoke any RA operations using @a session from
1583  * within @a receiver.
1584  *
1585  * Use @a pool for memory allocation.
1586  *
1587  * @note If @a paths is NULL or empty, the result depends on the
1588  * server. Pre-1.5 servers will send nothing; 1.5 servers will
1589  * effectively perform the log operation on the root of the
1590  * repository. This behavior may be changed in the future to ensure
1591  * consistency across all pedigrees of server.
1592  *
1593  * @note Pre-1.5 servers do not support custom revprop retrieval; if @a
1594  * revprops is NULL or contains a revprop other than svn:author, svn:date,
1595  * or svn:log, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is returned.
1596  *
1597  * @since New in 1.5.
1598  */
1599 svn_error_t *
1601  const apr_array_header_t *paths,
1602  svn_revnum_t start,
1603  svn_revnum_t end,
1604  int limit,
1605  svn_boolean_t discover_changed_paths,
1606  svn_boolean_t strict_node_history,
1607  svn_boolean_t include_merged_revisions,
1608  const apr_array_header_t *revprops,
1609  svn_log_entry_receiver_t receiver,
1610  void *receiver_baton,
1611  apr_pool_t *pool);
1612 
1613 /**
1614  * Similar to svn_ra_get_log2(), but uses @c svn_log_message_receiver_t
1615  * instead of @c svn_log_entry_receiver_t. Also, @a
1616  * include_merged_revisions is set to @c FALSE and @a revprops is
1617  * svn:author, svn:date, and svn:log.
1618  *
1619  * @since New in 1.2.
1620  * @deprecated Provided for backward compatibility with the 1.4 API.
1621  */
1623 svn_error_t *
1625  const apr_array_header_t *paths,
1626  svn_revnum_t start,
1627  svn_revnum_t end,
1628  int limit,
1629  svn_boolean_t discover_changed_paths,
1630  svn_boolean_t strict_node_history,
1631  svn_log_message_receiver_t receiver,
1632  void *receiver_baton,
1633  apr_pool_t *pool);
1634 
1635 /**
1636  * Set @a *kind to the node kind associated with @a path at @a revision.
1637  * If @a path does not exist under @a revision, set @a *kind to
1638  * @c svn_node_none. @a path is relative to the @a session's parent URL.
1639  *
1640  * Use @a pool for memory allocation.
1641  *
1642  * @since New in 1.2.
1643  */
1644 svn_error_t *
1646  const char *path,
1647  svn_revnum_t revision,
1648  svn_node_kind_t *kind,
1649  apr_pool_t *pool);
1650 
1651 /**
1652  * Set @a *dirent to an @c svn_dirent_t associated with @a path at @a
1653  * revision. @a path is relative to the @a session's parent's URL.
1654  * If @a path does not exist in @a revision, set @a *dirent to NULL.
1655  *
1656  * Use @a pool for memory allocation.
1657  *
1658  * @since New in 1.2.
1659  */
1660 svn_error_t *
1661 svn_ra_stat(svn_ra_session_t *session,
1662  const char *path,
1663  svn_revnum_t revision,
1664  svn_dirent_t **dirent,
1665  apr_pool_t *pool);
1666 
1667 
1668 /**
1669  * Set @a *uuid to the repository's UUID, allocated in @a pool.
1670  *
1671  * @since New in 1.5.
1672  */
1673 svn_error_t *
1675  const char **uuid,
1676  apr_pool_t *pool);
1677 
1678 /**
1679  * Similar to svn_ra_get_uuid2(), but returns the value allocated in
1680  * @a session's pool.
1681  *
1682  * @deprecated Provided for backward compatibility with the 1.4 API.
1683  * @since New in 1.2.
1684  */
1686 svn_error_t *
1688  const char **uuid,
1689  apr_pool_t *pool);
1690 
1691 /**
1692  * Set @a *url to the repository's root URL, allocated in @a pool.
1693  * The value will not include a trailing '/'. The returned URL is
1694  * guaranteed to be a prefix of the @a session's URL.
1695  *
1696  * @since New in 1.5.
1697  */
1698 svn_error_t *
1700  const char **url,
1701  apr_pool_t *pool);
1702 
1703 
1704 /**
1705  * Similar to svn_ra_get_repos_root2(), but returns the value
1706  * allocated in @a session's pool.
1707  *
1708  * @deprecated Provided for backward compatibility with the 1.4 API.
1709  * @since New in 1.2.
1710  */
1712 svn_error_t *
1714  const char **url,
1715  apr_pool_t *pool);
1716 
1717 /**
1718  * Set @a *locations to the locations (at the repository revisions
1719  * @a location_revisions) of the file identified by @a path in
1720  * @a peg_revision (passing @c SVN_INVALID_REVNUM is an error).
1721  * @a path is relative to the URL to which @a session was opened.
1722  * @a location_revisions is an array of @c svn_revnum_t's.
1723  * @a *locations will be a mapping from the revisions to
1724  * their appropriate absolute paths. If the file doesn't exist in a
1725  * location_revision, that revision will be ignored.
1726  *
1727  * Use @a pool for all allocations.
1728  *
1729  * @since New in 1.2.
1730  */
1731 svn_error_t *
1733  apr_hash_t **locations,
1734  const char *path,
1735  svn_revnum_t peg_revision,
1736  const apr_array_header_t *location_revisions,
1737  apr_pool_t *pool);
1738 
1739 
1740 /**
1741  * Call @a receiver (with @a receiver_baton) for each segment in the
1742  * location history of @a path in @a peg_revision, working backwards in
1743  * time from @a start_rev to @a end_rev.
1744  *
1745  * @a end_rev may be @c SVN_INVALID_REVNUM to indicate that you want
1746  * to trace the history of the object to its origin.
1747  *
1748  * @a start_rev may be @c SVN_INVALID_REVNUM to indicate "the HEAD
1749  * revision". Otherwise, @a start_rev must be younger than @a end_rev
1750  * (unless @a end_rev is @c SVN_INVALID_REVNUM).
1751  *
1752  * @a peg_revision may be @c SVN_INVALID_REVNUM to indicate "the HEAD
1753  * revision", and must evaluate to be at least as young as @a start_rev.
1754  *
1755  * Use @a pool for all allocations.
1756  *
1757  * @since New in 1.5.
1758  */
1759 svn_error_t *
1761  const char *path,
1762  svn_revnum_t peg_revision,
1763  svn_revnum_t start_rev,
1764  svn_revnum_t end_rev,
1766  void *receiver_baton,
1767  apr_pool_t *pool);
1768 
1769 /**
1770  * Retrieve a subset of the interesting revisions of a file @a path
1771  * as seen in revision @a end (see svn_fs_history_prev() for a
1772  * definition of "interesting revisions"). Invoke @a handler with
1773  * @a handler_baton as its first argument for each such revision.
1774  * @a session is an open RA session. Use @a pool for all allocations.
1775  *
1776  * If there is an interesting revision of the file that is less than or
1777  * equal to @a start, the iteration will begin at that revision.
1778  * Else, the iteration will begin at the first revision of the file in
1779  * the repository, which has to be less than or equal to @a end. Note
1780  * that if the function succeeds, @a handler will have been called at
1781  * least once.
1782  *
1783  * In a series of calls to @a handler, the file contents for the first
1784  * interesting revision will be provided as a text delta against the
1785  * empty file. In the following calls, the delta will be against the
1786  * fulltext contents for the previous call.
1787  *
1788  * If @a include_merged_revisions is TRUE, revisions which are
1789  * included as a result of a merge between @a start and @a end will be
1790  * included.
1791  *
1792  * @note This functionality is not available in pre-1.1 servers. If the
1793  * server doesn't implement it, an alternative (but much slower)
1794  * implementation based on svn_ra_get_log2() is used.
1795  *
1796  * On subversion 1.8 and newer servers this function has been enabled
1797  * to support reversion of the revision range for @a include_merged_revision
1798  * @c FALSE reporting by switching @a end with @a start.
1799  *
1800  * @note Prior to Subversion 1.9, this function may request delta handlers
1801  * from @a handler even for empty text deltas. Starting with 1.9, the
1802  * delta handler / baton return arguments passed to @a handler will be
1803  * #NULL unless there is an actual difference in the file contents between
1804  * the current and the previous call.
1805  *
1806  * @since New in 1.5.
1807  */
1808 svn_error_t *
1810  const char *path,
1811  svn_revnum_t start,
1812  svn_revnum_t end,
1813  svn_boolean_t include_merged_revisions,
1814  svn_file_rev_handler_t handler,
1815  void *handler_baton,
1816  apr_pool_t *pool);
1817 
1818 /**
1819  * Similar to svn_ra_get_file_revs2(), but with @a include_merged_revisions
1820  * set to FALSE.
1821  *
1822  * @since New in 1.2.
1823  * @deprecated Provided for backward compatibility with the 1.4 API.
1824  */
1826 svn_error_t *
1828  const char *path,
1829  svn_revnum_t start,
1830  svn_revnum_t end,
1831  svn_ra_file_rev_handler_t handler,
1832  void *handler_baton,
1833  apr_pool_t *pool);
1834 
1835 /**
1836  * Lock each path in @a path_revs, which is a hash whose keys are the
1837  * paths to be locked, and whose values are the corresponding base
1838  * revisions for each path. The keys are (const char *) and the
1839  * revisions are (svn_revnum_t *).
1840  *
1841  * Note that locking is never anonymous, so any server implementing
1842  * this function will have to "pull" a username from the client, if
1843  * it hasn't done so already.
1844  *
1845  * @a comment is optional: it's either an xml-escapable string
1846  * which describes the lock, or it is NULL.
1847  *
1848  * If any path is already locked by a different user, then call @a
1849  * lock_func/@a lock_baton with an error. If @a steal_lock is TRUE,
1850  * then "steal" the existing lock(s) anyway, even if the RA username
1851  * does not match the current lock's owner. Delete any lock on the
1852  * path, and unconditionally create a new lock.
1853  *
1854  * For each path, if its base revision (in @a path_revs) is a valid
1855  * revnum, then do an out-of-dateness check. If the revnum is less
1856  * than the last-changed-revision of any path (or if a path doesn't
1857  * exist in HEAD), call @a lock_func/@a lock_baton with an
1858  * SVN_ERR_RA_OUT_OF_DATE error.
1859  *
1860  * After successfully locking a file, @a lock_func is called with the
1861  * @a lock_baton.
1862  *
1863  * Use @a pool for temporary allocations.
1864  *
1865  * @since New in 1.2.
1866  */
1867 svn_error_t *
1868 svn_ra_lock(svn_ra_session_t *session,
1869  apr_hash_t *path_revs,
1870  const char *comment,
1871  svn_boolean_t steal_lock,
1872  svn_ra_lock_callback_t lock_func,
1873  void *lock_baton,
1874  apr_pool_t *pool);
1875 
1876 /**
1877  * Remove the repository lock for each path in @a path_tokens.
1878  * @a path_tokens is a hash whose keys are the paths to be locked, and
1879  * whose values are the corresponding lock tokens for each path. If
1880  * the path has no corresponding lock token, or if @a break_lock is TRUE,
1881  * then the corresponding value shall be "".
1882  *
1883  * Note that unlocking is never anonymous, so any server
1884  * implementing this function will have to "pull" a username from
1885  * the client, if it hasn't done so already.
1886  *
1887  * If @a token points to a lock, but the RA username doesn't match the
1888  * lock's owner, call @a lock_func/@a lock_baton with an error. If @a
1889  * break_lock is TRUE, however, instead allow the lock to be "broken"
1890  * by the RA user.
1891  *
1892  * After successfully unlocking a path, @a lock_func is called with
1893  * the @a lock_baton.
1894  *
1895  * Use @a pool for temporary allocations.
1896  *
1897  * @since New in 1.2.
1898  */
1899 svn_error_t *
1901  apr_hash_t *path_tokens,
1902  svn_boolean_t break_lock,
1903  svn_ra_lock_callback_t lock_func,
1904  void *lock_baton,
1905  apr_pool_t *pool);
1906 
1907 /**
1908  * If @a path is locked, set @a *lock to an svn_lock_t which
1909  * represents the lock, allocated in @a pool.
1910  *
1911  * If @a path is not locked or does not exist in HEAD, set @a *lock to NULL.
1912  *
1913  * @note Before 1.9, this function could return SVN_ERR_FS_NOT_FOUND
1914  * when @a path didn't exist in HEAD on specific ra layers.
1915  *
1916  * @since New in 1.2.
1917  */
1918 svn_error_t *
1920  svn_lock_t **lock,
1921  const char *path,
1922  apr_pool_t *pool);
1923 
1924 /**
1925  * Set @a *locks to a hashtable which represents all locks on or
1926  * below @a path.
1927  *
1928  * @a depth limits the returned locks to those associated with paths
1929  * within the specified depth of @a path, and must be one of the
1930  * following values: #svn_depth_empty, #svn_depth_files,
1931  * #svn_depth_immediates, or #svn_depth_infinity.
1932  *
1933  * The hashtable maps (const char *) absolute fs paths to (const
1934  * svn_lock_t *) structures. The hashtable -- and all keys and
1935  * values -- are allocated in @a pool.
1936  *
1937  * @note It is not considered an error for @a path to not exist in HEAD.
1938  * Such a search will simply return no locks.
1939  *
1940  * @note This functionality is not available in pre-1.2 servers. If the
1941  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
1942  * returned.
1943  *
1944  * @since New in 1.7.
1945  */
1946 svn_error_t *
1948  apr_hash_t **locks,
1949  const char *path,
1950  svn_depth_t depth,
1951  apr_pool_t *pool);
1952 
1953 /**
1954  * Similar to svn_ra_get_locks2(), but with @a depth always passed as
1955  * #svn_depth_infinity.
1956  *
1957  * @since New in 1.2.
1958  * @deprecated Provided for backward compatibility with the 1.6 API.
1959  */
1961 svn_error_t *
1963  apr_hash_t **locks,
1964  const char *path,
1965  apr_pool_t *pool);
1966 
1967 
1968 /**
1969  * Replay the changes from a range of revisions between @a start_revision
1970  * and @a end_revision.
1971  *
1972  * When receiving information for one revision, a callback @a revstart_func is
1973  * called; this callback will provide an editor and baton through which the
1974  * revision will be replayed.
1975  * When replaying the revision is finished, callback @a revfinish_func will be
1976  * called so the editor can be closed.
1977  *
1978  * Changes will be limited to those that occur under @a session's URL, and
1979  * the server will assume that the client has no knowledge of revisions
1980  * prior to @a low_water_mark. These two limiting factors define the portion
1981  * of the tree that the server will assume the client already has knowledge of,
1982  * and thus any copies of data from outside that part of the tree will be
1983  * sent in their entirety, not as simple copies or deltas against a previous
1984  * version.
1985  *
1986  * If @a send_deltas is @c TRUE, the actual text and property changes in
1987  * the revision will be sent, otherwise dummy text deltas and NULL property
1988  * changes will be sent instead.
1989  *
1990  * @a pool is used for all allocation.
1991  *
1992  * @since New in 1.5.
1993  */
1994 svn_error_t *
1996  svn_revnum_t start_revision,
1997  svn_revnum_t end_revision,
1998  svn_revnum_t low_water_mark,
1999  svn_boolean_t send_deltas,
2000  svn_ra_replay_revstart_callback_t revstart_func,
2001  svn_ra_replay_revfinish_callback_t revfinish_func,
2002  void *replay_baton,
2003  apr_pool_t *pool);
2004 
2005 /**
2006  * Replay the changes from @a revision through @a editor and @a edit_baton.
2007  *
2008  * Changes will be limited to those that occur under @a session's URL, and
2009  * the server will assume that the client has no knowledge of revisions
2010  * prior to @a low_water_mark. These two limiting factors define the portion
2011  * of the tree that the server will assume the client already has knowledge of,
2012  * and thus any copies of data from outside that part of the tree will be
2013  * sent in their entirety, not as simple copies or deltas against a previous
2014  * version.
2015  *
2016  * If @a send_deltas is @c TRUE, the actual text and property changes in
2017  * the revision will be sent, otherwise dummy text deltas and null property
2018  * changes will be sent instead.
2019  *
2020  * @a pool is used for all allocation.
2021  *
2022  * @since New in 1.4.
2023  */
2024 svn_error_t *
2026  svn_revnum_t revision,
2027  svn_revnum_t low_water_mark,
2028  svn_boolean_t send_deltas,
2029  const svn_delta_editor_t *editor,
2030  void *edit_baton,
2031  apr_pool_t *pool);
2032 
2033 /**
2034  * Given @a path at revision @a peg_revision, set @a *revision_deleted to the
2035  * revision @a path was first deleted, within the inclusive revision range
2036  * defined by @a peg_revision and @a end_revision. @a path is relative
2037  * to the URL in @a session.
2038  *
2039  * If @a path does not exist at @a peg_revision or was not deleted within
2040  * the specified range, then set @a *revision_deleted to @c SVN_INVALID_REVNUM.
2041  * If @a peg_revision or @a end_revision are invalid or if @a peg_revision is
2042  * greater than @a end_revision, then return @c SVN_ERR_CLIENT_BAD_REVISION.
2043  *
2044  * Use @a pool for all allocations.
2045  *
2046  * @since New in 1.6.
2047  */
2048 svn_error_t *
2050  const char *path,
2051  svn_revnum_t peg_revision,
2052  svn_revnum_t end_revision,
2053  svn_revnum_t *revision_deleted,
2054  apr_pool_t *pool);
2055 
2056 /**
2057  * Set @a *inherited_props to a depth-first ordered array of
2058  * #svn_prop_inherited_item_t * structures representing the properties
2059  * inherited by @a path at @a revision (or the 'head' revision if
2060  * @a revision is @c SVN_INVALID_REVNUM). Interpret @a path relative to
2061  * the URL in @a session. Use @a pool for all allocations. If no
2062  * inheritable properties are found, then set @a *inherited_props to
2063  * an empty array.
2064  *
2065  * The #svn_prop_inherited_item_t->path_or_url members of the
2066  * #svn_prop_inherited_item_t * structures in @a *inherited_props are
2067  * paths relative to the repository root URL (of the repository which
2068  * @a ra_session is associated).
2069  *
2070  * Allocate @a *inherited_props in @a result_pool. Use @a scratch_pool
2071  * for temporary allocations.
2072  *
2073  * @since New in 1.8.
2074  */
2075 svn_error_t *
2077  apr_array_header_t **inherited_props,
2078  const char *path,
2079  svn_revnum_t revision,
2080  apr_pool_t *result_pool,
2081  apr_pool_t *scratch_pool);
2082 
2083 /**
2084  * @defgroup Capabilities Dynamically query the server's capabilities.
2085  *
2086  * @{
2087  */
2088 
2089 /**
2090  * Set @a *has to TRUE if the server represented by @a session has
2091  * @a capability (one of the capabilities beginning with
2092  * @c "SVN_RA_CAPABILITY_"), else set @a *has to FALSE.
2093  *
2094  * If @a capability isn't recognized, throw @c SVN_ERR_UNKNOWN_CAPABILITY,
2095  * with the effect on @a *has undefined.
2096  *
2097  * Use @a pool for all allocation.
2098  *
2099  * @since New in 1.5.
2100  */
2101 svn_error_t *
2103  svn_boolean_t *has,
2104  const char *capability,
2105  apr_pool_t *pool);
2106 
2107 /**
2108  * The capability of understanding @c svn_depth_t (e.g., the server
2109  * understands what the client means when the client describes the
2110  * depth of a working copy to the server.)
2111  *
2112  * @since New in 1.5.
2113  */
2114 #define SVN_RA_CAPABILITY_DEPTH "depth"
2115 
2116 /**
2117  * The capability of doing the right thing with merge-tracking
2118  * information. This capability should be reported bidirectionally,
2119  * because some repositories may want to reject clients that do not
2120  * self-report as knowing how to handle merge-tracking.
2121  *
2122  * @since New in 1.5.
2123  */
2124 #define SVN_RA_CAPABILITY_MERGEINFO "mergeinfo"
2125 
2126 /**
2127  * The capability of retrieving arbitrary revprops in svn_ra_get_log2.
2128  *
2129  * @since New in 1.5.
2130  */
2131 #define SVN_RA_CAPABILITY_LOG_REVPROPS "log-revprops"
2132 
2133 /**
2134  * The capability of replaying a directory in the repository (partial replay).
2135  *
2136  * @since New in 1.5.
2137  */
2138 #define SVN_RA_CAPABILITY_PARTIAL_REPLAY "partial-replay"
2139 
2140 /**
2141  * The capability of including revision properties in a commit.
2142  *
2143  * @since New in 1.5.
2144  */
2145 #define SVN_RA_CAPABILITY_COMMIT_REVPROPS "commit-revprops"
2146 
2147 /**
2148  * The capability of specifying (and atomically verifying) expected
2149  * preexisting values when modifying revprops.
2150  *
2151  * @since New in 1.7.
2152  */
2153 #define SVN_RA_CAPABILITY_ATOMIC_REVPROPS "atomic-revprops"
2154 
2155 /**
2156  * The capability to get inherited properties.
2157  *
2158  * @since New in 1.8.
2159  */
2160 #define SVN_RA_CAPABILITY_INHERITED_PROPS "inherited-props"
2161 
2162 /**
2163  * The capability of a server to automatically remove transaction
2164  * properties prefixed with SVN_PROP_EPHEMERAL_PREFIX.
2165  *
2166  * @since New in 1.8.
2167  */
2168 #define SVN_RA_CAPABILITY_EPHEMERAL_TXNPROPS "ephemeral-txnprops"
2169 
2170 /**
2171  * The capability of a server to walk revisions backwards in
2172  * svn_ra_get_file_revs2
2173  *
2174  * @since New in 1.8.
2175  */
2176 #define SVN_RA_CAPABILITY_GET_FILE_REVS_REVERSE "get-file-revs-reversed"
2177 
2178 
2179 /* *** PLEASE READ THIS IF YOU ADD A NEW CAPABILITY ***
2180  *
2181  * RA layers generally fetch all capabilities when asked about any
2182  * capability, to save future round trips. So if you add a new
2183  * capability here, make sure to update the RA layers to remember
2184  * it after any capabilities query.
2185  *
2186  * Also note that capability strings should not include colons,
2187  * because we pass a list of client capabilities to the start-commit
2188  * hook as a single, colon-separated string.
2189  */
2190 
2191 /** @} */
2192 
2193 
2194 /**
2195  * Append a textual list of all available RA modules to the stringbuf
2196  * @a output.
2197  *
2198  * @since New in 1.2.
2199  */
2200 svn_error_t *
2202  apr_pool_t *pool);
2203 
2204 
2205 /**
2206  * Similar to svn_ra_print_modules().
2207  * @a ra_baton is ignored.
2208  *
2209  * @deprecated Provided for backward compatibility with the 1.1 API.
2210  */
2212 svn_error_t *
2214  void *ra_baton,
2215  apr_pool_t *pool);
2216 
2217 
2218 
2219 /**
2220  * Using this callback struct is similar to calling the newer public
2221  * interface that is based on @c svn_ra_session_t.
2222  *
2223  * @deprecated Provided for backward compatibility with the 1.1 API.
2224  */
2225 typedef struct svn_ra_plugin_t
2226 {
2227  /** The proper name of the RA library, (like "ra_serf" or "ra_local") */
2228  const char *name;
2229 
2230  /** Short doc string printed out by `svn --version` */
2231  const char *description;
2232 
2233  /* The vtable hooks */
2234 
2235  /** Call svn_ra_open() and set @a session_baton to an object representing
2236  * the new session. All other arguments are passed to svn_ra_open().
2237  */
2238  svn_error_t *(*open)(void **session_baton,
2239  const char *repos_URL,
2240  const svn_ra_callbacks_t *callbacks,
2241  void *callback_baton,
2242  apr_hash_t *config,
2243  apr_pool_t *pool);
2244 
2245  /** Call svn_ra_get_latest_revnum() with the session associated with
2246  * @a session_baton and all other arguments.
2247  */
2248  svn_error_t *(*get_latest_revnum)(void *session_baton,
2249  svn_revnum_t *latest_revnum,
2250  apr_pool_t *pool);
2251 
2252  /** Call svn_ra_get_dated_revision() with the session associated with
2253  * @a session_baton and all other arguments.
2254  */
2255  svn_error_t *(*get_dated_revision)(void *session_baton,
2256  svn_revnum_t *revision,
2257  apr_time_t tm,
2258  apr_pool_t *pool);
2259 
2260  /** Call svn_ra_change_rev_prop() with the session associated with
2261  * @a session_baton and all other arguments.
2262  */
2263  svn_error_t *(*change_rev_prop)(void *session_baton,
2264  svn_revnum_t rev,
2265  const char *name,
2266  const svn_string_t *value,
2267  apr_pool_t *pool);
2268 
2269  /** Call svn_ra_rev_proplist() with the session associated with
2270  * @a session_baton and all other arguments.
2271  */
2272  svn_error_t *(*rev_proplist)(void *session_baton,
2273  svn_revnum_t rev,
2274  apr_hash_t **props,
2275  apr_pool_t *pool);
2276 
2277  /** Call svn_ra_rev_prop() with the session associated with
2278  * @a session_baton and all other arguments.
2279  */
2280  svn_error_t *(*rev_prop)(void *session_baton,
2281  svn_revnum_t rev,
2282  const char *name,
2283  svn_string_t **value,
2284  apr_pool_t *pool);
2285 
2286  /** Call svn_ra_get_commit_editor() with the session associated with
2287  * @a session_baton and all other arguments plus @a lock_tokens set to
2288  * @c NULL and @a keep_locks set to @c TRUE.
2289  */
2290  svn_error_t *(*get_commit_editor)(void *session_baton,
2291  const svn_delta_editor_t **editor,
2292  void **edit_baton,
2293  const char *log_msg,
2294  svn_commit_callback_t callback,
2295  void *callback_baton,
2296  apr_pool_t *pool);
2297 
2298  /** Call svn_ra_get_file() with the session associated with
2299  * @a session_baton and all other arguments.
2300  */
2301  svn_error_t *(*get_file)(void *session_baton,
2302  const char *path,
2303  svn_revnum_t revision,
2304  svn_stream_t *stream,
2305  svn_revnum_t *fetched_rev,
2306  apr_hash_t **props,
2307  apr_pool_t *pool);
2308 
2309  /** Call svn_ra_get_dir() with the session associated with
2310  * @a session_baton and all other arguments.
2311  */
2312  svn_error_t *(*get_dir)(void *session_baton,
2313  const char *path,
2314  svn_revnum_t revision,
2315  apr_hash_t **dirents,
2316  svn_revnum_t *fetched_rev,
2317  apr_hash_t **props,
2318  apr_pool_t *pool);
2319 
2320  /** Call svn_ra_do_update() with the session associated with
2321  * @a session_baton and all other arguments.
2322  */
2323  svn_error_t *(*do_update)(void *session_baton,
2324  const svn_ra_reporter_t **reporter,
2325  void **report_baton,
2326  svn_revnum_t revision_to_update_to,
2327  const char *update_target,
2328  svn_boolean_t recurse,
2329  const svn_delta_editor_t *update_editor,
2330  void *update_baton,
2331  apr_pool_t *pool);
2332 
2333  /** Call svn_ra_do_switch() with the session associated with
2334  * @a session_baton and all other arguments.
2335  */
2336  svn_error_t *(*do_switch)(void *session_baton,
2337  const svn_ra_reporter_t **reporter,
2338  void **report_baton,
2339  svn_revnum_t revision_to_switch_to,
2340  const char *switch_target,
2341  svn_boolean_t recurse,
2342  const char *switch_url,
2343  const svn_delta_editor_t *switch_editor,
2344  void *switch_baton,
2345  apr_pool_t *pool);
2346 
2347  /** Call svn_ra_do_status() with the session associated with
2348  * @a session_baton and all other arguments.
2349  */
2350  svn_error_t *(*do_status)(void *session_baton,
2351  const svn_ra_reporter_t **reporter,
2352  void **report_baton,
2353  const char *status_target,
2354  svn_revnum_t revision,
2355  svn_boolean_t recurse,
2356  const svn_delta_editor_t *status_editor,
2357  void *status_baton,
2358  apr_pool_t *pool);
2359 
2360  /** Call svn_ra_do_diff() with the session associated with
2361  * @a session_baton and all other arguments.
2362  */
2363  svn_error_t *(*do_diff)(void *session_baton,
2364  const svn_ra_reporter_t **reporter,
2365  void **report_baton,
2366  svn_revnum_t revision,
2367  const char *diff_target,
2368  svn_boolean_t recurse,
2369  svn_boolean_t ignore_ancestry,
2370  const char *versus_url,
2371  const svn_delta_editor_t *diff_editor,
2372  void *diff_baton,
2373  apr_pool_t *pool);
2374 
2375  /** Call svn_ra_get_log() with the session associated with
2376  * @a session_baton and all other arguments. @a limit is set to 0.
2377  */
2378  svn_error_t *(*get_log)(void *session_baton,
2379  const apr_array_header_t *paths,
2380  svn_revnum_t start,
2381  svn_revnum_t end,
2382  svn_boolean_t discover_changed_paths,
2383  svn_boolean_t strict_node_history,
2384  svn_log_message_receiver_t receiver,
2385  void *receiver_baton,
2386  apr_pool_t *pool);
2387 
2388  /** Call svn_ra_check_path() with the session associated with
2389  * @a session_baton and all other arguments.
2390  */
2391  svn_error_t *(*check_path)(void *session_baton,
2392  const char *path,
2393  svn_revnum_t revision,
2394  svn_node_kind_t *kind,
2395  apr_pool_t *pool);
2396 
2397  /** Call svn_ra_get_uuid() with the session associated with
2398  * @a session_baton and all other arguments.
2399  */
2400  svn_error_t *(*get_uuid)(void *session_baton,
2401  const char **uuid,
2402  apr_pool_t *pool);
2403 
2404  /** Call svn_ra_get_repos_root() with the session associated with
2405  * @a session_baton and all other arguments.
2406  */
2407  svn_error_t *(*get_repos_root)(void *session_baton,
2408  const char **url,
2409  apr_pool_t *pool);
2410 
2411  /**
2412  * Call svn_ra_get_locations() with the session associated with
2413  * @a session_baton and all other arguments.
2414  *
2415  * @since New in 1.1.
2416  */
2417  svn_error_t *(*get_locations)(void *session_baton,
2418  apr_hash_t **locations,
2419  const char *path,
2420  svn_revnum_t peg_revision,
2421  apr_array_header_t *location_revisions,
2422  apr_pool_t *pool);
2423 
2424  /**
2425  * Call svn_ra_get_file_revs() with the session associated with
2426  * @a session_baton and all other arguments.
2427  *
2428  * @since New in 1.1.
2429  */
2430  svn_error_t *(*get_file_revs)(void *session_baton,
2431  const char *path,
2432  svn_revnum_t start,
2433  svn_revnum_t end,
2434  svn_ra_file_rev_handler_t handler,
2435  void *handler_baton,
2436  apr_pool_t *pool);
2437 
2438  /**
2439  * Return the plugin's version information.
2440  *
2441  * @since New in 1.1.
2442  */
2443  const svn_version_t *(*get_version)(void);
2444 
2445 
2446 } svn_ra_plugin_t;
2447 
2448 /**
2449  * All "ra_FOO" implementations *must* export a function named
2450  * svn_ra_FOO_init() of type @c svn_ra_init_func_t.
2451  *
2452  * When called by libsvn_client, this routine adds an entry (or
2453  * entries) to the hash table for any URL schemes it handles. The hash
2454  * value must be of type (<tt>@c svn_ra_plugin_t *</tt>). @a pool is a
2455  * pool for allocating configuration / one-time data.
2456  *
2457  * This type is defined to use the "C Calling Conventions" to ensure that
2458  * abi_version is the first parameter. The RA plugin must check that value
2459  * before accessing the other parameters.
2460  *
2461  * ### need to force this to be __cdecl on Windows... how??
2462  *
2463  * @deprecated Provided for backward compatibility with the 1.1 API.
2464  */
2465 typedef svn_error_t *(*svn_ra_init_func_t)(int abi_version,
2466  apr_pool_t *pool,
2467  apr_hash_t *hash);
2468 
2469 /**
2470  * The current ABI (Application Binary Interface) version for the
2471  * RA plugin model. This version number will change when the ABI
2472  * between the SVN core (e.g. libsvn_client) and the RA plugin changes.
2473  *
2474  * An RA plugin should verify that the passed version number is acceptable
2475  * before accessing the rest of the parameters, and before returning any
2476  * information.
2477  *
2478  * It is entirely acceptable for an RA plugin to accept multiple ABI
2479  * versions. It can simply interpret the parameters based on the version,
2480  * and it can return different plugin structures.
2481  *
2482  *
2483  * <pre>
2484  * VSN DATE REASON FOR CHANGE
2485  * --- ---------- ------------------------------------------------
2486  * 1 2001-02-17 Initial revision.
2487  * 2 2004-06-29 Preparing for svn 1.1, which adds new RA vtable funcs.
2488  * 2005-01-19 Rework the plugin interface and don't provide the vtable
2489  * to the client. Separate ABI versions are no longer used.
2490  * </pre>
2491  *
2492  * @deprecated Provided for backward compatibility with the 1.0 API.
2493  */
2494 #define SVN_RA_ABI_VERSION 2
2495 
2496 /* Public RA implementations. */
2497 
2498 /** Initialize libsvn_ra_serf.
2499  *
2500  * @deprecated Provided for backward compatibility with the 1.1 API. */
2502 svn_error_t *
2503 svn_ra_dav_init(int abi_version,
2504  apr_pool_t *pool,
2505  apr_hash_t *hash);
2506 
2507 /** Initialize libsvn_ra_local.
2508  *
2509  * @deprecated Provided for backward compatibility with the 1.1 API. */
2511 svn_error_t *
2512 svn_ra_local_init(int abi_version,
2513  apr_pool_t *pool,
2514  apr_hash_t *hash);
2515 
2516 /** Initialize libsvn_ra_svn.
2517  *
2518  * @deprecated Provided for backward compatibility with the 1.1 API. */
2520 svn_error_t *
2521 svn_ra_svn_init(int abi_version,
2522  apr_pool_t *pool,
2523  apr_hash_t *hash);
2524 
2525 /** Initialize libsvn_ra_serf.
2526  *
2527  * @since New in 1.4.
2528  * @deprecated Provided for backward compatibility with the 1.1 API. */
2530 svn_error_t *
2531 svn_ra_serf_init(int abi_version,
2532  apr_pool_t *pool,
2533  apr_hash_t *hash);
2534 
2535 
2536 /**
2537  * Initialize the compatibility wrapper, using @a pool for any allocations.
2538  * The caller must hold on to @a ra_baton as long as the RA library is used.
2539  *
2540  * @deprecated Provided for backward compatibility with the 1.1 API.
2541  */
2543 svn_error_t *
2544 svn_ra_init_ra_libs(void **ra_baton,
2545  apr_pool_t *pool);
2546 
2547 /**
2548  * Return an RA vtable-@a library which can handle URL. A number of
2549  * svn_client_* routines will call this internally, but client apps might
2550  * use it too. $a ra_baton is a baton obtained by a call to
2551  * svn_ra_init_ra_libs().
2552  *
2553  * @deprecated Provided for backward compatibility with the 1.1 API.
2554  */
2556 svn_error_t *
2558  void *ra_baton,
2559  const char *url,
2560  apr_pool_t *pool);
2561 
2562 #ifdef __cplusplus
2563 }
2564 #endif /* __cplusplus */
2565 
2566 #endif /* SVN_RA_H */
2567