Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_repos.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_repos.h
24  * @brief Tools built on top of the filesystem.
25  */
26 
27 #ifndef SVN_REPOS_H
28 #define SVN_REPOS_H
29 
30 #include <apr_pools.h>
31 #include <apr_hash.h>
32 #include <apr_tables.h>
33 #include <apr_time.h>
34 
35 #include "svn_types.h"
36 #include "svn_string.h"
37 #include "svn_delta.h"
38 #include "svn_fs.h"
39 #include "svn_io.h"
40 #include "svn_mergeinfo.h"
41 
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif /* __cplusplus */
46 
47 /* ---------------------------------------------------------------*/
48 
49 /**
50  * Get libsvn_repos version information.
51  *
52  * @since New in 1.1.
53  */
54 const svn_version_t *
55 svn_repos_version(void);
56 
57 
58 /* Some useful enums. They need to be declared here for the notification
59  system to pick them up. */
60 /** The different "actions" attached to nodes in the dumpfile. */
62 {
63  svn_node_action_change,
64  svn_node_action_add,
65  svn_node_action_delete,
66  svn_node_action_replace
67 };
68 
69 
70 /** @defgroup svn_repos_authz_callbacks Repository authorization callbacks
71  * @{
72  */
73 
74 /** Callback type for checking authorization on a path.
75  *
76  * Set @a *allowed to TRUE to indicate that some operation is
77  * authorized for @a path in @a root, or set it to FALSE to indicate
78  * unauthorized (presumably according to state stored in @a baton).
79  *
80  * Do not assume @a pool has any lifetime beyond this call.
81  *
82  * The exact operation being authorized depends on the callback
83  * implementation. For read authorization, for example, the caller
84  * would implement an instance that does read checking, and pass it as
85  * a parameter named [perhaps] 'authz_read_func'. The receiver of
86  * that parameter might also take another parameter named
87  * 'authz_write_func', which although sharing this type, would be a
88  * different implementation.
89  *
90  * @note If someday we want more sophisticated authorization states
91  * than just yes/no, @a allowed can become an enum type.
92  */
93 typedef svn_error_t *(*svn_repos_authz_func_t)(svn_boolean_t *allowed,
94  svn_fs_root_t *root,
95  const char *path,
96  void *baton,
97  apr_pool_t *pool);
98 
99 
100 /** An enum defining the kinds of access authz looks up.
101  *
102  * @since New in 1.3.
103  */
105 {
106  /** No access. */
108 
109  /** Path can be read. */
111 
112  /** Path can be altered. */
114 
115  /** The other access credentials are recursive. */
118 
119 
120 /** Callback type for checking authorization on paths produced by
121  * the repository commit editor.
122  *
123  * Set @a *allowed to TRUE to indicate that the @a required access on
124  * @a path in @a root is authorized, or set it to FALSE to indicate
125  * unauthorized (presumable according to state stored in @a baton).
126  *
127  * If @a path is NULL, the callback should perform a global authz
128  * lookup for the @a required access. That is, the lookup should
129  * check if the @a required access is granted for at least one path of
130  * the repository, and set @a *allowed to TRUE if so. @a root may
131  * also be NULL if @a path is NULL.
132  *
133  * This callback is very similar to svn_repos_authz_func_t, with the
134  * exception of the addition of the @a required parameter.
135  * This is due to historical reasons: when authz was first implemented
136  * for svn_repos_dir_delta2(), it seemed there would need only checks
137  * for read and write operations, hence the svn_repos_authz_func_t
138  * callback prototype and usage scenario. But it was then realized
139  * that lookups due to copying needed to be recursive, and that
140  * brute-force recursive lookups didn't square with the O(1)
141  * performances a copy operation should have.
142  *
143  * So a special way to ask for a recursive lookup was introduced. The
144  * commit editor needs this capability to retain acceptable
145  * performance. Instead of revving the existing callback, causing
146  * unnecessary revving of functions that don't actually need the
147  * extended functionality, this second, more complete callback was
148  * introduced, for use by the commit editor.
149  *
150  * Some day, it would be nice to reunite these two callbacks and do
151  * the necessary revving anyway, but for the time being, this dual
152  * callback mechanism will do.
153  */
154 typedef svn_error_t *(*svn_repos_authz_callback_t)
156  svn_boolean_t *allowed,
157  svn_fs_root_t *root,
158  const char *path,
159  void *baton,
160  apr_pool_t *pool);
161 
162 /** @} */
163 
164 
165 /** @defgroup svn_repos_notifications Repository notifications
166  * @{
167  */
168 
169 /* Notification system. */
170 
171 /** The type of action occurring.
172  *
173  * @since New in 1.7.
174  */
176 {
177  /** A warning message is waiting. */
179 
180  /** A revision has finished being dumped. */
182 
183  /** A revision has finished being verified. */
185 
186  /** All revisions have finished being dumped. */
188 
189  /** All revisions have finished being verified. */
191 
192  /** packing of an FSFS shard has commenced */
194 
195  /** packing of an FSFS shard is completed */
197 
198  /** packing of the shard revprops has commenced */
200 
201  /** packing of the shard revprops has completed */
203 
204  /** A revision has begun loading */
206 
207  /** A revision has finished loading */
209 
210  /** A node has begun loading */
212 
213  /** A node has finished loading */
215 
216  /** A copied node has been encountered */
218 
219  /** Mergeinfo has been normalized */
221 
222  /** The operation has acquired a mutex for the repo. */
224 
225  /** Recover has started. */
227 
228  /** Upgrade has started. */
230 
231  /** A revision was skipped during loading. @since New in 1.8. */
233 
234  /** The structure of a revision is being verified. @since New in 1.8. */
236 
237  /** A revision is found with corruption/errors. @since New in 1.9. */
239 
240  /** A revprop shard got packed. @since New in 1.9. */
242 
243  /** A non-packed revprop shard got removed. @since New in 1.9. */
245 
246  /** The repository format got bumped. @since New in 1.9. */
248 
249  /** A revision range was copied. @since New in 1.9. */
252 
253 /** The type of warning occurring.
254  *
255  * @since New in 1.7.
256  */
258 {
259  /** Referencing copy source data from a revision earlier than the
260  * first revision dumped. */
262 
263  /** An #SVN_PROP_MERGEINFO property's encoded mergeinfo references a
264  * revision earlier than the first revision dumped. */
266 
267  /** Found an invalid path in the filesystem.
268  * @see svn_fs.h:"Directory entry names and directory paths" */
269  /* ### TODO(doxygen): make that a proper doxygen link */
270  /* See svn_fs__path_valid(). */
272 
273  /**
274  * Detected a name collision. Reported when the names of two or more
275  * entries in the same directory differ only in character
276  * representation (normalization), but are otherwise identical.
277  *
278  * @since New in 1.9.
279  */
281 
282  /**
283  * Detected a mergeinfo path collision. Reported when the paths in
284  * two or more entries in the same svn:mergeinfo property differ
285  * only in character representation (normalization), but are
286  * otherwise identical.
287  *
288  * @since New in 1.9.
289  */
291 
292  /**
293  * Detected invalid mergeinfo.
294  *
295  * @since New in 1.9.
296  */
299 
300 /**
301  * Structure used by #svn_repos_notify_func_t.
302  *
303  * The only field guaranteed to be populated is @c action. Other fields are
304  * dependent upon the @c action. (See individual fields for more information.)
305  *
306  * @note Callers of notification functions should use
307  * svn_repos_notify_create() to create structures of this type to allow for
308  * future extensibility.
309  *
310  * @since New in 1.7.
311  */
312 typedef struct svn_repos_notify_t
313 {
314  /** Action that describes what happened in the repository. */
316 
317  /** For #svn_repos_notify_dump_rev_end and #svn_repos_notify_verify_rev_end,
318  * the revision which just completed.
319  * For #svn_fs_upgrade_format_bumped, the new format version. */
321 
322  /** For #svn_repos_notify_warning, the warning message. */
323  const char *warning_str;
324  /** For #svn_repos_notify_warning, the warning type. */
326 
327  /** For #svn_repos_notify_pack_shard_start,
328  #svn_repos_notify_pack_shard_end,
329  #svn_repos_notify_pack_revprops,
330  #svn_repos_notify_cleanup_revprops
331  #svn_repos_notify_pack_shard_start_revprop, and
332  #svn_repos_notify_pack_shard_end_revprop, the shard processed. */
333  apr_int64_t shard;
334 
335  /** For #svn_repos_notify_load_txn_committed, the revision committed. */
337 
338  /** For #svn_repos_notify_load_txn_committed, the source revision, if
339  different from @a new_revision, otherwise #SVN_INVALID_REVNUM.
340  For #svn_repos_notify_load_txn_start and
341  #svn_repos_notify_load_skipped_rev, the source revision. */
343 
344  /** For #svn_repos_notify_load_node_start, the action being taken on the
345  node. */
347 
348  /** For #svn_repos_notify_load_node_start, the path of the node. */
349  const char *path;
350 
351  /** For #svn_repos_notify_failure, this error chain indicates what
352  went wrong during verification.
353  @since New in 1.9. */
355 
356  /** For #svn_repos_notify_hotcopy_rev_range, the start of the copied
357  revision range.
358  @since New in 1.9. */
360 
361  /** For #svn_repos_notify_hotcopy_rev_range, the end of the copied
362  revision range (might be the same as @a start_revision).
363  @since New in 1.9. */
365 
366  /* NOTE: Add new fields at the end to preserve binary compatibility.
367  Also, if you add fields here, you have to update
368  svn_repos_notify_create(). */
370 
371 /** Callback for providing notification from the repository.
372  * Returns @c void. Justification: success of an operation is not dependent
373  * upon successful notification of that operation.
374  *
375  * @since New in 1.7. */
376 typedef void (*svn_repos_notify_func_t)(void *baton,
377  const svn_repos_notify_t *notify,
378  apr_pool_t *scratch_pool);
379 
380 /**
381  * Allocate an #svn_repos_notify_t structure in @a result_pool, initialize
382  * and return it.
383  *
384  * @since New in 1.7.
385  */
388  apr_pool_t *result_pool);
389 
390  /** @} */
391 
392 
393 /** The repository object. */
394 typedef struct svn_repos_t svn_repos_t;
395 
396 /* Opening and creating repositories. */
397 
398 
399 /** Find the root path of the repository that contains @a path.
400  *
401  * If a repository was found, the path to the root of the repository
402  * is returned, else @c NULL. The pointer to the returned path may be
403  * equal to @a path.
404  */
405 const char *
406 svn_repos_find_root_path(const char *path,
407  apr_pool_t *pool);
408 
409 /** Set @a *repos_p to a repository object for the repository at @a path.
410  *
411  * Allocate @a *repos_p in @a result_pool.
412  *
413  * Acquires a shared lock on the repository, and attaches a cleanup
414  * function to @a result_pool to remove the lock. If no lock can be acquired,
415  * returns error, with undefined effect on @a *repos_p. If an exclusive
416  * lock is present, this blocks until it's gone. @a fs_config will be
417  * passed to the filesystem initialization function and may be @c NULL.
418  *
419  * Use @a scratch_pool for temporary allocations.
420  *
421  * @since New in 1.9.
422  */
423 svn_error_t *
424 svn_repos_open3(svn_repos_t **repos_p,
425  const char *path,
426  apr_hash_t *fs_config,
427  apr_pool_t *result_pool,
428  apr_pool_t *scratch_pool);
429 
430 /** Similar to svn_repos_open3() but without @a scratch_pool.
431  *
432  * @deprecated Provided for backward compatibility with 1.8 API.
433  * @since New in 1.7.
434  */
436 svn_error_t *
437 svn_repos_open2(svn_repos_t **repos_p,
438  const char *path,
439  apr_hash_t *fs_config,
440  apr_pool_t *pool);
441 
442 /** Similar to svn_repos_open2() with @a fs_config set to NULL.
443  *
444  * @deprecated Provided for backward compatibility with 1.6 API.
445  */
447 svn_error_t *
448 svn_repos_open(svn_repos_t **repos_p,
449  const char *path,
450  apr_pool_t *pool);
451 
452 /** Create a new Subversion repository at @a path, building the necessary
453  * directory structure, creating the filesystem, and so on.
454  * Return the repository object in @a *repos_p, allocated in @a pool.
455  *
456  * @a config is a client configuration hash of #svn_config_t * items
457  * keyed on config category names, and may be NULL.
458  *
459  * @a fs_config is passed to the filesystem, and may be NULL.
460  *
461  * @a unused_1 and @a unused_2 are not used and should be NULL.
462  */
463 svn_error_t *
464 svn_repos_create(svn_repos_t **repos_p,
465  const char *path,
466  const char *unused_1,
467  const char *unused_2,
468  apr_hash_t *config,
469  apr_hash_t *fs_config,
470  apr_pool_t *pool);
471 
472 /**
473  * Upgrade the Subversion repository (and its underlying versioned
474  * filesystem) located in the directory @a path to the latest version
475  * supported by this library. If the requested upgrade is not
476  * supported due to the current state of the repository or it
477  * underlying filesystem, return #SVN_ERR_REPOS_UNSUPPORTED_UPGRADE
478  * or #SVN_ERR_FS_UNSUPPORTED_UPGRADE (respectively) and make no
479  * changes to the repository or filesystem.
480  *
481  * Acquires an exclusive lock on the repository, upgrades the
482  * repository, and releases the lock. If an exclusive lock can't be
483  * acquired, returns error.
484  *
485  * If @a nonblocking is TRUE, an error of type EWOULDBLOCK is
486  * returned if the lock is not immediately available.
487  *
488  * If @a start_callback is not NULL, it will be called with @a
489  * start_callback_baton as argument before the upgrade starts, but
490  * after the exclusive lock has been acquired.
491  *
492  * Use @a pool for necessary allocations.
493  *
494  * @note This functionality is provided as a convenience for
495  * administrators wishing to make use of new Subversion functionality
496  * without a potentially costly full repository dump/load. As such,
497  * the operation performs only the minimum amount of work needed to
498  * accomplish this while maintaining the integrity of the repository.
499  * It does *not* guarantee the most optimized repository state as a
500  * dump and subsequent load would.
501  *
502  * @note On some platforms the exclusive lock does not exclude other
503  * threads in the same process so this function should only be called
504  * by a single threaded process, or by a multi-threaded process when
505  * no other threads are accessing the repository.
506  *
507  * @since New in 1.7.
508  */
509 svn_error_t *
510 svn_repos_upgrade2(const char *path,
511  svn_boolean_t nonblocking,
512  svn_repos_notify_func_t notify_func,
513  void *notify_baton,
514  apr_pool_t *pool);
515 
516 /**
517  * Similar to svn_repos_upgrade2(), but with @a start_callback and baton,
518  * rather than a notify_callback / baton
519  *
520  * @since New in 1.5.
521  * @deprecated Provided for backward compatibility with the 1.6 API.
522  */
524 svn_error_t *
525 svn_repos_upgrade(const char *path,
526  svn_boolean_t nonblocking,
527  svn_error_t *(*start_callback)(void *baton),
528  void *start_callback_baton,
529  apr_pool_t *pool);
530 
531 /** Destroy the Subversion repository found at @a path, using @a pool for any
532  * necessary allocations.
533  */
534 svn_error_t *
535 svn_repos_delete(const char *path,
536  apr_pool_t *pool);
537 
538 
539 /** @defgroup svn_repos_capabilities Repository capabilities
540  * @{
541  */
542 
543 /**
544  * Set @a *has to TRUE if @a repos has @a capability (one of the
545  * capabilities beginning with @c "SVN_REPOS_CAPABILITY_"), else set
546  * @a *has to FALSE.
547  *
548  * If @a capability isn't recognized, throw #SVN_ERR_UNKNOWN_CAPABILITY,
549  * with the effect on @a *has undefined.
550  *
551  * Use @a pool for all allocation.
552  *
553  * @since New in 1.5.
554  */
555 svn_error_t *
557  svn_boolean_t *has,
558  const char *capability,
559  apr_pool_t *pool);
560 
561 /**
562  * Return a set of @a capabilities supported by the running Subversion
563  * library and by @a repos. (Capabilities supported by this version of
564  * Subversion but not by @a repos are not listed. This may happen when
565  * svn_repos_upgrade2() has not been called after a software upgrade.)
566  *
567  * The set is represented as a hash whose const char * keys are the set
568  * members. The values are not defined.
569  *
570  * Allocate @a capabilities in @a result_pool and use @a scratch_pool for
571  * temporary allocations.
572  *
573  * @see svn_repos_info_format
574  *
575  * @since New in 1.9.
576  */
577 svn_error_t *
578 svn_repos_capabilities(apr_hash_t **capabilities,
579  svn_repos_t *repos,
580  apr_pool_t *result_pool,
581  apr_pool_t *scratch_pool);
582 
583 /**
584  * The capability of doing the right thing with merge-tracking
585  * information, both storing it and responding to queries about it.
586  *
587  * @since New in 1.5.
588  */
589 #define SVN_REPOS_CAPABILITY_MERGEINFO "mergeinfo"
590 /* *** PLEASE READ THIS IF YOU ADD A NEW CAPABILITY ***
591  *
592  * @c SVN_REPOS_CAPABILITY_foo strings should not include colons, to
593  * be consistent with @c SVN_RA_CAPABILITY_foo strings, which forbid
594  * colons for their own reasons. While this RA limitation has no
595  * direct impact on repository capabilities, there's no reason to be
596  * gratuitously different either.
597  *
598  * If you add a capability, update svn_repos_capabilities().
599  */
600 
601 /** @} */
602 
603 
604 /**
605  * Store in @a repos the client-reported capabilities @a capabilities,
606  * which must be allocated in memory at least as long-lived as @a repos.
607  *
608  * The elements of @a capabilities are 'const char *', a subset of
609  * the constants beginning with @c SVN_RA_CAPABILITY_.
610  * @a capabilities is not copied, so changing it later will affect
611  * what is remembered by @a repos.
612  *
613  * @note The capabilities are passed along to the start-commit hook;
614  * see that hook's template for details.
615  *
616  * @note As of Subversion 1.5, there are no error conditions defined,
617  * so this always returns SVN_NO_ERROR. In future releases it may
618  * return error, however, so callers should check.
619  *
620  * @since New in 1.5.
621  */
622 svn_error_t *
624  const apr_array_header_t *capabilities);
625 
626 
627 /** Return the filesystem associated with repository object @a repos. */
628 svn_fs_t *
629 svn_repos_fs(svn_repos_t *repos);
630 
631 /** Return the type of filesystem associated with repository object
632  * @a repos allocated in @a result_pool.
633  *
634  * @see #svn_fs_backend_names
635  *
636  * @since New in 1.9.
637  */
638 const char *
640  apr_pool_t *result_pool);
641 
642 /** Make a hot copy of the Subversion repository found at @a src_path
643  * to @a dst_path.
644  *
645  * Copy a possibly live Subversion repository from @a src_path to
646  * @a dst_path. If @a clean_logs is @c TRUE, perform cleanup on the
647  * source filesystem as part of the copy operation; currently, this
648  * means deleting copied, unused logfiles for a Berkeley DB source
649  * repository.
650  *
651  * If @a incremental is TRUE, make an effort to not re-copy information
652  * already present in the destination. If incremental hotcopy is not
653  * implemented by the filesystem backend, raise SVN_ERR_UNSUPPORTED_FEATURE.
654  *
655  * For each revision range copied, the @a notify_func function will be
656  * called with the @a notify_baton and a notification structure containing
657  * appropriate values in @c start_revision and @c end_revision (both
658  * inclusive). @c start_revision might be equal to @c end_revision in
659  * case the copied range consists of a single revision. Currently, this
660  * notification is not triggered by the BDB backend. @a notify_func
661  * may be @c NULL if this notification is not required.
662  *
663  * The optional @a cancel_func callback will be invoked with
664  * @a cancel_baton as usual to allow the user to preempt this potentially
665  * lengthy operation.
666  *
667  * Use @a scratch_pool for temporary allocations.
668  *
669  * @since New in 1.9.
670  */
671 svn_error_t *
672 svn_repos_hotcopy3(const char *src_path,
673  const char *dst_path,
674  svn_boolean_t clean_logs,
675  svn_boolean_t incremental,
676  svn_repos_notify_func_t notify_func,
677  void *notify_baton,
678  svn_cancel_func_t cancel_func,
679  void *cancel_baton,
680  apr_pool_t *scratch_pool);
681 
682 /**
683  * Like svn_repos_hotcopy3(), but with @a notify_func and @a notify_baton
684  * always passed as @c NULL.
685  *
686  * @since New in 1.8.
687  * @deprecated Provided for backward compatibility with the 1.8 API.
688  */
690 svn_error_t *
691 svn_repos_hotcopy2(const char *src_path,
692  const char *dst_path,
693  svn_boolean_t clean_logs,
694  svn_boolean_t incremental,
695  svn_cancel_func_t cancel_func,
696  void *cancel_baton,
697  apr_pool_t *pool);
698 
699 /**
700  * Like svn_repos_hotcopy2(), but with @a incremental always passed as
701  * @c FALSE and without cancellation support.
702  *
703  * @deprecated Provided for backward compatibility with the 1.6 API.
704  */
706 svn_error_t *
707 svn_repos_hotcopy(const char *src_path,
708  const char *dst_path,
709  svn_boolean_t clean_logs,
710  apr_pool_t *pool);
711 
712 
713 /**
714  * Possibly update the repository, @a repos, to use a more efficient
715  * filesystem representation. Use @a pool for allocations.
716  *
717  * @since New in 1.7.
718  */
719 svn_error_t *
721  svn_repos_notify_func_t notify_func,
722  void *notify_baton,
723  svn_cancel_func_t cancel_func,
724  void *cancel_baton,
725  apr_pool_t *pool);
726 
727 /**
728  * Similar to svn_repos_fs_pack2(), but with a #svn_fs_pack_notify_t instead
729  * of a #svn_repos_notify_t.
730  *
731  * @since New in 1.6.
732  * @deprecated Provided for backward compatibility with the 1.6 API.
733  */
735 svn_error_t *
737  svn_fs_pack_notify_t notify_func,
738  void *notify_baton,
739  svn_cancel_func_t cancel_func,
740  void *cancel_baton,
741  apr_pool_t *pool);
742 
743 /**
744  * Run database recovery procedures on the repository at @a path,
745  * returning the database to a consistent state. Use @a pool for all
746  * allocation.
747  *
748  * Acquires an exclusive lock on the repository, recovers the
749  * database, and releases the lock. If an exclusive lock can't be
750  * acquired, returns error.
751  *
752  * If @a nonblocking is TRUE, an error of type EWOULDBLOCK is
753  * returned if the lock is not immediately available.
754  *
755  * If @a notify_func is not NULL, it will be called with @a
756  * notify_baton as argument before the recovery starts, but
757  * after the exclusive lock has been acquired.
758  *
759  * If @a cancel_func is not @c NULL, it is called periodically with
760  * @a cancel_baton as argument to see if the client wishes to cancel
761  * the recovery.
762  *
763  * @note On some platforms the exclusive lock does not exclude other
764  * threads in the same process so this function should only be called
765  * by a single threaded process, or by a multi-threaded process when
766  * no other threads are accessing the repository.
767  *
768  * @since New in 1.7.
769  */
770 svn_error_t *
771 svn_repos_recover4(const char *path,
772  svn_boolean_t nonblocking,
773  svn_repos_notify_func_t notify_func,
774  void *notify_baton,
775  svn_cancel_func_t cancel_func,
776  void * cancel_baton,
777  apr_pool_t *pool);
778 
779 /**
780  * Similar to svn_repos_recover4(), but with @a start callback in place of
781  * the notify_func / baton.
782  *
783  * @since New in 1.5.
784  * @deprecated Provided for backward compatibility with the 1.6 API.
785  */
787 svn_error_t *
788 svn_repos_recover3(const char *path,
789  svn_boolean_t nonblocking,
790  svn_error_t *(*start_callback)(void *baton),
791  void *start_callback_baton,
792  svn_cancel_func_t cancel_func,
793  void * cancel_baton,
794  apr_pool_t *pool);
795 
796 /**
797  * Similar to svn_repos_recover3(), but without cancellation support.
798  *
799  * @deprecated Provided for backward compatibility with the 1.4 API.
800  */
802 svn_error_t *
803 svn_repos_recover2(const char *path,
804  svn_boolean_t nonblocking,
805  svn_error_t *(*start_callback)(void *baton),
806  void *start_callback_baton,
807  apr_pool_t *pool);
808 
809 /**
810  * Similar to svn_repos_recover2(), but with nonblocking set to FALSE, and
811  * with no callbacks provided.
812  *
813  * @deprecated Provided for backward compatibility with the 1.0 API.
814  */
816 svn_error_t *
817 svn_repos_recover(const char *path,
818  apr_pool_t *pool);
819 
820 /**
821  * Callback for svn_repos_freeze.
822  *
823  * @since New in 1.8.
824  */
825 typedef svn_error_t *(*svn_repos_freeze_func_t)(void *baton, apr_pool_t *pool);
826 
827 /**
828  * Take an exclusive lock on each of the repositories in @a paths to
829  * prevent commits and then while holding all the locks invoke @a
830  * freeze_func passing @a freeze_baton. Each repository may be readable by
831  * Subversion while frozen, or may be unreadable, depending on which
832  * FS backend the repository uses. Repositories are locked in the
833  * order in which they are specified in the array.
834  *
835  * @note @a freeze_func must not, directly or indirectly, call any function
836  * that attempts to take out a lock on the underlying repository. These
837  * include functions for packing, hotcopying, setting revprops and commits.
838  * Attempts to do so may result in a deadlock.
839  *
840  * @note On some platforms the exclusive lock does not exclude other
841  * threads in the same process so this function should only be called
842  * by a single threaded process, or by a multi-threaded process when
843  * no other threads are accessing the repositories.
844  *
845  * @since New in 1.8.
846  */
847 svn_error_t *
848 svn_repos_freeze(apr_array_header_t *paths,
849  svn_repos_freeze_func_t freeze_func,
850  void *freeze_baton,
851  apr_pool_t *pool);
852 
853 /** This function is a wrapper around svn_fs_berkeley_logfiles(),
854  * returning log file paths relative to the root of the repository.
855  *
856  * @copydoc svn_fs_berkeley_logfiles()
857  */
858 svn_error_t *
859 svn_repos_db_logfiles(apr_array_header_t **logfiles,
860  const char *path,
861  svn_boolean_t only_unused,
862  apr_pool_t *pool);
863 
864 
865 
866 /* Repository Paths */
867 
868 /** Return the top-level repository path allocated in @a pool. */
869 const char *
871  apr_pool_t *pool);
872 
873 /** Return the path to @a repos's filesystem directory, allocated in
874  * @a pool.
875  */
876 const char *
878  apr_pool_t *pool);
879 
880 /** Return path to @a repos's config directory, allocated in @a pool. */
881 const char *
883  apr_pool_t *pool);
884 
885 /** Return path to @a repos's svnserve.conf, allocated in @a pool. */
886 const char *
888  apr_pool_t *pool);
889 
890 /** Return path to @a repos's lock directory, allocated in @a pool. */
891 const char *
893  apr_pool_t *pool);
894 
895 /** Return path to @a repos's db lockfile, allocated in @a pool. */
896 const char *
898  apr_pool_t *pool);
899 
900 /** Return path to @a repos's db logs lockfile, allocated in @a pool. */
901 const char *
903  apr_pool_t *pool);
904 
905 /** Return the path to @a repos's hook directory, allocated in @a pool. */
906 const char *
908  apr_pool_t *pool);
909 
910 /** Return the path to @a repos's start-commit hook, allocated in @a pool. */
911 const char *
913  apr_pool_t *pool);
914 
915 /** Return the path to @a repos's pre-commit hook, allocated in @a pool. */
916 const char *
918  apr_pool_t *pool);
919 
920 /** Return the path to @a repos's post-commit hook, allocated in @a pool. */
921 const char *
923  apr_pool_t *pool);
924 
925 /** Return the path to @a repos's pre-revprop-change hook, allocated in
926  * @a pool.
927  */
928 const char *
930  apr_pool_t *pool);
931 
932 /** Return the path to @a repos's post-revprop-change hook, allocated in
933  * @a pool.
934  */
935 const char *
937  apr_pool_t *pool);
938 
939 
940 /** @defgroup svn_repos_lock_hooks Paths to lock hooks
941  * @{
942  * @since New in 1.2. */
943 
944 /** Return the path to @a repos's pre-lock hook, allocated in @a pool. */
945 const char *
947  apr_pool_t *pool);
948 
949 /** Return the path to @a repos's post-lock hook, allocated in @a pool. */
950 const char *
952  apr_pool_t *pool);
953 
954 /** Return the path to @a repos's pre-unlock hook, allocated in @a pool. */
955 const char *
957  apr_pool_t *pool);
958 
959 /** Return the path to @a repos's post-unlock hook, allocated in @a pool. */
960 const char *
962  apr_pool_t *pool);
963 
964 /** Specify that Subversion should consult the configuration file
965  * located at @a hooks_env_path to determine how to setup the
966  * environment for hook scripts invoked for the repository @a repos.
967  * As a special case, if @a hooks_env_path is @c NULL, look for the
968  * file in its default location within the repository disk structure.
969  * If @a hooks_env_path is not absolute, it specifies a path relative
970  * to the parent of the file's default location.
971  *
972  * Use @a scratch_pool for temporary allocations.
973  *
974  * If this function is not called, or if the specified configuration
975  * file does not define any environment variables, hooks will run in
976  * an empty environment.
977  *
978  * @since New in 1.8.
979  */
980 svn_error_t *
982  const char *hooks_env_path,
983  apr_pool_t *scratch_pool);
984 
985 /** @} */
986 
987 /* ---------------------------------------------------------------*/
988 
989 /* Reporting the state of a working copy, for updates. */
990 
991 
992 /**
993  * Construct and return a @a report_baton that will be passed to the
994  * other functions in this section to describe the state of a pre-existing
995  * tree (typically, a working copy). When the report is finished,
996  * @a editor/@a edit_baton will be driven in such a way as to transform the
997  * existing tree to @a revnum and, if @a tgt_path is non-NULL, switch the
998  * reported hierarchy to @a tgt_path.
999  *
1000  * @a fs_base is the absolute path of the node in the filesystem at which
1001  * the comparison should be rooted. @a target is a single path component,
1002  * used to limit the scope of the report to a single entry of @a fs_base,
1003  * or "" if all of @a fs_base itself is the main subject of the report.
1004  *
1005  * @a tgt_path and @a revnum is the fs path/revision pair that is the
1006  * "target" of the delta. @a tgt_path should be provided only when
1007  * the source and target paths of the report differ. That is, @a tgt_path
1008  * should *only* be specified when specifying that the resultant editor
1009  * drive be one that transforms the reported hierarchy into a pristine tree
1010  * of @a tgt_path at revision @a revnum. A @c NULL value for @a tgt_path
1011  * will indicate that the editor should be driven in such a way as to
1012  * transform the reported hierarchy to revision @a revnum, preserving the
1013  * reported hierarchy.
1014  *
1015  * @a text_deltas instructs the driver of the @a editor to enable
1016  * the generation of text deltas.
1017  *
1018  * @a ignore_ancestry instructs the driver to ignore node ancestry
1019  * when determining how to transmit differences.
1020  *
1021  * @a send_copyfrom_args instructs the driver to send 'copyfrom'
1022  * arguments to the editor's add_file() and add_directory() methods,
1023  * whenever it deems feasible.
1024  *
1025  * Use @a authz_read_func and @a authz_read_baton (if not @c NULL) to
1026  * avoid sending data through @a editor/@a edit_baton which is not
1027  * authorized for transmission.
1028  *
1029  * @a zero_copy_limit controls the maximum size (in bytes) at which
1030  * data blocks may be sent using the zero-copy code path. On that
1031  * path, a number of in-memory copy operations have been eliminated to
1032  * maximize throughput. However, until the whole block has been
1033  * pushed to the network stack, other clients block, so be careful
1034  * when using larger values here. Pass 0 for @a zero_copy_limit to
1035  * disable this optimization altogether.
1036  *
1037  * @note Never activate this optimization if @a editor might access
1038  * any FSFS data structures (and, hence, caches). So, it is basically
1039  * safe for networked editors only.
1040  *
1041  * All allocation for the context and collected state will occur in
1042  * @a pool.
1043  *
1044  * @a depth is the requested depth of the editor drive.
1045  *
1046  * If @a depth is #svn_depth_unknown, the editor will affect only the
1047  * paths reported by the individual calls to svn_repos_set_path3() and
1048  * svn_repos_link_path3().
1049  *
1050  * For example, if the reported tree is the @c A subdir of the Greek Tree
1051  * (see Subversion's test suite), at depth #svn_depth_empty, but the
1052  * @c A/B subdir is reported at depth #svn_depth_infinity, then
1053  * repository-side changes to @c A/mu, or underneath @c A/C and @c
1054  * A/D, would not be reflected in the editor drive, but changes
1055  * underneath @c A/B would be.
1056  *
1057  * Additionally, the editor driver will call @c add_directory and
1058  * and @c add_file for directories with an appropriate depth. For
1059  * example, a directory reported at #svn_depth_files will receive
1060  * file (but not directory) additions. A directory at #svn_depth_empty
1061  * will receive neither.
1062  *
1063  * If @a depth is #svn_depth_files, #svn_depth_immediates or
1064  * #svn_depth_infinity and @a depth is greater than the reported depth
1065  * of the working copy, then the editor driver will emit editor
1066  * operations so as to upgrade the working copy to this depth.
1067  *
1068  * If @a depth is #svn_depth_empty, #svn_depth_files,
1069  * #svn_depth_immediates and @a depth is lower
1070  * than or equal to the depth of the working copy, then the editor
1071  * operations will affect only paths at or above @a depth.
1072  *
1073  * @since New in 1.8.
1074  */
1075 svn_error_t *
1076 svn_repos_begin_report3(void **report_baton,
1077  svn_revnum_t revnum,
1078  svn_repos_t *repos,
1079  const char *fs_base,
1080  const char *target,
1081  const char *tgt_path,
1082  svn_boolean_t text_deltas,
1083  svn_depth_t depth,
1084  svn_boolean_t ignore_ancestry,
1085  svn_boolean_t send_copyfrom_args,
1086  const svn_delta_editor_t *editor,
1087  void *edit_baton,
1088  svn_repos_authz_func_t authz_read_func,
1089  void *authz_read_baton,
1090  apr_size_t zero_copy_limit,
1091  apr_pool_t *pool);
1092 
1093 /**
1094  * The same as svn_repos_begin_report3(), but with @a zero_copy_limit
1095  * always passed as 0.
1096  *
1097  * @since New in 1.5.
1098  * @deprecated Provided for backward compatibility with the 1.7 API.
1099  */
1101 svn_error_t *
1102 svn_repos_begin_report2(void **report_baton,
1103  svn_revnum_t revnum,
1104  svn_repos_t *repos,
1105  const char *fs_base,
1106  const char *target,
1107  const char *tgt_path,
1108  svn_boolean_t text_deltas,
1109  svn_depth_t depth,
1110  svn_boolean_t ignore_ancestry,
1111  svn_boolean_t send_copyfrom_args,
1112  const svn_delta_editor_t *editor,
1113  void *edit_baton,
1114  svn_repos_authz_func_t authz_read_func,
1115  void *authz_read_baton,
1116  apr_pool_t *pool);
1117 
1118 /**
1119  * The same as svn_repos_begin_report2(), but taking a boolean
1120  * @a recurse flag, and sending FALSE for @a send_copyfrom_args.
1121  *
1122  * If @a recurse is TRUE, the editor driver will drive the editor with
1123  * a depth of #svn_depth_infinity; if FALSE, then with a depth of
1124  * #svn_depth_files.
1125  *
1126  * @note @a username is ignored, and has been removed in a revised
1127  * version of this API.
1128  *
1129  * @deprecated Provided for backward compatibility with the 1.4 API.
1130  */
1132 svn_error_t *
1133 svn_repos_begin_report(void **report_baton,
1134  svn_revnum_t revnum,
1135  const char *username,
1136  svn_repos_t *repos,
1137  const char *fs_base,
1138  const char *target,
1139  const char *tgt_path,
1140  svn_boolean_t text_deltas,
1141  svn_boolean_t recurse,
1142  svn_boolean_t ignore_ancestry,
1143  const svn_delta_editor_t *editor,
1144  void *edit_baton,
1145  svn_repos_authz_func_t authz_read_func,
1146  void *authz_read_baton,
1147  apr_pool_t *pool);
1148 
1149 
1150 /**
1151  * Given a @a report_baton constructed by svn_repos_begin_report3(),
1152  * record the presence of @a path, at @a revision with depth @a depth,
1153  * in the current tree.
1154  *
1155  * @a path is relative to the anchor/target used in the creation of the
1156  * @a report_baton.
1157  *
1158  * @a revision may be SVN_INVALID_REVNUM if (for example) @a path
1159  * represents a locally-added path with no revision number, or @a
1160  * depth is #svn_depth_exclude.
1161  *
1162  * @a path may not be underneath a path on which svn_repos_set_path3()
1163  * was previously called with #svn_depth_exclude in this report.
1164  *
1165  * The first call of this in a given report usually passes an empty
1166  * @a path; this is used to set up the correct root revision for the editor
1167  * drive.
1168  *
1169  * A depth of #svn_depth_unknown is not allowed, and results in an
1170  * error.
1171  *
1172  * If @a start_empty is TRUE and @a path is a directory, then require the
1173  * caller to explicitly provide all the children of @a path - do not assume
1174  * that the tree also contains all the children of @a path at @a revision.
1175  * This is for 'low confidence' client reporting.
1176  *
1177  * If the caller has a lock token for @a path, then @a lock_token should
1178  * be set to that token. Else, @a lock_token should be NULL.
1179  *
1180  * All temporary allocations are done in @a pool.
1181  *
1182  * @since New in 1.5.
1183  */
1184 svn_error_t *
1185 svn_repos_set_path3(void *report_baton,
1186  const char *path,
1187  svn_revnum_t revision,
1188  svn_depth_t depth,
1189  svn_boolean_t start_empty,
1190  const char *lock_token,
1191  apr_pool_t *pool);
1192 
1193 /**
1194  * Similar to svn_repos_set_path3(), but with @a depth set to
1195  * #svn_depth_infinity.
1196  *
1197  * @deprecated Provided for backward compatibility with the 1.4 API.
1198  */
1200 svn_error_t *
1201 svn_repos_set_path2(void *report_baton,
1202  const char *path,
1203  svn_revnum_t revision,
1204  svn_boolean_t start_empty,
1205  const char *lock_token,
1206  apr_pool_t *pool);
1207 
1208 /**
1209  * Similar to svn_repos_set_path2(), but with @a lock_token set to @c NULL.
1210  *
1211  * @deprecated Provided for backward compatibility with the 1.1 API.
1212  */
1214 svn_error_t *
1215 svn_repos_set_path(void *report_baton,
1216  const char *path,
1217  svn_revnum_t revision,
1218  svn_boolean_t start_empty,
1219  apr_pool_t *pool);
1220 
1221 /**
1222  * Given a @a report_baton constructed by svn_repos_begin_report3(),
1223  * record the presence of @a path in the current tree, containing the contents
1224  * of @a link_path at @a revision with depth @a depth.
1225  *
1226  * A depth of #svn_depth_unknown is not allowed, and results in an
1227  * error.
1228  *
1229  * @a path may not be underneath a path on which svn_repos_set_path3()
1230  * was previously called with #svn_depth_exclude in this report.
1231  *
1232  * Note that while @a path is relative to the anchor/target used in the
1233  * creation of the @a report_baton, @a link_path is an absolute filesystem
1234  * path!
1235  *
1236  * If @a start_empty is TRUE and @a path is a directory, then require the
1237  * caller to explicitly provide all the children of @a path - do not assume
1238  * that the tree also contains all the children of @a link_path at
1239  * @a revision. This is for 'low confidence' client reporting.
1240  *
1241  * If the caller has a lock token for @a link_path, then @a lock_token
1242  * should be set to that token. Else, @a lock_token should be NULL.
1243  *
1244  * All temporary allocations are done in @a pool.
1245  *
1246  * @since New in 1.5.
1247  */
1248 svn_error_t *
1249 svn_repos_link_path3(void *report_baton,
1250  const char *path,
1251  const char *link_path,
1252  svn_revnum_t revision,
1253  svn_depth_t depth,
1254  svn_boolean_t start_empty,
1255  const char *lock_token,
1256  apr_pool_t *pool);
1257 
1258 /**
1259  * Similar to svn_repos_link_path3(), but with @a depth set to
1260  * #svn_depth_infinity.
1261  *
1262  * @deprecated Provided for backward compatibility with the 1.4 API.
1263  */
1265 svn_error_t *
1266 svn_repos_link_path2(void *report_baton,
1267  const char *path,
1268  const char *link_path,
1269  svn_revnum_t revision,
1270  svn_boolean_t start_empty,
1271  const char *lock_token,
1272  apr_pool_t *pool);
1273 
1274 /**
1275  * Similar to svn_repos_link_path2(), but with @a lock_token set to @c NULL.
1276  *
1277  * @deprecated Provided for backward compatibility with the 1.1 API.
1278  */
1280 svn_error_t *
1281 svn_repos_link_path(void *report_baton,
1282  const char *path,
1283  const char *link_path,
1284  svn_revnum_t revision,
1285  svn_boolean_t start_empty,
1286  apr_pool_t *pool);
1287 
1288 /** Given a @a report_baton constructed by svn_repos_begin_report3(),
1289  * record the non-existence of @a path in the current tree.
1290  *
1291  * @a path may not be underneath a path on which svn_repos_set_path3()
1292  * was previously called with #svn_depth_exclude in this report.
1293  *
1294  * (This allows the reporter's driver to describe missing pieces of a
1295  * working copy, so that 'svn up' can recreate them.)
1296  *
1297  * All temporary allocations are done in @a pool.
1298  */
1299 svn_error_t *
1300 svn_repos_delete_path(void *report_baton,
1301  const char *path,
1302  apr_pool_t *pool);
1303 
1304 /** Given a @a report_baton constructed by svn_repos_begin_report3(),
1305  * finish the report and drive the editor as specified when the report
1306  * baton was constructed.
1307  *
1308  * If an error occurs during the driving of the editor, do NOT abort the
1309  * edit; that responsibility belongs to the caller of this function, if
1310  * it happens at all.
1311  *
1312  * After the call to this function, @a report_baton is no longer valid;
1313  * it should not be passed to any other reporting functions, including
1314  * svn_repos_abort_report(), even if this function returns an error.
1315  */
1316 svn_error_t *
1317 svn_repos_finish_report(void *report_baton,
1318  apr_pool_t *pool);
1319 
1320 
1321 /** Given a @a report_baton constructed by svn_repos_begin_report3(),
1322  * abort the report. This function can be called anytime before
1323  * svn_repos_finish_report() is called.
1324  *
1325  * After the call to this function, @a report_baton is no longer valid;
1326  * it should not be passed to any other reporting functions.
1327  */
1328 svn_error_t *
1329 svn_repos_abort_report(void *report_baton,
1330  apr_pool_t *pool);
1331 
1332 
1333 /* ---------------------------------------------------------------*/
1334 
1335 /* The magical dir_delta update routines. */
1336 
1337 /** Use the provided @a editor and @a edit_baton to describe the changes
1338  * necessary for making a given node (and its descendants, if it is a
1339  * directory) under @a src_root look exactly like @a tgt_path under
1340  * @a tgt_root. @a src_entry is the node to update. If @a src_entry
1341  * is empty, then compute the difference between the entire tree
1342  * anchored at @a src_parent_dir under @a src_root and @a tgt_path
1343  * under @a tgt_root. Else, describe the changes needed to update
1344  * only that entry in @a src_parent_dir. Typically, callers of this
1345  * function will use a @a tgt_path that is the concatenation of @a
1346  * src_parent_dir and @a src_entry.
1347  *
1348  * @a src_root and @a tgt_root can both be either revision or transaction
1349  * roots. If @a tgt_root is a revision, @a editor's set_target_revision()
1350  * will be called with the @a tgt_root's revision number, else it will
1351  * not be called at all.
1352  *
1353  * If @a authz_read_func is non-NULL, invoke it before any call to
1354  *
1355  * @a editor->open_root
1356  * @a editor->add_directory
1357  * @a editor->open_directory
1358  * @a editor->add_file
1359  * @a editor->open_file
1360  *
1361  * passing @a tgt_root, the same path that would be passed to the
1362  * editor function in question, and @a authz_read_baton. If the
1363  * @a *allowed parameter comes back TRUE, then proceed with the planned
1364  * editor call; else if FALSE, then invoke @a editor->absent_file or
1365  * @a editor->absent_directory as appropriate, except if the planned
1366  * editor call was open_root, throw SVN_ERR_AUTHZ_ROOT_UNREADABLE.
1367  *
1368  * If @a text_deltas is @c FALSE, send a single @c NULL txdelta window to
1369  * the window handler returned by @a editor->apply_textdelta().
1370  *
1371  * If @a depth is #svn_depth_empty, invoke @a editor calls only on
1372  * @a src_entry (or @a src_parent_dir, if @a src_entry is empty).
1373  * If @a depth is #svn_depth_files, also invoke the editor on file
1374  * children, if any; if #svn_depth_immediates, invoke it on
1375  * immediate subdirectories as well as files; if #svn_depth_infinity,
1376  * recurse fully.
1377  *
1378  * If @a entry_props is @c TRUE, accompany each opened/added entry with
1379  * propchange editor calls that relay special "entry props" (this
1380  * is typically used only for working copy updates).
1381  *
1382  * @a ignore_ancestry instructs the function to ignore node ancestry
1383  * when determining how to transmit differences.
1384  *
1385  * Before completing successfully, this function calls @a editor's
1386  * close_edit(), so the caller should expect its @a edit_baton to be
1387  * invalid after its use with this function.
1388  *
1389  * Do any allocation necessary for the delta computation in @a pool.
1390  * This function's maximum memory consumption is at most roughly
1391  * proportional to the greatest depth of the tree under @a tgt_root, not
1392  * the total size of the delta.
1393  *
1394  * ### svn_repos_dir_delta2 is mostly superseded by the reporter
1395  * ### functionality (svn_repos_begin_report3 and friends).
1396  * ### svn_repos_dir_delta2 does allow the roots to be transaction
1397  * ### roots rather than just revision roots, and it has the
1398  * ### entry_props flag. Almost all of Subversion's own code uses the
1399  * ### reporter instead; there are some stray references to the
1400  * ### svn_repos_dir_delta[2] in comments which should probably
1401  * ### actually refer to the reporter.
1402  *
1403  * @since New in 1.5.
1404  */
1405 svn_error_t *
1407  const char *src_parent_dir,
1408  const char *src_entry,
1409  svn_fs_root_t *tgt_root,
1410  const char *tgt_path,
1411  const svn_delta_editor_t *editor,
1412  void *edit_baton,
1413  svn_repos_authz_func_t authz_read_func,
1414  void *authz_read_baton,
1415  svn_boolean_t text_deltas,
1416  svn_depth_t depth,
1417  svn_boolean_t entry_props,
1418  svn_boolean_t ignore_ancestry,
1419  apr_pool_t *pool);
1420 
1421 /**
1422  * Similar to svn_repos_dir_delta2(), but if @a recurse is TRUE, pass
1423  * #svn_depth_infinity for @a depth, and if @a recurse is FALSE,
1424  * pass #svn_depth_files for @a depth.
1425  *
1426  * @deprecated Provided for backward compatibility with the 1.4 API.
1427  */
1429 svn_error_t *
1431  const char *src_parent_dir,
1432  const char *src_entry,
1433  svn_fs_root_t *tgt_root,
1434  const char *tgt_path,
1435  const svn_delta_editor_t *editor,
1436  void *edit_baton,
1437  svn_repos_authz_func_t authz_read_func,
1438  void *authz_read_baton,
1439  svn_boolean_t text_deltas,
1440  svn_boolean_t recurse,
1441  svn_boolean_t entry_props,
1442  svn_boolean_t ignore_ancestry,
1443  apr_pool_t *pool);
1444 
1445 
1446 /** Use the provided @a editor and @a edit_baton to describe the
1447  * skeletal changes made in a particular filesystem @a root
1448  * (revision or transaction).
1449  *
1450  * Changes will be limited to those within @a base_dir, and if
1451  * @a low_water_mark is set to something other than #SVN_INVALID_REVNUM
1452  * it is assumed that the client has no knowledge of revisions prior to
1453  * @a low_water_mark. Together, these two arguments define the portion of
1454  * the tree that the client is assumed to have knowledge of, and thus any
1455  * copies of data from outside that part of the tree will be sent in their
1456  * entirety, not as simple copies or deltas against a previous version.
1457  *
1458  * The @a editor passed to this function should be aware of the fact
1459  * that, if @a send_deltas is FALSE, calls to its change_dir_prop(),
1460  * change_file_prop(), and apply_textdelta() functions will not
1461  * contain meaningful data, and merely serve as indications that
1462  * properties or textual contents were changed.
1463  *
1464  * If @a send_deltas is @c TRUE, the text and property deltas for changes
1465  * will be sent, otherwise NULL text deltas and empty prop changes will be
1466  * used.
1467  *
1468  * If @a authz_read_func is non-NULL, it will be used to determine if the
1469  * user has read access to the data being accessed. Data that the user
1470  * cannot access will be skipped.
1471  *
1472  * @note This editor driver passes SVN_INVALID_REVNUM for all
1473  * revision parameters in the editor interface except the copyfrom
1474  * parameter of the add_file() and add_directory() editor functions.
1475  *
1476  * @since New in 1.4.
1477  */
1478 svn_error_t *
1480  const char *base_dir,
1481  svn_revnum_t low_water_mark,
1482  svn_boolean_t send_deltas,
1483  const svn_delta_editor_t *editor,
1484  void *edit_baton,
1485  svn_repos_authz_func_t authz_read_func,
1486  void *authz_read_baton,
1487  apr_pool_t *pool);
1488 
1489 /**
1490  * Similar to svn_repos_replay2(), but with @a base_dir set to @c "",
1491  * @a low_water_mark set to #SVN_INVALID_REVNUM, @a send_deltas
1492  * set to @c FALSE, and @a authz_read_func and @a authz_read_baton
1493  * set to @c NULL.
1494  *
1495  * @deprecated Provided for backward compatibility with the 1.3 API.
1496  */
1498 svn_error_t *
1500  const svn_delta_editor_t *editor,
1501  void *edit_baton,
1502  apr_pool_t *pool);
1503 
1504 /* ---------------------------------------------------------------*/
1505 
1506 /* Making commits. */
1507 
1508 /**
1509  * Return an @a editor and @a edit_baton to commit changes to the
1510  * filesystem of @a repos, beginning at location 'rev:@a base_path',
1511  * where "rev" is the argument given to open_root().
1512  *
1513  * @a repos is a previously opened repository. @a repos_url_decoded is the
1514  * decoded URL to the base of the repository, and is used to check
1515  * copyfrom paths. @a txn is a filesystem transaction object to use
1516  * during the commit, or @c NULL to indicate that this function should
1517  * create (and fully manage) a new transaction.
1518  *
1519  * Store the contents of @a revprop_table, a hash mapping <tt>const
1520  * char *</tt> property names to #svn_string_t values, as properties
1521  * of the commit transaction, including author and log message if
1522  * present.
1523  *
1524  * @note #SVN_PROP_REVISION_DATE may be present in @a revprop_table, but
1525  * it will be overwritten when the transaction is committed.
1526  *
1527  * Iff @a authz_callback is provided, check read/write authorizations
1528  * on paths accessed by editor operations. An operation which fails
1529  * due to authz will return SVN_ERR_AUTHZ_UNREADABLE or
1530  * SVN_ERR_AUTHZ_UNWRITABLE.
1531  *
1532  * Calling @a (*editor)->close_edit completes the commit.
1533  *
1534  * If @a commit_callback is non-NULL, then before @c close_edit returns (but
1535  * after the commit has succeeded) @c close_edit will invoke
1536  * @a commit_callback with a filled-in #svn_commit_info_t *, @a commit_baton,
1537  * and @a pool or some subpool thereof as arguments. The @c repos_root field
1538  * of the #svn_commit_info_t is @c NULL. If @a commit_callback
1539  * returns an error, that error will be returned from @c close_edit,
1540  * otherwise if there was a post-commit hook failure, then that error
1541  * will be returned with code SVN_ERR_REPOS_POST_COMMIT_HOOK_FAILED.
1542  * (Note that prior to Subversion 1.6, @a commit_callback cannot be @c NULL;
1543  * if you don't need a callback, pass a dummy function.)
1544  *
1545  * Calling @a (*editor)->abort_edit aborts the commit, and will also
1546  * abort the commit transaction unless @a txn was supplied (not @c
1547  * NULL). Callers who supply their own transactions are responsible
1548  * for cleaning them up (either by committing them, or aborting them).
1549  *
1550  * @since New in 1.5. Since 1.6, @a commit_callback can be @c NULL.
1551  *
1552  * @note Yes, @a repos_url_decoded is a <em>decoded</em> URL. We realize
1553  * that's sorta wonky. Sorry about that.
1554  *
1555  * @note Like most commit editors, the returned editor requires that the
1556  * @c copyfrom_path parameter passed to its @c add_file and @c add_directory
1557  * methods is a full, URI-encoded URL, not a relative path.
1558  */
1559 svn_error_t *
1561  void **edit_baton,
1562  svn_repos_t *repos,
1563  svn_fs_txn_t *txn,
1564  const char *repos_url_decoded,
1565  const char *base_path,
1566  apr_hash_t *revprop_table,
1567  svn_commit_callback2_t commit_callback,
1568  void *commit_baton,
1569  svn_repos_authz_callback_t authz_callback,
1570  void *authz_baton,
1571  apr_pool_t *pool);
1572 
1573 /**
1574  * Similar to svn_repos_get_commit_editor5(), but with @a revprop_table
1575  * set to a hash containing @a user and @a log_msg as the
1576  * #SVN_PROP_REVISION_AUTHOR and #SVN_PROP_REVISION_LOG properties,
1577  * respectively. @a user and @a log_msg may both be @c NULL.
1578  *
1579  * @since New in 1.4.
1580  *
1581  * @deprecated Provided for backward compatibility with the 1.4 API.
1582  */
1584 svn_error_t *
1586  void **edit_baton,
1587  svn_repos_t *repos,
1588  svn_fs_txn_t *txn,
1589  const char *repos_url,
1590  const char *base_path,
1591  const char *user,
1592  const char *log_msg,
1593  svn_commit_callback2_t commit_callback,
1594  void *commit_baton,
1595  svn_repos_authz_callback_t authz_callback,
1596  void *authz_baton,
1597  apr_pool_t *pool);
1598 
1599 /**
1600  * Similar to svn_repos_get_commit_editor4(), but
1601  * uses the svn_commit_callback_t type.
1602  *
1603  * @since New in 1.3.
1604  *
1605  * @deprecated Provided for backward compatibility with the 1.3 API.
1606  */
1608 svn_error_t *
1610  void **edit_baton,
1611  svn_repos_t *repos,
1612  svn_fs_txn_t *txn,
1613  const char *repos_url,
1614  const char *base_path,
1615  const char *user,
1616  const char *log_msg,
1617  svn_commit_callback_t callback,
1618  void *callback_baton,
1619  svn_repos_authz_callback_t authz_callback,
1620  void *authz_baton,
1621  apr_pool_t *pool);
1622 
1623 /**
1624  * Similar to svn_repos_get_commit_editor3(), but with @a
1625  * authz_callback and @a authz_baton set to @c NULL.
1626  *
1627  * @deprecated Provided for backward compatibility with the 1.2 API.
1628  */
1630 svn_error_t *
1632  void **edit_baton,
1633  svn_repos_t *repos,
1634  svn_fs_txn_t *txn,
1635  const char *repos_url,
1636  const char *base_path,
1637  const char *user,
1638  const char *log_msg,
1639  svn_commit_callback_t callback,
1640  void *callback_baton,
1641  apr_pool_t *pool);
1642 
1643 
1644 /**
1645  * Similar to svn_repos_get_commit_editor2(), but with @a txn always
1646  * set to @c NULL.
1647  *
1648  * @deprecated Provided for backward compatibility with the 1.1 API.
1649  */
1651 svn_error_t *
1653  void **edit_baton,
1654  svn_repos_t *repos,
1655  const char *repos_url,
1656  const char *base_path,
1657  const char *user,
1658  const char *log_msg,
1659  svn_commit_callback_t callback,
1660  void *callback_baton,
1661  apr_pool_t *pool);
1662 
1663 /* ---------------------------------------------------------------*/
1664 
1665 /* Finding particular revisions. */
1666 
1667 /** Set @a *revision to the revision number in @a repos's filesystem that was
1668  * youngest at time @a tm.
1669  */
1670 svn_error_t *
1672  svn_repos_t *repos,
1673  apr_time_t tm,
1674  apr_pool_t *pool);
1675 
1676 
1677 /** Given a @a root/@a path within some filesystem, return three pieces of
1678  * information allocated in @a pool:
1679  *
1680  * - set @a *committed_rev to the revision in which the object was
1681  * last modified. (In fs parlance, this is the revision in which
1682  * the particular node-rev-id was 'created'.)
1683  *
1684  * - set @a *committed_date to the date of said revision, or @c NULL
1685  * if not available.
1686  *
1687  * - set @a *last_author to the author of said revision, or @c NULL
1688  * if not available.
1689  */
1690 svn_error_t *
1692  const char **committed_date,
1693  const char **last_author,
1694  svn_fs_root_t *root,
1695  const char *path,
1696  apr_pool_t *pool);
1697 
1698 
1699 /**
1700  * Set @a *dirent to an #svn_dirent_t associated with @a path in @a
1701  * root. If @a path does not exist in @a root, set @a *dirent to
1702  * NULL. Use @a pool for memory allocation.
1703  *
1704  * @since New in 1.2.
1705  */
1706 svn_error_t *
1707 svn_repos_stat(svn_dirent_t **dirent,
1708  svn_fs_root_t *root,
1709  const char *path,
1710  apr_pool_t *pool);
1711 
1712 
1713 /**
1714  * Given @a path which exists at revision @a start in @a fs, set
1715  * @a *deleted to the revision @a path was first deleted, within the
1716  * inclusive revision range bounded by @a start and @a end. If @a path
1717  * does not exist at revision @a start or was not deleted within the
1718  * specified range, then set @a *deleted to SVN_INVALID_REVNUM.
1719  * Use @a pool for memory allocation.
1720  *
1721  * @since New in 1.5.
1722  */
1723 svn_error_t *
1725  const char *path,
1726  svn_revnum_t start,
1727  svn_revnum_t end,
1728  svn_revnum_t *deleted,
1729  apr_pool_t *pool);
1730 
1731 
1732 /** Callback type for use with svn_repos_history(). @a path and @a
1733  * revision represent interesting history locations in the lifetime
1734  * of the path passed to svn_repos_history(). @a baton is the same
1735  * baton given to svn_repos_history(). @a pool is provided for the
1736  * convenience of the implementor, who should not expect it to live
1737  * longer than a single callback call.
1738  *
1739  * Signal to callback driver to stop processing/invoking this callback
1740  * by returning the #SVN_ERR_CEASE_INVOCATION error code.
1741  *
1742  * @note SVN_ERR_CEASE_INVOCATION is new in 1.5.
1743  */
1744 typedef svn_error_t *(*svn_repos_history_func_t)(void *baton,
1745  const char *path,
1746  svn_revnum_t revision,
1747  apr_pool_t *pool);
1748 
1749 /**
1750  * Call @a history_func (with @a history_baton) for each interesting
1751  * history location in the lifetime of @a path in @a fs, from the
1752  * youngest of @a end and @a start to the oldest. Stop processing if
1753  * @a history_func returns #SVN_ERR_CEASE_INVOCATION. Only cross
1754  * filesystem copy history if @a cross_copies is @c TRUE. And do all
1755  * of this in @a pool.
1756  *
1757  * If @a authz_read_func is non-NULL, then use it (and @a
1758  * authz_read_baton) to verify that @a path in @a end is readable; if
1759  * not, return SVN_ERR_AUTHZ_UNREADABLE. Also verify the readability
1760  * of every ancestral path/revision pair before pushing them at @a
1761  * history_func. If a pair is deemed unreadable, then do not send
1762  * them; instead, immediately stop traversing history and return
1763  * SVN_NO_ERROR.
1764  *
1765  * @since New in 1.1.
1766  *
1767  * @note SVN_ERR_CEASE_INVOCATION is new in 1.5.
1768  */
1769 svn_error_t *
1771  const char *path,
1772  svn_repos_history_func_t history_func,
1773  void *history_baton,
1774  svn_repos_authz_func_t authz_read_func,
1775  void *authz_read_baton,
1776  svn_revnum_t start,
1777  svn_revnum_t end,
1778  svn_boolean_t cross_copies,
1779  apr_pool_t *pool);
1780 
1781 /**
1782  * Similar to svn_repos_history2(), but with @a authz_read_func
1783  * and @a authz_read_baton always set to NULL.
1784  *
1785  * @deprecated Provided for backward compatibility with the 1.0 API.
1786  */
1788 svn_error_t *
1790  const char *path,
1791  svn_repos_history_func_t history_func,
1792  void *history_baton,
1793  svn_revnum_t start,
1794  svn_revnum_t end,
1795  svn_boolean_t cross_copies,
1796  apr_pool_t *pool);
1797 
1798 
1799 /**
1800  * Set @a *locations to be a mapping of the revisions to the paths of
1801  * the file @a fs_path present at the repository in revision
1802  * @a peg_revision, where the revisions are taken out of the array
1803  * @a location_revisions.
1804  *
1805  * @a location_revisions is an array of svn_revnum_t's and @a *locations
1806  * maps 'svn_revnum_t *' to 'const char *'.
1807  *
1808  * If optional @a authz_read_func is non-NULL, then use it (and @a
1809  * authz_read_baton) to verify that the peg-object is readable. If not,
1810  * return SVN_ERR_AUTHZ_UNREADABLE. Also use the @a authz_read_func
1811  * to check that every path returned in the hash is readable. If an
1812  * unreadable path is encountered, stop tracing and return
1813  * SVN_NO_ERROR.
1814  *
1815  * @a pool is used for all allocations.
1816  *
1817  * @since New in 1.1.
1818  */
1819 svn_error_t *
1821  apr_hash_t **locations,
1822  const char *fs_path,
1823  svn_revnum_t peg_revision,
1824  const apr_array_header_t *location_revisions,
1825  svn_repos_authz_func_t authz_read_func,
1826  void *authz_read_baton,
1827  apr_pool_t *pool);
1828 
1829 
1830 /**
1831  * Call @a receiver and @a receiver_baton to report successive
1832  * location segments in revisions between @a start_rev and @a end_rev
1833  * (inclusive) for the line of history identified by the peg-object @a
1834  * path in @a peg_revision (and in @a repos).
1835  *
1836  * @a end_rev may be #SVN_INVALID_REVNUM to indicate that you want
1837  * to trace the history of the object to its origin.
1838  *
1839  * @a start_rev may be #SVN_INVALID_REVNUM to indicate "the HEAD
1840  * revision". Otherwise, @a start_rev must be younger than @a end_rev
1841  * (unless @a end_rev is #SVN_INVALID_REVNUM).
1842  *
1843  * @a peg_revision may be #SVN_INVALID_REVNUM to indicate "the HEAD
1844  * revision", and must evaluate to be at least as young as @a start_rev.
1845  *
1846  * If optional @a authz_read_func is not @c NULL, then use it (and @a
1847  * authz_read_baton) to verify that the peg-object is readable. If
1848  * not, return #SVN_ERR_AUTHZ_UNREADABLE. Also use the @a
1849  * authz_read_func to check that every path reported in a location
1850  * segment is readable. If an unreadable path is encountered, report
1851  * a final (possibly truncated) location segment (if any), stop
1852  * tracing history, and return #SVN_NO_ERROR.
1853  *
1854  * @a pool is used for all allocations.
1855  *
1856  * @since New in 1.5.
1857  */
1858 svn_error_t *
1860  const char *path,
1861  svn_revnum_t peg_revision,
1862  svn_revnum_t start_rev,
1863  svn_revnum_t end_rev,
1865  void *receiver_baton,
1866  svn_repos_authz_func_t authz_read_func,
1867  void *authz_read_baton,
1868  apr_pool_t *pool);
1869 
1870 
1871 /* ---------------------------------------------------------------*/
1872 
1873 /* Retrieving log messages. */
1874 
1875 
1876 /**
1877  * Invoke @a receiver with @a receiver_baton on each log message from
1878  * @a start to @a end in @a repos's filesystem. @a start may be greater
1879  * or less than @a end; this just controls whether the log messages are
1880  * processed in descending or ascending revision number order.
1881  *
1882  * If @a start or @a end is #SVN_INVALID_REVNUM, it defaults to youngest.
1883  *
1884  * If @a paths is non-NULL and has one or more elements, then only show
1885  * revisions in which at least one of @a paths was changed (i.e., if
1886  * file, text or props changed; if dir, props or entries changed or any node
1887  * changed below it). Each path is a <tt>const char *</tt> representing
1888  * an absolute path in the repository. If @a paths is NULL or empty,
1889  * show all revisions regardless of what paths were changed in those
1890  * revisions.
1891  *
1892  * If @a limit is greater than zero then only invoke @a receiver on the first
1893  * @a limit logs.
1894  *
1895  * If @a discover_changed_paths, then each call to @a receiver passes a
1896  * hash mapping paths committed in that revision to information about them
1897  * as the receiver's @a changed_paths argument.
1898  * Otherwise, each call to @a receiver passes NULL for @a changed_paths.
1899  *
1900  * If @a strict_node_history is set, copy history (if any exists) will
1901  * not be traversed while harvesting revision logs for each path.
1902  *
1903  * If @a include_merged_revisions is set, log information for revisions
1904  * which have been merged to @a paths will also be returned, unless these
1905  * revisions are already part of @a start to @a end in @a repos's
1906  * filesystem, as limited by @a paths. In the latter case those revisions
1907  * are skipped and @a receiver is not invoked.
1908  *
1909  * If @a revprops is NULL, retrieve all revision properties; else, retrieve
1910  * only the revision properties named by the (const char *) array elements
1911  * (i.e. retrieve none if the array is empty).
1912  *
1913  * If any invocation of @a receiver returns error, return that error
1914  * immediately and without wrapping it.
1915  *
1916  * If @a start or @a end is a non-existent revision, return the error
1917  * #SVN_ERR_FS_NO_SUCH_REVISION, without ever invoking @a receiver.
1918  *
1919  * If optional @a authz_read_func is non-NULL, then use this function
1920  * (along with optional @a authz_read_baton) to check the readability
1921  * of each changed-path in each revision about to be "pushed" at
1922  * @a receiver. If a revision has some changed-paths readable and
1923  * others unreadable, unreadable paths are omitted from the
1924  * changed_paths field and only svn:author and svn:date will be
1925  * available in the revprops field. If a revision has no
1926  * changed-paths readable at all, then all paths are omitted and no
1927  * revprops are available.
1928  *
1929  * See also the documentation for #svn_log_entry_receiver_t.
1930  *
1931  * Use @a pool for temporary allocations.
1932  *
1933  * @since New in 1.5.
1934  */
1935 svn_error_t *
1937  const apr_array_header_t *paths,
1938  svn_revnum_t start,
1939  svn_revnum_t end,
1940  int limit,
1941  svn_boolean_t discover_changed_paths,
1942  svn_boolean_t strict_node_history,
1943  svn_boolean_t include_merged_revisions,
1944  const apr_array_header_t *revprops,
1945  svn_repos_authz_func_t authz_read_func,
1946  void *authz_read_baton,
1947  svn_log_entry_receiver_t receiver,
1948  void *receiver_baton,
1949  apr_pool_t *pool);
1950 
1951 /**
1952  * Same as svn_repos_get_logs4(), but with @a receiver being
1953  * #svn_log_message_receiver_t instead of #svn_log_entry_receiver_t.
1954  * Also, @a include_merged_revisions is set to @c FALSE and @a revprops is
1955  * svn:author, svn:date, and svn:log. If @a paths is empty, nothing
1956  * is returned.
1957  *
1958  * @since New in 1.2.
1959  * @deprecated Provided for backward compatibility with the 1.4 API.
1960  */
1962 svn_error_t *
1964  const apr_array_header_t *paths,
1965  svn_revnum_t start,
1966  svn_revnum_t end,
1967  int limit,
1968  svn_boolean_t discover_changed_paths,
1969  svn_boolean_t strict_node_history,
1970  svn_repos_authz_func_t authz_read_func,
1971  void *authz_read_baton,
1972  svn_log_message_receiver_t receiver,
1973  void *receiver_baton,
1974  apr_pool_t *pool);
1975 
1976 
1977 /**
1978  * Same as svn_repos_get_logs3(), but with @a limit always set to 0.
1979  *
1980  * @deprecated Provided for backward compatibility with the 1.1 API.
1981  */
1983 svn_error_t *
1985  const apr_array_header_t *paths,
1986  svn_revnum_t start,
1987  svn_revnum_t end,
1988  svn_boolean_t discover_changed_paths,
1989  svn_boolean_t strict_node_history,
1990  svn_repos_authz_func_t authz_read_func,
1991  void *authz_read_baton,
1992  svn_log_message_receiver_t receiver,
1993  void *receiver_baton,
1994  apr_pool_t *pool);
1995 
1996 /**
1997  * Same as svn_repos_get_logs2(), but with @a authz_read_func and
1998  * @a authz_read_baton always set to NULL.
1999  *
2000  * @deprecated Provided for backward compatibility with the 1.0 API.
2001  */
2003 svn_error_t *
2005  const apr_array_header_t *paths,
2006  svn_revnum_t start,
2007  svn_revnum_t end,
2008  svn_boolean_t discover_changed_paths,
2009  svn_boolean_t strict_node_history,
2010  svn_log_message_receiver_t receiver,
2011  void *receiver_baton,
2012  apr_pool_t *pool);
2013 
2014 
2015 
2016 /* ---------------------------------------------------------------*/
2017 
2018 /* Retrieving mergeinfo. */
2019 
2020 /**
2021  * Fetch the mergeinfo for @a paths at @a revision in @a repos, and
2022  * set @a *catalog to a catalog of this mergeinfo. @a *catalog will
2023  * never be @c NULL but may be empty.
2024  *
2025  * The paths in @a paths, and the keys of @a catalog, start with '/'.
2026  *
2027  * @a inherit indicates whether explicit, explicit or inherited, or
2028  * only inherited mergeinfo for @a paths is fetched.
2029  *
2030  * If @a revision is #SVN_INVALID_REVNUM, it defaults to youngest.
2031  *
2032  * If @a include_descendants is TRUE, then additionally return the
2033  * mergeinfo for any descendant of any element of @a paths which has
2034  * the #SVN_PROP_MERGEINFO property explicitly set on it. (Note
2035  * that inheritance is only taken into account for the elements in @a
2036  * paths; descendants of the elements in @a paths which get their
2037  * mergeinfo via inheritance are not included in @a *catalog.)
2038  *
2039  * If optional @a authz_read_func is non-NULL, then use this function
2040  * (along with optional @a authz_read_baton) to check the readability
2041  * of each path which mergeinfo was requested for (from @a paths).
2042  * Silently omit unreadable paths from the request for mergeinfo.
2043  *
2044  * Use @a pool for all allocations.
2045  *
2046  * @since New in 1.5.
2047  */
2048 svn_error_t *
2050  svn_repos_t *repos,
2051  const apr_array_header_t *paths,
2052  svn_revnum_t revision,
2054  svn_boolean_t include_descendants,
2055  svn_repos_authz_func_t authz_read_func,
2056  void *authz_read_baton,
2057  apr_pool_t *pool);
2058 
2059 
2060 /* ---------------------------------------------------------------*/
2061 
2062 /* Retrieving multiple revisions of a file. */
2063 
2064 /**
2065  * Retrieve a subset of the interesting revisions of a file @a path in
2066  * @a repos as seen in revision @a end. Invoke @a handler with
2067  * @a handler_baton as its first argument for each such revision.
2068  * @a pool is used for all allocations. See svn_fs_history_prev() for
2069  * a discussion of interesting revisions.
2070  *
2071  * If optional @a authz_read_func is non-NULL, then use this function
2072  * (along with optional @a authz_read_baton) to check the readability
2073  * of the rev-path in each interesting revision encountered.
2074  *
2075  * Revision discovery happens from @a end to @a start, and if an
2076  * unreadable revision is encountered before @a start is reached, then
2077  * revision discovery stops and only the revisions from @a end to the
2078  * oldest readable revision are returned (So it will appear that @a
2079  * path was added without history in the latter revision).
2080  *
2081  * If there is an interesting revision of the file that is less than or
2082  * equal to start, the iteration will start at that revision. Else, the
2083  * iteration will start at the first revision of the file in the repository,
2084  * which has to be less than or equal to end. Note that if the function
2085  * succeeds, @a handler will have been called at least once.
2086  *
2087  * In a series of calls, the file contents for the first interesting revision
2088  * will be provided as a text delta against the empty file. In the following
2089  * calls, the delta will be against the contents for the previous call.
2090  *
2091  * If @a include_merged_revisions is TRUE, revisions which a included as a
2092  * result of a merge between @a start and @a end will be included.
2093  *
2094  * Since Subversion 1.8 this function has been enabled to support reversion
2095  * the revision range for @a include_merged_revision @c FALSE reporting by
2096  * switching @a start with @a end.
2097  *
2098  * @note Prior to Subversion 1.9, this function may request delta handlers
2099  * from @a handler even for empty text deltas. Starting with 1.9, the
2100  * delta handler / baton return arguments passed to @a handler will be
2101  * #NULL unless there is an actual difference in the file contents between
2102  * the current and the previous call.
2103  *
2104  * @since New in 1.5.
2105  */
2106 svn_error_t *
2108  const char *path,
2109  svn_revnum_t start,
2110  svn_revnum_t end,
2111  svn_boolean_t include_merged_revisions,
2112  svn_repos_authz_func_t authz_read_func,
2113  void *authz_read_baton,
2114  svn_file_rev_handler_t handler,
2115  void *handler_baton,
2116  apr_pool_t *pool);
2117 
2118 /**
2119  * Similar to #svn_file_rev_handler_t, but without the @a
2120  * result_of_merge parameter.
2121  *
2122  * @deprecated Provided for backward compatibility with 1.4 API.
2123  * @since New in 1.1.
2124  */
2125 typedef svn_error_t *(*svn_repos_file_rev_handler_t)
2126  (void *baton,
2127  const char *path,
2128  svn_revnum_t rev,
2129  apr_hash_t *rev_props,
2130  svn_txdelta_window_handler_t *delta_handler,
2131  void **delta_baton,
2132  apr_array_header_t *prop_diffs,
2133  apr_pool_t *pool);
2134 
2135 /**
2136  * Similar to svn_repos_get_file_revs2(), with @a include_merged_revisions
2137  * set to FALSE.
2138  *
2139  * @deprecated Provided for backward compatibility with the 1.4 API.
2140  * @since New in 1.1.
2141  */
2143 svn_error_t *
2145  const char *path,
2146  svn_revnum_t start,
2147  svn_revnum_t end,
2148  svn_repos_authz_func_t authz_read_func,
2149  void *authz_read_baton,
2151  void *handler_baton,
2152  apr_pool_t *pool);
2153 
2154 
2155 /* ---------------------------------------------------------------*/
2156 
2157 /**
2158  * @defgroup svn_repos_hook_wrappers Hook-sensitive wrappers for libsvn_fs \
2159  * routines.
2160  * @{
2161  */
2162 
2163 /** Like svn_fs_commit_txn(), but invoke the @a repos' pre- and
2164  * post-commit hooks around the commit. Use @a pool for any necessary
2165  * allocations.
2166  *
2167  * If the pre-commit hook fails, do not attempt to commit the
2168  * transaction and throw the original error to the caller.
2169  *
2170  * A successful commit is indicated by a valid revision value in @a
2171  * *new_rev, not if svn_fs_commit_txn() returns an error, which can
2172  * occur during its post commit FS processing. If the transaction was
2173  * not committed, then return the associated error and do not execute
2174  * the post-commit hook.
2175  *
2176  * If the commit succeeds the post-commit hook is executed. If the
2177  * post-commit hook returns an error, always wrap it with
2178  * SVN_ERR_REPOS_POST_COMMIT_HOOK_FAILED; this allows the caller to
2179  * find the post-commit hook error in the returned error chain. If
2180  * both svn_fs_commit_txn() and the post-commit hook return errors,
2181  * then svn_fs_commit_txn()'s error is the parent error and the
2182  * SVN_ERR_REPOS_POST_COMMIT_HOOK_FAILED wrapped error is the child
2183  * error.
2184  *
2185  * @a conflict_p, @a new_rev, and @a txn are as in svn_fs_commit_txn().
2186  */
2187 svn_error_t *
2188 svn_repos_fs_commit_txn(const char **conflict_p,
2189  svn_repos_t *repos,
2190  svn_revnum_t *new_rev,
2191  svn_fs_txn_t *txn,
2192  apr_pool_t *pool);
2193 
2194 /** Like svn_fs_begin_txn(), but use @a revprop_table, a hash mapping
2195  * <tt>const char *</tt> property names to #svn_string_t values, to
2196  * set the properties on transaction @a *txn_p. @a repos is the
2197  * repository object which contains the filesystem. @a rev, @a
2198  * *txn_p, and @a pool are as in svn_fs_begin_txn().
2199  *
2200  * Before a txn is created, the repository's start-commit hooks are
2201  * run; if any of them fail, no txn is created, @a *txn_p is unaffected,
2202  * and #SVN_ERR_REPOS_HOOK_FAILURE is returned.
2203  *
2204  * @note @a revprop_table may contain an #SVN_PROP_REVISION_DATE property,
2205  * which will be set on the transaction, but that will be overwritten
2206  * when the transaction is committed.
2207  *
2208  * @since New in 1.5.
2209  */
2210 svn_error_t *
2212  svn_repos_t *repos,
2213  svn_revnum_t rev,
2214  apr_hash_t *revprop_table,
2215  apr_pool_t *pool);
2216 
2217 
2218 /**
2219  * Same as svn_repos_fs_begin_txn_for_commit2(), but with @a revprop_table
2220  * set to a hash containing @a author and @a log_msg as the
2221  * #SVN_PROP_REVISION_AUTHOR and #SVN_PROP_REVISION_LOG properties,
2222  * respectively. @a author and @a log_msg may both be @c NULL.
2223  *
2224  * @deprecated Provided for backward compatibility with the 1.4 API.
2225  */
2227 svn_error_t *
2229  svn_repos_t *repos,
2230  svn_revnum_t rev,
2231  const char *author,
2232  const char *log_msg,
2233  apr_pool_t *pool);
2234 
2235 
2236 /** Like svn_fs_begin_txn(), but use @a author to set the corresponding
2237  * property on transaction @a *txn_p. @a repos is the repository object
2238  * which contains the filesystem. @a rev, @a *txn_p, and @a pool are as in
2239  * svn_fs_begin_txn().
2240  *
2241  * ### Someday: before a txn is created, some kind of read-hook could
2242  * be called here.
2243  *
2244  * @note This function was never fully implemented, nor used. Ignore it.
2245  * @deprecated Provided for backward compatibility with the 1.7 API.
2246  */
2248 svn_error_t *
2250  svn_repos_t *repos,
2251  svn_revnum_t rev,
2252  const char *author,
2253  apr_pool_t *pool);
2254 
2255 
2256 /** @} */
2257 
2258 /** @defgroup svn_repos_fs_locks Repository lock wrappers
2259  * @{
2260  */
2261 
2262 /** Like svn_fs_lock_many(), but invoke the @a repos's pre- and
2263  * post-lock hooks before and after the locking action.
2264  *
2265  * The pre-lock is run for every path in @a targets. Those targets for
2266  * which the pre-lock is successful are passed to svn_fs_lock_many and
2267  * the post-lock is run for those that are successfully locked.
2268  * Pre-lock hook errors are passed to @a lock_callback.
2269  *
2270  * For each path in @a targets @a lock_callback will be invoked
2271  * passing @a lock_baton and the lock and error that apply to path.
2272  * @a lock_callback can be NULL in which case it is not called and any
2273  * errors that would have been passed to the callback are not reported.
2274  *
2275  * If an error occurs when running the post-lock hook the error is
2276  * returned wrapped with #SVN_ERR_REPOS_POST_LOCK_HOOK_FAILED. If the
2277  * caller sees this error, it knows that some locks succeeded.
2278  *
2279  * The pre-lock hook may cause a different token to be used for the
2280  * lock, instead of the token supplied; see the pre-lock-hook
2281  * documentation for more.
2282  *
2283  * The lock and path passed to @a lock_callback will be allocated in
2284  * @a result_pool. Use @a scratch_pool for temporary allocations.
2285  *
2286  * @note This function is not atomic. If it returns an error, some targets
2287  * may remain unlocked while others may have been locked.
2288  *
2289  * @see svn_fs_lock_many
2290  *
2291  * @since New in 1.9.
2292  */
2293 svn_error_t *
2295  apr_hash_t *lock_targets,
2296  const char *comment,
2297  svn_boolean_t is_dav_comment,
2298  apr_time_t expiration_date,
2299  svn_boolean_t steal_lock,
2300  svn_fs_lock_callback_t lock_callback,
2301  void *lock_baton,
2302  apr_pool_t *result_pool,
2303  apr_pool_t *scratch_pool);
2304 
2305 /** Similar to svn_repos_fs_lock_many() but locks only a single path.
2306  *
2307  * @since New in 1.2.
2308  */
2309 svn_error_t *
2311  svn_repos_t *repos,
2312  const char *path,
2313  const char *token,
2314  const char *comment,
2315  svn_boolean_t is_dav_comment,
2316  apr_time_t expiration_date,
2317  svn_revnum_t current_rev,
2318  svn_boolean_t steal_lock,
2319  apr_pool_t *pool);
2320 
2321 
2322 /** Like svn_fs_unlock_many(), but invoke the @a repos's pre- and
2323  * post-unlock hooks before and after the unlocking action.
2324  *
2325  * The pre-unlock hook is run for every path in @a targets. Those
2326  * targets for which the pre-unlock is successful are passed to
2327  * svn_fs_unlock_many and the post-unlock is run for those that are
2328  * successfully unlocked. Pre-unlock hook errors are passed to @a
2329  * lock_callback.
2330  *
2331  * For each path in @a targets @a lock_callback will be invoked
2332  * passing @a lock_baton and error that apply to path. The lock
2333  * passed to the callback will be NULL. @a lock_callback can be NULL
2334  * in which case it is not called and any errors that would have been
2335  * passed to the callback are not reported.
2336  *
2337  * If an error occurs when running the post-unlock hook, return the
2338  * original error wrapped with #SVN_ERR_REPOS_POST_UNLOCK_HOOK_FAILED.
2339  * If the caller sees this error, it knows that some unlocks
2340  * succeeded.
2341  *
2342  * The path passed to @a lock_callback will be allocated in @a result_pool.
2343  * Use @a scratch_pool for temporary allocations.
2344  *
2345  * @note This function is not atomic. If it returns an error, some targets
2346  * may remain locked while others may have been unlocked.
2347  *
2348  * @see svn_fs_unlock_many
2349  *
2350  * @since New in 1.9.
2351  */
2352 svn_error_t *
2354  apr_hash_t *unlock_targets,
2355  svn_boolean_t break_lock,
2356  svn_fs_lock_callback_t lock_callback,
2357  void *lock_baton,
2358  apr_pool_t *result_pool,
2359  apr_pool_t *scratch_pool);
2360 
2361 /** Similar to svn_repos_fs_unlock_many() but only unlocks a single path.
2362  *
2363  * @since New in 1.2.
2364  */
2365 svn_error_t *
2367  const char *path,
2368  const char *token,
2369  svn_boolean_t break_lock,
2370  apr_pool_t *pool);
2371 
2372 
2373 
2374 /** Look up all the locks in and under @a path in @a repos, setting @a
2375  * *locks to a hash which maps <tt>const char *</tt> paths to the
2376  * #svn_lock_t locks associated with those paths. Use @a
2377  * authz_read_func and @a authz_read_baton to "screen" all returned
2378  * locks. That is: do not return any locks on any paths that are
2379  * unreadable in HEAD, just silently omit them.
2380  *
2381  * @a depth limits the returned locks to those associated with paths
2382  * within the specified depth of @a path, and must be one of the
2383  * following values: #svn_depth_empty, #svn_depth_files,
2384  * #svn_depth_immediates, or #svn_depth_infinity.
2385  *
2386  * @since New in 1.7.
2387  */
2388 svn_error_t *
2389 svn_repos_fs_get_locks2(apr_hash_t **locks,
2390  svn_repos_t *repos,
2391  const char *path,
2392  svn_depth_t depth,
2393  svn_repos_authz_func_t authz_read_func,
2394  void *authz_read_baton,
2395  apr_pool_t *pool);
2396 
2397 /**
2398  * Similar to svn_repos_fs_get_locks2(), but with @a depth always
2399  * passed as svn_depth_infinity.
2400  *
2401  * @since New in 1.2.
2402  * @deprecated Provided for backward compatibility with the 1.6 API.
2403  */
2405 svn_error_t *
2406 svn_repos_fs_get_locks(apr_hash_t **locks,
2407  svn_repos_t *repos,
2408  const char *path,
2409  svn_repos_authz_func_t authz_read_func,
2410  void *authz_read_baton,
2411  apr_pool_t *pool);
2412 
2413 /** @} */
2414 
2415 /** @defgroup svn_repos_properties Versioned and Unversioned Properties
2416  *
2417  * Prop-changing and prop-reading wrappers for libsvn_fs routines.
2418  * @{
2419  */
2420 
2421 /**
2422  * Like svn_fs_change_rev_prop2(), but validate the name and value of the
2423  * property and invoke the @a repos's pre- and post-revprop-change hooks
2424  * around the change as specified by @a use_pre_revprop_change_hook and
2425  * @a use_post_revprop_change_hook (respectively).
2426  *
2427  * @a rev is the revision whose property to change, @a name is the
2428  * name of the property, and @a new_value is the new value of the
2429  * property. If @a old_value_p is not @c NULL, then @a *old_value_p
2430  * is the expected current (preexisting) value of the property (or @c NULL
2431  * for "unset"). @a author is the authenticated username of the person
2432  * changing the property value, or NULL if not available.
2433  *
2434  * If @a authz_read_func is non-NULL, then use it (with @a
2435  * authz_read_baton) to validate the changed-paths associated with @a
2436  * rev. If the revision contains any unreadable changed paths, then
2437  * return #SVN_ERR_AUTHZ_UNREADABLE.
2438  *
2439  * Validate @a name and @a new_value like the same way
2440  * svn_repos_fs_change_node_prop() does.
2441  *
2442  * Use @a pool for temporary allocations.
2443  *
2444  * @since New in 1.7.
2445  */
2446 svn_error_t *
2448  svn_revnum_t rev,
2449  const char *author,
2450  const char *name,
2451  const svn_string_t *const *old_value_p,
2452  const svn_string_t *new_value,
2453  svn_boolean_t use_pre_revprop_change_hook,
2454  svn_boolean_t use_post_revprop_change_hook,
2455  svn_repos_authz_func_t authz_read_func,
2456  void *authz_read_baton,
2457  apr_pool_t *pool);
2458 
2459 /**
2460  * Similar to svn_repos_fs_change_rev_prop4(), but with @a old_value_p always
2461  * set to @c NULL. (In other words, it is similar to
2462  * svn_fs_change_rev_prop().)
2463  *
2464  * @deprecated Provided for backward compatibility with the 1.6 API.
2465  * @since New in 1.5.
2466  */
2468 svn_error_t *
2470  svn_revnum_t rev,
2471  const char *author,
2472  const char *name,
2473  const svn_string_t *new_value,
2474  svn_boolean_t use_pre_revprop_change_hook,
2475  svn_boolean_t use_post_revprop_change_hook,
2476  svn_repos_authz_func_t authz_read_func,
2477  void *authz_read_baton,
2478  apr_pool_t *pool);
2479 
2480 /**
2481  * Similar to svn_repos_fs_change_rev_prop3(), but with the @a
2482  * use_pre_revprop_change_hook and @a use_post_revprop_change_hook
2483  * always set to @c TRUE.
2484  *
2485  * @deprecated Provided for backward compatibility with the 1.4 API.
2486  */
2488 svn_error_t *
2490  svn_revnum_t rev,
2491  const char *author,
2492  const char *name,
2493  const svn_string_t *new_value,
2494  svn_repos_authz_func_t authz_read_func,
2495  void *authz_read_baton,
2496  apr_pool_t *pool);
2497 
2498 /**
2499  * Similar to svn_repos_fs_change_rev_prop2(), but with the
2500  * @a authz_read_func parameter always NULL.
2501  *
2502  * @deprecated Provided for backward compatibility with the 1.0 API.
2503  */
2505 svn_error_t *
2507  svn_revnum_t rev,
2508  const char *author,
2509  const char *name,
2510  const svn_string_t *new_value,
2511  apr_pool_t *pool);
2512 
2513 
2514 
2515 /**
2516  * Set @a *value_p to the value of the property named @a propname on
2517  * revision @a rev in the filesystem opened in @a repos. If @a rev
2518  * has no property by that name, set @a *value_p to zero. Allocate
2519  * the result in @a pool.
2520  *
2521  * If @a authz_read_func is non-NULL, then use it (with @a
2522  * authz_read_baton) to validate the changed-paths associated with @a
2523  * rev. If the changed-paths are all unreadable, then set @a *value_p
2524  * to zero unconditionally. If only some of the changed-paths are
2525  * unreadable, then allow 'svn:author' and 'svn:date' propvalues to be
2526  * fetched, but return 0 for any other property.
2527  *
2528  * @since New in 1.1.
2529  */
2530 svn_error_t *
2532  svn_repos_t *repos,
2533  svn_revnum_t rev,
2534  const char *propname,
2535  svn_repos_authz_func_t authz_read_func,
2536  void *authz_read_baton,
2537  apr_pool_t *pool);
2538 
2539 
2540 /**
2541  * Set @a *table_p to the entire property list of revision @a rev in
2542  * filesystem opened in @a repos, as a hash table allocated in @a
2543  * pool. The table maps <tt>char *</tt> property names to
2544  * #svn_string_t * values; the names and values are allocated in @a
2545  * pool.
2546  *
2547  * If @a authz_read_func is non-NULL, then use it (with @a
2548  * authz_read_baton) to validate the changed-paths associated with @a
2549  * rev. If the changed-paths are all unreadable, then return an empty
2550  * hash. If only some of the changed-paths are unreadable, then return
2551  * an empty hash, except for 'svn:author' and 'svn:date' properties
2552  * (assuming those properties exist).
2553  *
2554  * @since New in 1.1.
2555  */
2556 svn_error_t *
2557 svn_repos_fs_revision_proplist(apr_hash_t **table_p,
2558  svn_repos_t *repos,
2559  svn_revnum_t rev,
2560  svn_repos_authz_func_t authz_read_func,
2561  void *authz_read_baton,
2562  apr_pool_t *pool);
2563 
2564 /** Validating wrapper for svn_fs_change_node_prop() (which see for
2565  * argument descriptions).
2566  *
2567  * If @a name's kind is not #svn_prop_regular_kind, return
2568  * #SVN_ERR_REPOS_BAD_ARGS. If @a name is an "svn:" property, validate its
2569  * @a value and return SVN_ERR_BAD_PROPERTY_VALUE if it is invalid for the
2570  * property.
2571  *
2572  * @note Originally, the only properties validated were the "svn:" properties
2573  * #SVN_PROP_REVISION_LOG and #SVN_PROP_REVISION_DATE. For the current
2574  * validation rules see the private function svn_repos__validate_prop().
2575  */
2576 svn_error_t *
2578  const char *path,
2579  const char *name,
2580  const svn_string_t *value,
2581  apr_pool_t *pool);
2582 
2583 /**
2584  * Set @a *inherited_values to a depth-first ordered array of
2585  * #svn_prop_inherited_item_t * structures (the path_or_url members of
2586  * which are relative filesystem paths) representing the properties
2587  * inherited by @a path in @a root. If no properties are inherited,
2588  * then set @a *inherited_values to an empty array.
2589  *
2590  * if @a propname is NULL then retrieve all explicit and/or inherited
2591  * properties. Otherwise retrieve only the properties named @a propname.
2592  *
2593  * If optional @a authz_read_func is non-NULL, then use this function
2594  * (along with optional @a authz_read_baton) to check the readability
2595  * of each parent path from which properties are inherited. Silently omit
2596  * properties for unreadable parent paths.
2597  *
2598  * Allocate @a *inherited_props in @a result_pool. Use @a scratch_pool for
2599  * temporary allocations.
2600  *
2601  * @since New in 1.8.
2602  */
2603 svn_error_t *
2604 svn_repos_fs_get_inherited_props(apr_array_header_t **inherited_props,
2605  svn_fs_root_t *root,
2606  const char *path,
2607  const char *propname,
2608  svn_repos_authz_func_t authz_read_func,
2609  void *authz_read_baton,
2610  apr_pool_t *result_pool,
2611  apr_pool_t *scratch_pool);
2612 
2613 /** Validating wrapper for svn_fs_change_txn_prop() (which see for
2614  * argument descriptions). See svn_repos_fs_change_txn_props() for more
2615  * information.
2616  */
2617 svn_error_t *
2619  const char *name,
2620  const svn_string_t *value,
2621  apr_pool_t *pool);
2622 
2623 /** Validating wrapper for svn_fs_change_txn_props() (which see for
2624  * argument descriptions). Validate properties and their values the
2625  * same way svn_repos_fs_change_node_prop() does.
2626  *
2627  * @since New in 1.5.
2628  */
2629 svn_error_t *
2631  const apr_array_header_t *props,
2632  apr_pool_t *pool);
2633 
2634 /** @} */
2635 
2636 
2637 /* ---------------------------------------------------------------*/
2638 
2639 /**
2640  * @defgroup svn_repos_inspection Data structures and editor things for \
2641  * repository inspection.
2642  * @{
2643  *
2644  * As it turns out, the svn_repos_replay2(), svn_repos_dir_delta2() and
2645  * svn_repos_begin_report3() interfaces can be extremely useful for
2646  * examining the repository, or more exactly, changes to the repository.
2647  * These drivers allows for differences between two trees to be
2648  * described using an editor.
2649  *
2650  * By using the editor obtained from svn_repos_node_editor() with one of
2651  * the drivers mentioned above, the description of how to transform one
2652  * tree into another can be used to build an in-memory linked-list tree,
2653  * which each node representing a repository node that was changed.
2654  */
2655 
2656 /** A node in the repository. */
2657 typedef struct svn_repos_node_t
2658 {
2659  /** Node type (file, dir, etc.) */
2661 
2662  /** How this node entered the node tree: 'A'dd, 'D'elete, 'R'eplace */
2663  char action;
2664 
2665  /** Were there any textual mods? (files only) */
2667 
2668  /** Where there any property mods? */
2670 
2671  /** The name of this node as it appears in its parent's entries list */
2672  const char *name;
2673 
2674  /** The filesystem revision where this was copied from (if any) */
2676 
2677  /** The filesystem path where this was copied from (if any) */
2678  const char *copyfrom_path;
2679 
2680  /** Pointer to the next sibling of this node */
2682 
2683  /** Pointer to the first child of this node */
2685 
2686  /** Pointer to the parent of this node */
2688 
2690 
2691 
2692 /** Set @a *editor and @a *edit_baton to an editor that, when driven by
2693  * a driver such as svn_repos_replay2(), builds an <tt>svn_repos_node_t *</tt>
2694  * tree representing the delta from @a base_root to @a root in @a
2695  * repos's filesystem.
2696  *
2697  * The editor can also be driven by svn_repos_dir_delta2() or
2698  * svn_repos_begin_report3(), but unless you have special needs,
2699  * svn_repos_replay2() is preferred.
2700  *
2701  * Invoke svn_repos_node_from_baton() on @a edit_baton to obtain the root
2702  * node afterwards.
2703  *
2704  * Note that the delta includes "bubbled-up" directories; that is,
2705  * many of the directory nodes will have no prop_mods.
2706  *
2707  * Allocate the tree and its contents in @a node_pool; do all other
2708  * allocation in @a pool.
2709  */
2710 svn_error_t *
2712  void **edit_baton,
2713  svn_repos_t *repos,
2714  svn_fs_root_t *base_root,
2715  svn_fs_root_t *root,
2716  apr_pool_t *node_pool,
2717  apr_pool_t *pool);
2718 
2719 /** Return the root node of the linked-list tree generated by driving the
2720  * editor (associated with @a edit_baton) created by svn_repos_node_editor().
2721  * This is only really useful if used *after* the editor drive is completed.
2722  */
2724 svn_repos_node_from_baton(void *edit_baton);
2725 
2726 /**
2727  * Return repository format information for @a repos.
2728  *
2729  * Set @a *repos_format to the repository format number of @a repos, which is
2730  * an integer that increases when incompatible changes are made (such as
2731  * by #svn_repos_upgrade2).
2732  *
2733  * Set @a *supports_version to the version number of the minimum Subversion
2734  * GA release that can read and write @a repos; allocate it in
2735  * @a result_pool. Use @a scratch_pool for temporary allocations.
2736  *
2737  * @see svn_fs_info_format, svn_repos_capabilities
2738  *
2739  * @since New in 1.9.
2740  */
2741 svn_error_t *
2742 svn_repos_info_format(int *repos_format,
2743  svn_version_t **supports_version,
2744  svn_repos_t *repos,
2745  apr_pool_t *result_pool,
2746  apr_pool_t *scratch_pool);
2747 
2748 /** @} */
2749 
2750 /* ---------------------------------------------------------------*/
2751 
2752 /**
2753  * @defgroup svn_repos_dump_load Dumping, loading and verifying filesystem data
2754  * @{
2755  *
2756  * The filesystem 'dump' format contains nothing but the abstract
2757  * structure of the filesystem -- independent of any internal node-id
2758  * schema or database back-end. All of the data in the dumpfile is
2759  * acquired by public function calls into svn_fs.h. Similarly, the
2760  * parser which reads the dumpfile is able to reconstruct the
2761  * filesystem using only public svn_fs.h routines.
2762  *
2763  * Thus the dump/load feature's main purpose is for *migrating* data
2764  * from one svn filesystem to another -- presumably two filesystems
2765  * which have different internal implementations.
2766  *
2767  * If you simply want to backup your filesystem, you're probably
2768  * better off using the built-in facilities of the DB backend (using
2769  * Berkeley DB's hot-backup feature, for example.)
2770  *
2771  * For a description of the dumpfile format, see
2772  * /trunk/notes/fs_dumprestore.txt.
2773  */
2774 
2775 /* The RFC822-style headers in our dumpfile format. */
2776 #define SVN_REPOS_DUMPFILE_MAGIC_HEADER "SVN-fs-dump-format-version"
2777 #define SVN_REPOS_DUMPFILE_FORMAT_VERSION 3
2778 #define SVN_REPOS_DUMPFILE_FORMAT_VERSION_DELTAS 3
2779 #define SVN_REPOS_DUMPFILE_UUID "UUID"
2780 #define SVN_REPOS_DUMPFILE_CONTENT_LENGTH "Content-length"
2781 
2782 #define SVN_REPOS_DUMPFILE_REVISION_NUMBER "Revision-number"
2783 
2784 #define SVN_REPOS_DUMPFILE_NODE_PATH "Node-path"
2785 #define SVN_REPOS_DUMPFILE_NODE_KIND "Node-kind"
2786 #define SVN_REPOS_DUMPFILE_NODE_ACTION "Node-action"
2787 #define SVN_REPOS_DUMPFILE_NODE_COPYFROM_PATH "Node-copyfrom-path"
2788 #define SVN_REPOS_DUMPFILE_NODE_COPYFROM_REV "Node-copyfrom-rev"
2789 /** @since New in 1.6. */
2790 #define SVN_REPOS_DUMPFILE_TEXT_COPY_SOURCE_MD5 "Text-copy-source-md5"
2791 /** @since New in 1.6. */
2792 #define SVN_REPOS_DUMPFILE_TEXT_COPY_SOURCE_SHA1 "Text-copy-source-sha1"
2793 #define SVN_REPOS_DUMPFILE_TEXT_COPY_SOURCE_CHECKSUM \
2794  SVN_REPOS_DUMPFILE_TEXT_COPY_SOURCE_MD5
2795 /** @since New in 1.6. */
2796 #define SVN_REPOS_DUMPFILE_TEXT_CONTENT_MD5 "Text-content-md5"
2797 /** @since New in 1.6. */
2798 #define SVN_REPOS_DUMPFILE_TEXT_CONTENT_SHA1 "Text-content-sha1"
2799 #define SVN_REPOS_DUMPFILE_TEXT_CONTENT_CHECKSUM \
2800  SVN_REPOS_DUMPFILE_TEXT_CONTENT_MD5
2801 
2802 #define SVN_REPOS_DUMPFILE_PROP_CONTENT_LENGTH "Prop-content-length"
2803 #define SVN_REPOS_DUMPFILE_TEXT_CONTENT_LENGTH "Text-content-length"
2804 
2805 /** @since New in 1.1. */
2806 #define SVN_REPOS_DUMPFILE_PROP_DELTA "Prop-delta"
2807 /** @since New in 1.1. */
2808 #define SVN_REPOS_DUMPFILE_TEXT_DELTA "Text-delta"
2809 /** @since New in 1.6. */
2810 #define SVN_REPOS_DUMPFILE_TEXT_DELTA_BASE_MD5 "Text-delta-base-md5"
2811 /** @since New in 1.6. */
2812 #define SVN_REPOS_DUMPFILE_TEXT_DELTA_BASE_SHA1 "Text-delta-base-sha1"
2813 /** @since New in 1.5. */
2814 #define SVN_REPOS_DUMPFILE_TEXT_DELTA_BASE_CHECKSUM \
2815  SVN_REPOS_DUMPFILE_TEXT_DELTA_BASE_MD5
2816 
2817 /** The different policies for processing the UUID in the dumpfile. */
2819 {
2820  /** only update uuid if the repos has no revisions. */
2822  /** never update uuid. */
2824  /** always update uuid. */
2826 };
2827 
2828 /**
2829  * Verify the contents of the file system in @a repos.
2830  *
2831  * Verify the revisions from @a start_rev to @a end_rev inclusive. If
2832  * @a start_rev is #SVN_INVALID_REVNUM, start at revision 0; if @a end_rev
2833  * is #SVN_INVALID_REVNUM, end at the head revision. @a start_rev must be
2834  * older than or equal to @a end_rev. If revision 0 is included in the
2835  * range, then also verify "global invariants" of the repository, as
2836  * described in svn_fs_verify().
2837  *
2838  * When a failure is found, if @a keep_going is @c TRUE then continue
2839  * verification from the next revision, otherwise stop.
2840  *
2841  * If @a check_normalization is @c TRUE, report any name collisions
2842  * within the same directory or svn:mergeinfo property where the names
2843  * differ only in character representation, but are otherwise
2844  * identical.
2845  *
2846  * If @a metadata_only is @c TRUE, backends that have a concept of separate
2847  * metadata verification will only perform that and skip the more expensive
2848  * file context reconstruction and verification. For FSFS format 7+ and
2849  * FSX, this allows for a very fast check against external corruption.
2850  *
2851  * If @a notify_func is not null, then call it with @a notify_baton and
2852  * with a notification structure in which the fields are set as follows.
2853  * (For a warning or error notification that does not apply to a specific
2854  * revision, the revision number is #SVN_INVALID_REVNUM.)
2855  *
2856  * For each FS-specific structure warning:
2857  * @c action = svn_repos_notify_verify_rev_structure
2858  * @c revision = the revision or #SVN_INVALID_REVNUM
2859  *
2860  * For a FS-specific structure failure:
2861  * @c action = #svn_repos_notify_failure
2862  * @c revision = #SVN_INVALID_REVNUM
2863  * @c err = the corresponding error chain
2864  *
2865  * For each revision verification failure:
2866  * @c action = #svn_repos_notify_failure
2867  * @c revision = the revision
2868  * @c err = the corresponding error chain
2869  *
2870  * For each revision verification warning:
2871  * @c action = #svn_repos_notify_warning
2872  * @c warning and @c warning_str fields set accordingly
2873  * ### TODO: Set @c revision = the revision?
2874  *
2875  * For each successfully verified revision:
2876  * @c action = #svn_repos_notify_verify_rev_end
2877  * @c revision = the revision
2878  *
2879  * At the end:
2880  * @c action = svn_repos_notify_verify_end
2881  * ### Do we really need a callback to tell us the function we
2882  * called has reached its end and is about to return?
2883  * ### Not sent, currently, if a FS structure error is found.
2884  *
2885  * If @a cancel_func is not @c NULL, call it periodically with @a
2886  * cancel_baton as argument to see if the caller wishes to cancel the
2887  * verification.
2888  *
2889  * Use @a scratch_pool for temporary allocation.
2890  *
2891  * Return an error if there were any failures during verification, or
2892  * #SVN_NO_ERROR if there were no failures. A failure means an event that,
2893  * if a notification callback were provided, would send a notification
2894  * with @c action = #svn_repos_notify_failure.
2895  *
2896  * @since New in 1.9.
2897  */
2898 svn_error_t *
2900  svn_revnum_t start_rev,
2901  svn_revnum_t end_rev,
2902  svn_boolean_t keep_going,
2903  svn_boolean_t check_normalization,
2904  svn_boolean_t metadata_only,
2905  svn_repos_notify_func_t notify_func,
2906  void *notify_baton,
2907  svn_cancel_func_t cancel,
2908  void *cancel_baton,
2909  apr_pool_t *scratch_pool);
2910 
2911 /**
2912  * Like svn_repos_verify_fs3(), but with @a keep_going,
2913  * @a check_normalization and @a metadata_only set to @c FALSE.
2914  *
2915  * @since New in 1.7.
2916  * @deprecated Provided for backward compatibility with the 1.8 API.
2917  */
2919 svn_error_t *
2921  svn_revnum_t start_rev,
2922  svn_revnum_t end_rev,
2923  svn_repos_notify_func_t notify_func,
2924  void *notify_baton,
2925  svn_cancel_func_t cancel,
2926  void *cancel_baton,
2927  apr_pool_t *scratch_pool);
2928 
2929 /**
2930  * Similar to svn_repos_verify_fs2(), but with a feedback_stream instead of
2931  * handling feedback via the notify_func handler.
2932  *
2933  * If @a feedback_stream is not @c NULL, write feedback to it (lines of
2934  * the form "* Verified revision %ld\n").
2935  *
2936  * @since New in 1.5.
2937  * @deprecated Provided for backward compatibility with the 1.6 API.
2938  */
2940 svn_error_t *
2942  svn_stream_t *feedback_stream,
2943  svn_revnum_t start_rev,
2944  svn_revnum_t end_rev,
2945  svn_cancel_func_t cancel_func,
2946  void *cancel_baton,
2947  apr_pool_t *pool);
2948 
2949 /**
2950  * Dump the contents of the filesystem within already-open @a repos into
2951  * writable @a dumpstream. If @a dumpstream is
2952  * @c NULL, this is effectively a primitive verify. It is not complete,
2953  * however; see instead svn_repos_verify_fs3().
2954  *
2955  * Begin at revision @a start_rev, and dump every revision up through
2956  * @a end_rev. If @a start_rev is #SVN_INVALID_REVNUM, start at revision
2957  * 0. If @a end_rev is #SVN_INVALID_REVNUM, end at the head revision.
2958  *
2959  * If @a incremental is @c TRUE, the first revision dumped will be a diff
2960  * against the previous revision (usually it looks like a full dump of
2961  * the tree).
2962  *
2963  * If @a use_deltas is @c TRUE, output only node properties which have
2964  * changed relative to the previous contents, and output text contents
2965  * as svndiff data against the previous contents. Regardless of how
2966  * this flag is set, the first revision of a non-incremental dump will
2967  * be done with full plain text. A dump with @a use_deltas set cannot
2968  * be loaded by Subversion 1.0.x.
2969  *
2970  * If @a notify_func is not null, then call it with @a notify_baton and
2971  * with a notification structure in which the fields are set as follows.
2972  * (For a warning or error notification that does not apply to a specific
2973  * revision, the revision number is #SVN_INVALID_REVNUM.)
2974  *
2975  * For each warning:
2976  * @c action = #svn_repos_notify_warning
2977  * @c warning and @c warning_str fields set accordingly
2978  * ### TODO: Set @c revision = the revision or #SVN_INVALID_REVNUM?
2979  *
2980  * For each successfully dumped revision:
2981  * @c action = #svn_repos_notify_dump_rev_end
2982  * @c revision = the revision
2983  *
2984  * At the end:
2985  * @c action = svn_repos_notify_verify_end
2986  * ### Do we really need a callback to tell us the function we
2987  * called has reached its end and is about to return?
2988  *
2989  * At the end, if there were certain warnings previously:
2990  * @c action = #svn_repos_notify_warning
2991  * @c warning and @c warning_str fields set accordingly,
2992  * reiterating the existence of previous warnings
2993  * ### This is a presentation issue. Caller could do this itself.
2994  *
2995  * If @a cancel_func is not @c NULL, it is called periodically with
2996  * @a cancel_baton as argument to see if the client wishes to cancel
2997  * the dump.
2998  *
2999  * Use @a scratch_pool for temporary allocation.
3000  *
3001  * @since New in 1.7.
3002  */
3003 svn_error_t *
3005  svn_stream_t *dumpstream,
3006  svn_revnum_t start_rev,
3007  svn_revnum_t end_rev,
3008  svn_boolean_t incremental,
3009  svn_boolean_t use_deltas,
3010  svn_repos_notify_func_t notify_func,
3011  void *notify_baton,
3012  svn_cancel_func_t cancel_func,
3013  void *cancel_baton,
3014  apr_pool_t *scratch_pool);
3015 
3016 /**
3017  * Similar to svn_repos_dump_fs3(), but with a feedback_stream instead of
3018  * handling feedback via the notify_func handler
3019  *
3020  * @since New in 1.1.
3021  * @deprecated Provided for backward compatibility with the 1.6 API.
3022  */
3024 svn_error_t *
3026  svn_stream_t *dumpstream,
3027  svn_stream_t *feedback_stream,
3028  svn_revnum_t start_rev,
3029  svn_revnum_t end_rev,
3030  svn_boolean_t incremental,
3031  svn_boolean_t use_deltas,
3032  svn_cancel_func_t cancel_func,
3033  void *cancel_baton,
3034  apr_pool_t *pool);
3035 
3036 /**
3037  * Similar to svn_repos_dump_fs2(), but with the @a use_deltas
3038  * parameter always set to @c FALSE.
3039  *
3040  * @deprecated Provided for backward compatibility with the 1.0 API.
3041  */
3043 svn_error_t *
3045  svn_stream_t *dumpstream,
3046  svn_stream_t *feedback_stream,
3047  svn_revnum_t start_rev,
3048  svn_revnum_t end_rev,
3049  svn_boolean_t incremental,
3050  svn_cancel_func_t cancel_func,
3051  void *cancel_baton,
3052  apr_pool_t *pool);
3053 
3054 
3055 /**
3056  * Read and parse dumpfile-formatted @a dumpstream, reconstructing
3057  * filesystem revisions in already-open @a repos, handling uuids in
3058  * accordance with @a uuid_action. Use @a pool for all allocation.
3059  *
3060  * If the dumpstream contains copy history that is unavailable in the
3061  * repository, an error will be thrown.
3062  *
3063  * The repository's UUID will be updated iff
3064  * the dumpstream contains a UUID and
3065  * @a uuid_action is not equal to #svn_repos_load_uuid_ignore and
3066  * either the repository contains no revisions or
3067  * @a uuid_action is equal to #svn_repos_load_uuid_force.
3068  *
3069  * If the dumpstream contains no UUID, then @a uuid_action is
3070  * ignored and the repository UUID is not touched.
3071  *
3072  * @a start_rev and @a end_rev act as filters, the lower and upper
3073  * (inclusive) range values of revisions in @a dumpstream which will
3074  * be loaded. Either both of these values are #SVN_INVALID_REVNUM (in
3075  * which case no revision-based filtering occurs at all), or both are
3076  * valid revisions (where @a start_rev is older than or equivalent to
3077  * @a end_rev).
3078  *
3079  * If @a parent_dir is not NULL, then the parser will reparent all the
3080  * loaded nodes, from root to @a parent_dir. The directory @a parent_dir
3081  * must be an existing directory in the repository.
3082  *
3083  * If @a use_pre_commit_hook is set, call the repository's pre-commit
3084  * hook before committing each loaded revision.
3085  *
3086  * If @a use_post_commit_hook is set, call the repository's
3087  * post-commit hook after committing each loaded revision.
3088  *
3089  * If @a validate_props is set, then validate Subversion revision and
3090  * node properties (those in the svn: namespace) against established
3091  * rules for those things.
3092  *
3093  * If @a ignore_dates is set, ignore any revision datestamps found in
3094  * @a dumpstream, allowing the revisions created by the load process
3095  * to be stamped as if they were newly created via the normal commit
3096  * process.
3097  *
3098  * If non-NULL, use @a notify_func and @a notify_baton to send notification
3099  * of events to the caller.
3100  *
3101  * If @a cancel_func is not @c NULL, it is called periodically with
3102  * @a cancel_baton as argument to see if the client wishes to cancel
3103  * the load.
3104  *
3105  * @since New in 1.9.
3106  */
3107 svn_error_t *
3109  svn_stream_t *dumpstream,
3110  svn_revnum_t start_rev,
3111  svn_revnum_t end_rev,
3112  enum svn_repos_load_uuid uuid_action,
3113  const char *parent_dir,
3114  svn_boolean_t use_pre_commit_hook,
3115  svn_boolean_t use_post_commit_hook,
3116  svn_boolean_t validate_props,
3117  svn_boolean_t ignore_dates,
3118  svn_repos_notify_func_t notify_func,
3119  void *notify_baton,
3120  svn_cancel_func_t cancel_func,
3121  void *cancel_baton,
3122  apr_pool_t *pool);
3123 
3124 /** Similar to svn_repos_load_fs5(), but with @a ignore_dates
3125  * always passed as FALSE.
3126  *
3127  * @since New in 1.8.
3128  * @deprecated Provided for backward compatibility with the 1.8 API.
3129  */
3131 svn_error_t *
3133  svn_stream_t *dumpstream,
3134  svn_revnum_t start_rev,
3135  svn_revnum_t end_rev,
3136  enum svn_repos_load_uuid uuid_action,
3137  const char *parent_dir,
3138  svn_boolean_t use_pre_commit_hook,
3139  svn_boolean_t use_post_commit_hook,
3140  svn_boolean_t validate_props,
3141  svn_repos_notify_func_t notify_func,
3142  void *notify_baton,
3143  svn_cancel_func_t cancel_func,
3144  void *cancel_baton,
3145  apr_pool_t *pool);
3146 
3147 /** Similar to svn_repos_load_fs4(), but with @a start_rev and @a
3148  * end_rev always passed as #SVN_INVALID_REVNUM.
3149  *
3150  * @since New in 1.7.
3151  * @deprecated Provided for backward compatibility with the 1.7 API.
3152  */
3154 svn_error_t *
3156  svn_stream_t *dumpstream,
3157  enum svn_repos_load_uuid uuid_action,
3158  const char *parent_dir,
3159  svn_boolean_t use_pre_commit_hook,
3160  svn_boolean_t use_post_commit_hook,
3161  svn_boolean_t validate_props,
3162  svn_repos_notify_func_t notify_func,
3163  void *notify_baton,
3164  svn_cancel_func_t cancel_func,
3165  void *cancel_baton,
3166  apr_pool_t *pool);
3167 
3168 /**
3169  * Similar to svn_repos_load_fs3(), but with @a feedback_stream in
3170  * place of the #svn_repos_notify_func_t and baton and with
3171  * @a validate_props always FALSE.
3172  *
3173  * @since New in 1.2.
3174  * @deprecated Provided for backward compatibility with the 1.6 API.
3175  */
3177 svn_error_t *
3179  svn_stream_t *dumpstream,
3180  svn_stream_t *feedback_stream,
3181  enum svn_repos_load_uuid uuid_action,
3182  const char *parent_dir,
3183  svn_boolean_t use_pre_commit_hook,
3184  svn_boolean_t use_post_commit_hook,
3185  svn_cancel_func_t cancel_func,
3186  void *cancel_baton,
3187  apr_pool_t *pool);
3188 
3189 /**
3190  * Similar to svn_repos_load_fs2(), but with @a use_pre_commit_hook and
3191  * @a use_post_commit_hook always @c FALSE.
3192  *
3193  * @deprecated Provided for backward compatibility with the 1.1 API.
3194  */
3196 svn_error_t *
3198  svn_stream_t *dumpstream,
3199  svn_stream_t *feedback_stream,
3200  enum svn_repos_load_uuid uuid_action,
3201  const char *parent_dir,
3202  svn_cancel_func_t cancel_func,
3203  void *cancel_baton,
3204  apr_pool_t *pool);
3205 
3206 
3207 /**
3208  * A vtable that is driven by svn_repos_parse_dumpstream3().
3209  *
3210  * @since New in 1.8.
3211  */
3213 {
3214  /** The parser has discovered a new "magic header" record within the
3215  * parsing session represented by @a parse_baton. The dump-format
3216  * version number is @a version.
3217  */
3218  svn_error_t *(*magic_header_record)(int version,
3219  void *parse_baton,
3220  apr_pool_t *pool);
3221 
3222  /** The parser has discovered a new uuid record within the parsing
3223  * session represented by @a parse_baton. The uuid's value is
3224  * @a uuid, and it is allocated in @a pool.
3225  */
3226  svn_error_t *(*uuid_record)(const char *uuid,
3227  void *parse_baton,
3228  apr_pool_t *pool);
3229 
3230  /** The parser has discovered a new revision record within the
3231  * parsing session represented by @a parse_baton. All the headers are
3232  * placed in @a headers (allocated in @a pool), which maps <tt>const
3233  * char *</tt> header-name ==> <tt>const char *</tt> header-value.
3234  * The @a revision_baton received back (also allocated in @a pool)
3235  * represents the revision.
3236  */
3237  svn_error_t *(*new_revision_record)(void **revision_baton,
3238  apr_hash_t *headers,
3239  void *parse_baton,
3240  apr_pool_t *pool);
3241 
3242  /** The parser has discovered a new node record within the current
3243  * revision represented by @a revision_baton. All the headers are
3244  * placed in @a headers (as with @c new_revision_record), allocated in
3245  * @a pool. The @a node_baton received back is allocated in @a pool
3246  * and represents the node.
3247  */
3248  svn_error_t *(*new_node_record)(void **node_baton,
3249  apr_hash_t *headers,
3250  void *revision_baton,
3251  apr_pool_t *pool);
3252 
3253  /** For a given @a revision_baton, set a property @a name to @a value. */
3254  svn_error_t *(*set_revision_property)(void *revision_baton,
3255  const char *name,
3256  const svn_string_t *value);
3257 
3258  /** For a given @a node_baton, set a property @a name to @a value. */
3259  svn_error_t *(*set_node_property)(void *node_baton,
3260  const char *name,
3261  const svn_string_t *value);
3262 
3263  /** For a given @a node_baton, delete property @a name. */
3264  svn_error_t *(*delete_node_property)(void *node_baton, const char *name);
3265 
3266  /** For a given @a node_baton, remove all properties. */
3267  svn_error_t *(*remove_node_props)(void *node_baton);
3268 
3269  /** For a given @a node_baton, set @a stream to a writable stream
3270  * capable of receiving the node's fulltext. The parser will write
3271  * the fulltext to the stream and then close the stream to signal
3272  * completion.
3273  *
3274  * If a @c NULL is returned instead of a stream, the vtable is
3275  * indicating that no text is desired, and the parser will not
3276  * attempt to send it.
3277  */
3278  svn_error_t *(*set_fulltext)(svn_stream_t **stream,
3279  void *node_baton);
3280 
3281  /** For a given @a node_baton, set @a handler and @a handler_baton
3282  * to a window handler and baton capable of receiving a delta
3283  * against the node's previous contents. The parser will send all
3284  * the windows of data to this handler, and will then send a NULL
3285  * window to signal completion.
3286  *
3287  * If a @c NULL is returned instead of a handler, the vtable is
3288  * indicating that no delta is desired, and the parser will not
3289  * attempt to send it.
3290  */
3291  svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *handler,
3292  void **handler_baton,
3293  void *node_baton);
3294 
3295  /** The parser has reached the end of the current node represented by
3296  * @a node_baton, it can be freed.
3297  */
3298  svn_error_t *(*close_node)(void *node_baton);
3299 
3300  /** The parser has reached the end of the current revision
3301  * represented by @a revision_baton. In other words, there are no more
3302  * changed nodes within the revision. The baton can be freed.
3303  */
3304  svn_error_t *(*close_revision)(void *revision_baton);
3305 
3307 
3308 
3309 /**
3310  * Read and parse dumpfile-formatted @a stream, calling callbacks in
3311  * @a parse_fns/@a parse_baton, and using @a pool for allocations.
3312  *
3313  * If @a deltas_are_text is @c TRUE, handle text-deltas with the @a
3314  * set_fulltext callback. This is useful when manipulating a dump
3315  * stream without loading it. Otherwise handle text-deltas with the
3316  * @a apply_textdelta callback.
3317  *
3318  * If @a cancel_func is not @c NULL, it is called periodically with
3319  * @a cancel_baton as argument to see if the client wishes to cancel
3320  * the dump.
3321  *
3322  * This parser has built-in knowledge of the dumpfile format, but only
3323  * in a limited sense:
3324  *
3325  * * it recognizes the "magic" format-version header.
3326  *
3327  * * it recognizes the UUID header.
3328  *
3329  * * it recognizes revision and node records by looking for either
3330  * a REVISION_NUMBER or NODE_PATH headers.
3331  *
3332  * * it recognizes the CONTENT-LENGTH headers, so it knows if and
3333  * how to suck up the content body.
3334  *
3335  * * it knows how to parse a content body into two parts: props
3336  * and text, and pass the pieces to the vtable.
3337  *
3338  * This is enough knowledge to make it easy on vtable implementors,
3339  * but still allow expansion of the format: most headers do not have
3340  * to be handled explicitly.
3341  *
3342  * ### [JAF] Wouldn't it be more efficient to support a start/end rev
3343  * range here than only supporting it in receivers such as
3344  * svn_repos_get_fs_build_parser4()? This parser could then skip over
3345  * chunks of the input stream before the oldest required rev, and
3346  * could stop reading entirely after the youngest required rev.
3347  *
3348  * @since New in 1.8.
3349  */
3350 svn_error_t *
3352  const svn_repos_parse_fns3_t *parse_fns,
3353  void *parse_baton,
3354  svn_boolean_t deltas_are_text,
3355  svn_cancel_func_t cancel_func,
3356  void *cancel_baton,
3357  apr_pool_t *pool);
3358 
3359 
3360 /**
3361  * Set @a *parser and @a *parse_baton to a vtable parser which commits new
3362  * revisions to the fs in @a repos. The constructed parser will treat
3363  * UUID records in a manner consistent with @a uuid_action. Use @a pool
3364  * to operate on the fs.
3365  *
3366  * @a start_rev and @a end_rev act as filters, the lower and upper
3367  * (inclusive) range values of revisions which will
3368  * be loaded. Either both of these values are #SVN_INVALID_REVNUM (in
3369  * which case no revision-based filtering occurs at all), or both are
3370  * valid revisions (where @a start_rev is older than or equivalent to
3371  * @a end_rev). They refer to dump stream revision numbers rather than
3372  * committed revision numbers.
3373  *
3374  * If @a use_history is true, then when the parser encounters a node that
3375  * is added-with-history, it will require 'copy-from' history to exist in
3376  * the repository at the relative (adjusted) copy-from revision and path.
3377  * It will perform a copy from that source location, and will fail if no
3378  * suitable source exists there. If @a use_history is false, then it will
3379  * instead convert every copy to a plain add.
3380  *
3381  * ### The 'use_history=FALSE' case is unused and untested in Subversion.
3382  * It seems to me it would not work with a deltas dumpfile (a driver
3383  * that calls the @c apply_textdelta method), as it would not have
3384  * access to the delta base text.
3385  *
3386  * If @a use_pre_commit_hook is set, call the repository's pre-commit
3387  * hook before committing each loaded revision.
3388  *
3389  * If @a use_post_commit_hook is set, call the repository's
3390  * post-commit hook after committing each loaded revision.
3391  *
3392  * If @a validate_props is set, then validate Subversion revision and
3393  * node properties (those in the svn: namespace) against established
3394  * rules for those things.
3395  *
3396  * If @a ignore_dates is set, ignore any revision datestamps found in
3397  * @a dumpstream, allowing the revisions created by the load process
3398  * to be stamped as if they were newly created via the normal commit
3399  * process.
3400  *
3401  * If @a parent_dir is not NULL, then the parser will reparent all the
3402  * loaded nodes, from root to @a parent_dir. The directory @a parent_dir
3403  * must be an existing directory in the repository.
3404  *
3405  * @since New in 1.9.
3406  */
3407 svn_error_t *
3409  void **parse_baton,
3410  svn_repos_t *repos,
3411  svn_revnum_t start_rev,
3412  svn_revnum_t end_rev,
3413  svn_boolean_t use_history,
3414  svn_boolean_t validate_props,
3415  enum svn_repos_load_uuid uuid_action,
3416  const char *parent_dir,
3417  svn_boolean_t use_pre_commit_hook,
3418  svn_boolean_t use_post_commit_hook,
3419  svn_boolean_t ignore_dates,
3420  svn_repos_notify_func_t notify_func,
3421  void *notify_baton,
3422  apr_pool_t *pool);
3423 
3424 /**
3425  * Similar to svn_repos_get_fs_build_parser5(), but with the
3426  * @c use_pre_commit_hook, @c use_post_commit_hook and @c ignore_dates
3427  * arguments all false.
3428  *
3429  * @since New in 1.8.
3430  * @deprecated Provided for backward compatibility with the 1.8 API.
3431  */
3433 svn_error_t *
3435  void **parse_baton,
3436  svn_repos_t *repos,
3437  svn_revnum_t start_rev,
3438  svn_revnum_t end_rev,
3439  svn_boolean_t use_history,
3440  svn_boolean_t validate_props,
3441  enum svn_repos_load_uuid uuid_action,
3442  const char *parent_dir,
3443  svn_repos_notify_func_t notify_func,
3444  void *notify_baton,
3445  apr_pool_t *pool);
3446 
3447 
3448 
3449 /**
3450  * A vtable that is driven by svn_repos_parse_dumpstream2().
3451  * Similar to #svn_repos_parse_fns3_t except that it lacks
3452  * the magic_header_record callback.
3453  *
3454  * @deprecated Provided for backward compatibility with the 1.7 API.
3455  */
3457 {
3458  /** Same as #svn_repos_parse_fns3_t.new_revision_record. */
3459  svn_error_t *(*new_revision_record)(void **revision_baton,
3460  apr_hash_t *headers,
3461  void *parse_baton,
3462  apr_pool_t *pool);
3463  /** Same as #svn_repos_parse_fns3_t.uuid_record. */
3464  svn_error_t *(*uuid_record)(const char *uuid,
3465  void *parse_baton,
3466  apr_pool_t *pool);
3467  /** Same as #svn_repos_parse_fns3_t.new_node_record. */
3468  svn_error_t *(*new_node_record)(void **node_baton,
3469  apr_hash_t *headers,
3470  void *revision_baton,
3471  apr_pool_t *pool);
3472  /** Same as #svn_repos_parse_fns3_t.set_revision_property. */
3473  svn_error_t *(*set_revision_property)(void *revision_baton,
3474  const char *name,
3475  const svn_string_t *value);
3476  /** Same as #svn_repos_parse_fns3_t.set_node_property. */
3477  svn_error_t *(*set_node_property)(void *node_baton,
3478  const char *name,
3479  const svn_string_t *value);
3480  /** Same as #svn_repos_parse_fns3_t.delete_node_property. */
3481  svn_error_t *(*delete_node_property)(void *node_baton,
3482  const char *name);
3483  /** Same as #svn_repos_parse_fns3_t.remove_node_props. */
3484  svn_error_t *(*remove_node_props)(void *node_baton);
3485  /** Same as #svn_repos_parse_fns3_t.set_fulltext. */
3486  svn_error_t *(*set_fulltext)(svn_stream_t **stream,
3487  void *node_baton);
3488  /** Same as #svn_repos_parse_fns3_t.apply_textdelta. */
3489  svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *handler,
3490  void **handler_baton,
3491  void *node_baton);
3492  /** Same as #svn_repos_parse_fns3_t.close_node. */
3493  svn_error_t *(*close_node)(void *node_baton);
3494  /** Same as #svn_repos_parse_fns3_t.close_revision. */
3495  svn_error_t *(*close_revision)(void *revision_baton);
3497 
3498 /** @deprecated Provided for backward compatibility with the 1.7 API. */
3500 
3501 
3502 /**
3503  * A vtable that is driven by svn_repos_parse_dumpstream().
3504  * Similar to #svn_repos_parse_fns2_t except that it lacks
3505  * the delete_node_property and apply_textdelta callbacks.
3506  *
3507  * @deprecated Provided for backward compatibility with the 1.0 API.
3508  */
3510 {
3511  /** Same as #svn_repos_parse_fns2_t.new_revision_record. */
3512  svn_error_t *(*new_revision_record)(void **revision_baton,
3513  apr_hash_t *headers,
3514  void *parse_baton,
3515  apr_pool_t *pool);
3516  /** Same as #svn_repos_parse_fns2_t.uuid_record. */
3517  svn_error_t *(*uuid_record)(const char *uuid,
3518  void *parse_baton,
3519  apr_pool_t *pool);
3520  /** Same as #svn_repos_parse_fns2_t.new_node_record. */
3521  svn_error_t *(*new_node_record)(void **node_baton,
3522  apr_hash_t *headers,
3523  void *revision_baton,
3524  apr_pool_t *pool);
3525  /** Same as #svn_repos_parse_fns2_t.set_revision_property. */
3526  svn_error_t *(*set_revision_property)(void *revision_baton,
3527  const char *name,
3528  const svn_string_t *value);
3529  /** Same as #svn_repos_parse_fns2_t.set_node_property. */
3530  svn_error_t *(*set_node_property)(void *node_baton,
3531  const char *name,
3532  const svn_string_t *value);
3533  /** Same as #svn_repos_parse_fns2_t.remove_node_props. */
3534  svn_error_t *(*remove_node_props)(void *node_baton);
3535  /** Same as #svn_repos_parse_fns2_t.set_fulltext. */
3536  svn_error_t *(*set_fulltext)(svn_stream_t **stream,
3537  void *node_baton);
3538  /** Same as #svn_repos_parse_fns2_t.close_node. */
3539  svn_error_t *(*close_node)(void *node_baton);
3540  /** Same as #svn_repos_parse_fns2_t.close_revision. */
3541  svn_error_t *(*close_revision)(void *revision_baton);
3543 
3544 
3545 /**
3546  * Similar to svn_repos_parse_dumpstream3(), but uses the more limited
3547  * #svn_repos_parser_fns2_t vtable type.
3548  *
3549  * @deprecated Provided for backward compatibility with the 1.7 API.
3550  */
3552 svn_error_t *
3554  const svn_repos_parser_fns2_t *parse_fns,
3555  void *parse_baton,
3556  svn_cancel_func_t cancel_func,
3557  void *cancel_baton,
3558  apr_pool_t *pool);
3559 
3560 /**
3561  * Similar to svn_repos_parse_dumpstream2(), but uses the more limited
3562  * #svn_repos_parser_fns_t vtable type.
3563  *
3564  * @deprecated Provided for backward compatibility with the 1.0 API.
3565  */
3567 svn_error_t *
3569  const svn_repos_parser_fns_t *parse_fns,
3570  void *parse_baton,
3571  svn_cancel_func_t cancel_func,
3572  void *cancel_baton,
3573  apr_pool_t *pool);
3574 
3575 /**
3576  * Similar to svn_repos_get_fs_build_parser4(), but with @a start_rev
3577  * and @a end_rev always passed as #SVN_INVALID_REVNUM, and yielding
3578  * the more limited svn_repos_parse_fns2_t.
3579  *
3580  * @since New in 1.7.
3581  * @deprecated Provided for backward compatibility with the 1.7 API.
3582  */
3584 svn_error_t *
3586  void **parse_baton,
3587  svn_repos_t *repos,
3588  svn_boolean_t use_history,
3589  svn_boolean_t validate_props,
3590  enum svn_repos_load_uuid uuid_action,
3591  const char *parent_dir,
3592  svn_repos_notify_func_t notify_func,
3593  void *notify_baton,
3594  apr_pool_t *pool);
3595 
3596 /**
3597  * Similar to svn_repos_get_fs_build_parser3(), but with @a outstream
3598  * in place if a #svn_repos_notify_func_t and baton and with
3599  * @a validate_props always FALSE.
3600  *
3601  * @since New in 1.1.
3602  * @deprecated Provided for backward compatibility with the 1.6 API.
3603  */
3605 svn_error_t *
3607  void **parse_baton,
3608  svn_repos_t *repos,
3609  svn_boolean_t use_history,
3610  enum svn_repos_load_uuid uuid_action,
3611  svn_stream_t *outstream,
3612  const char *parent_dir,
3613  apr_pool_t *pool);
3614 
3615 /**
3616  * Similar to svn_repos_get_fs_build_parser2(), but yields the more
3617  * limited svn_repos_parser_fns_t vtable type.
3618  *
3619  * @deprecated Provided for backward compatibility with the 1.0 API.
3620  */
3622 svn_error_t *
3624  void **parse_baton,
3625  svn_repos_t *repos,
3626  svn_boolean_t use_history,
3627  enum svn_repos_load_uuid uuid_action,
3628  svn_stream_t *outstream,
3629  const char *parent_dir,
3630  apr_pool_t *pool);
3631 
3632 
3633 /** @} */
3634 
3635 /** A data type which stores the authz information.
3636  *
3637  * @since New in 1.3.
3638  */
3639 typedef struct svn_authz_t svn_authz_t;
3640 
3641 /**
3642  * Read authz configuration data from @a path (a dirent, an absolute file url
3643  * or a registry path) into @a *authz_p, allocated in @a pool.
3644  *
3645  * If @a groups_path (a dirent, an absolute file url, or a registry path) is
3646  * set, use the global groups parsed from it.
3647  *
3648  * If @a path or @a groups_path is not a valid authz rule file, then return
3649  * #SVN_ERR_AUTHZ_INVALID_CONFIG. The contents of @a *authz_p is then
3650  * undefined. If @a must_exist is TRUE, a missing authz or groups file
3651  * is also an error other than #SVN_ERR_AUTHZ_INVALID_CONFIG (exact error
3652  * depends on the access type).
3653  *
3654  * @since New in 1.8.
3655  */
3656 svn_error_t *
3658  const char *path,
3659  const char *groups_path,
3660  svn_boolean_t must_exist,
3661  apr_pool_t *pool);
3662 
3663 
3664 /**
3665  * Similar to svn_repos_authz_read2(), but with @a groups_path and @a
3666  * repos_root always passed as @c NULL.
3667  *
3668  * @since New in 1.3.
3669  * @deprecated Provided for backward compatibility with the 1.7 API.
3670  */
3672 svn_error_t *
3674  const char *file,
3675  svn_boolean_t must_exist,
3676  apr_pool_t *pool);
3677 
3678 /**
3679  * Read authz configuration data from @a stream into @a *authz_p,
3680  * allocated in @a pool.
3681  *
3682  * If @a groups_stream is set, use the global groups parsed from it.
3683  *
3684  * @since New in 1.8.
3685  */
3686 svn_error_t *
3688  svn_stream_t *stream,
3689  svn_stream_t *groups_stream,
3690  apr_pool_t *pool);
3691 
3692 /**
3693  * Check whether @a user can access @a path in the repository @a
3694  * repos_name with the @a required_access. @a authz lists the ACLs to
3695  * check against. Set @a *access_granted to indicate if the requested
3696  * access is granted.
3697  *
3698  * If @a path is NULL, then check whether @a user has the @a
3699  * required_access anywhere in the repository. Set @a *access_granted
3700  * to TRUE if at least one path is accessible with the @a
3701  * required_access.
3702  *
3703  * For compatibility with 1.6, and earlier, @a repos_name can be NULL
3704  * in which case it is equivalent to a @a repos_name of "".
3705  *
3706  * @note Presently, @a repos_name must byte-for-byte match the repos_name
3707  * specified in the authz file; it is treated as an opaque string, and not
3708  * as a dirent.
3709  *
3710  * @since New in 1.3.
3711  */
3712 svn_error_t *
3714  const char *repos_name,
3715  const char *path,
3716  const char *user,
3717  svn_repos_authz_access_t required_access,
3718  svn_boolean_t *access_granted,
3719  apr_pool_t *pool);
3720 
3721 
3722 
3723 /** Revision Access Levels
3724  *
3725  * Like most version control systems, access to versioned objects in
3726  * Subversion is determined on primarily path-based system. Users either
3727  * do or don't have the ability to read a given path.
3728  *
3729  * However, unlike many version control systems where versioned objects
3730  * maintain their own distinct version information (revision numbers,
3731  * authors, log messages, change timestamps, etc.), Subversion binds
3732  * multiple paths changed as part of a single commit operation into a
3733  * set, calls the whole thing a revision, and hangs commit metadata
3734  * (author, date, log message, etc.) off of that revision. So, commit
3735  * metadata is shared across all the paths changed as part of a given
3736  * commit operation.
3737  *
3738  * It is common (or, at least, we hope it is) for log messages to give
3739  * detailed information about changes made in the commit to which the log
3740  * message is attached. Such information might include a mention of all
3741  * the files changed, what was changed in them, and so on. But this
3742  * causes a problem when presenting information to readers who aren't
3743  * authorized to read every path in the repository. Simply knowing that
3744  * a given path exists may be a security leak, even if the user can't see
3745  * the contents of the data located at that path.
3746  *
3747  * So Subversion does what it reasonably can to prevent the leak of this
3748  * information, and does so via a staged revision access policy. A
3749  * reader can be said to have one of three levels of access to a given
3750  * revision's metadata, based solely on the reader's access rights to the
3751  * paths changed or copied in that revision:
3752  *
3753  * 'full access' -- Granted when the reader has access to all paths
3754  * changed or copied in the revision, or when no paths were
3755  * changed in the revision at all, this access level permits
3756  * full visibility of all revision property names and values,
3757  * and the full changed-paths information.
3758  *
3759  * 'no access' -- Granted when the reader does not have access to any
3760  * paths changed or copied in the revision, this access level
3761  * denies the reader access to all revision properties and all
3762  * changed-paths information.
3763  *
3764  * 'partial access' -- Granted when the reader has access to at least
3765  * one, but not all, of the paths changed or copied in the revision,
3766  * this access level permits visibility of the svn:date and
3767  * svn:author revision properties and only the paths of the
3768  * changed-paths information to which the reader has access.
3769  *
3770  */
3771 
3772 
3773 /** An enum defining levels of revision access.
3774  *
3775  * @since New in 1.5.
3776  */
3778 {
3779  /** no access allowed to the revision properties and all changed-paths
3780  * information. */
3782  /** access granted to some (svn:date and svn:author) revision properties and
3783  * changed-paths information on paths the read has access to. */
3785  /** access granted to all revision properites and changed-paths
3786  * information. */
3788 }
3790 
3791 
3792 /**
3793  * Set @a access to the access level granted for @a revision in @a
3794  * repos, as determined by consulting the @a authz_read_func callback
3795  * function and its associated @a authz_read_baton.
3796  *
3797  * @a authz_read_func may be @c NULL, in which case @a access will be
3798  * set to #svn_repos_revision_access_full.
3799  *
3800  * @since New in 1.5.
3801  */
3802 svn_error_t *
3804  svn_repos_t *repos,
3805  svn_revnum_t revision,
3806  svn_repos_authz_func_t authz_read_func,
3807  void *authz_read_baton,
3808  apr_pool_t *pool);
3809 
3810 
3811 #ifdef __cplusplus
3812 }
3813 #endif /* __cplusplus */
3814 
3815 #endif /* SVN_REPOS_H */