Main Page | Modules | Data Structures | File List | Data Fields | Globals

svn_fs.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_fs.h
00019  * @brief Interface to the Subversion filesystem.
00020  */
00021 
00022 
00023 #ifndef SVN_FS_H
00024 #define SVN_FS_H
00025 
00026 #include <apr_pools.h>
00027 #include <apr_hash.h>
00028 #include <apr_tables.h>
00029 #include "svn_types.h"
00030 #include "svn_error.h"
00031 #include "svn_delta.h"
00032 #include "svn_io.h"
00033 
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif /* __cplusplus */
00038 
00039 
00040 /* Opening and creating filesystems.  */
00041 
00042 
00043 /** An object representing a Subversion filesystem.  */
00044 typedef struct svn_fs_t svn_fs_t;
00045 
00046 
00047 /** Filesystem configuration options. */
00048 #define SVN_FS_CONFIG_BDB_TXN_NOSYNC            "bdb-txn-nosync"
00049 #define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE        "bdb-log-autoremove"
00050 
00051 
00052 /** Create a new filesystem object in @a pool.
00053  *
00054  * It doesn't refer to any actual repository yet; you need to invoke
00055  * @c svn_fs_open_* or @c svn_fs_create_* on it for that to happen. If
00056  * @a fs_config is not @c NULL, the options it contains modify the
00057  * behaviour of the filesystem. The interpretation of @a fs_config is
00058  * specific to the filesystem back-end.
00059  *
00060  * @note The lifetime of @a fs_config must not be shorter than @a
00061  * pool's. It's a good idea to allocate @a fs_config from @a pool or
00062  * one of its ancestors.
00063  *
00064  * @note You probably don't want to use this directly, especially not
00065  * if it's followed immediately by a call to @c svn_fs_open_berkeley().
00066  * Take a look at @c svn_repos_open() instead.
00067  */
00068 svn_fs_t *svn_fs_new (apr_hash_t *fs_config, apr_pool_t *pool);
00069 
00070 
00071 /** The type of a warning callback function.  @a baton is the value specified
00072  * in the call to @c svn_fs_set_warning_func; the filesystem passes it through
00073  * to the callback.  @a err contains the warning message.
00074  *
00075  * The callback function should not clear the error that is passed to it;
00076  * its caller should do that.
00077  */
00078 typedef void (*svn_fs_warning_callback_t) (void *baton, svn_error_t *err);
00079 
00080 
00081 /** Provide a callback function, @a warning, that @a fs should use to 
00082  * report (non-fatal) errors.  To print an error, the filesystem will call
00083  * @a warning, passing it @a warning_baton and the error.
00084  *
00085  * By default, this is set to a function that will crash the process.
00086  * Dumping to @c stderr or <tt>/dev/tty</tt> is not acceptable default 
00087  * behavior for server processes, since those may both be equivalent to
00088  * <tt>/dev/null</tt>.
00089  */
00090 void svn_fs_set_warning_func (svn_fs_t *fs,
00091                               svn_fs_warning_callback_t warning,
00092                               void *warning_baton);
00093 
00094 
00095 
00096 /** Subversion filesystems based on Berkeley DB.
00097  * 
00098  * There are many possible ways to implement the Subversion filesystem
00099  * interface.  You could implement it directly using ordinary POSIX
00100  * filesystem operations; you could build it using an SQL server as a
00101  * back end; you could build it on RCS; and so on.
00102  *
00103  * The functions on this page create filesystem objects that use
00104  * Berkeley DB (http://www.sleepycat.com) to store their data.
00105  * Berkeley DB supports transactions and recoverability, making it
00106  * well-suited for Subversion.
00107  *
00108  * A Berkeley DB ``environment'' is a Unix directory containing
00109  * database files, log files, backing files for shared memory buffers,
00110  * and so on --- everything necessary for a complex database
00111  * application.  Each Subversion filesystem lives in a single Berkeley
00112  * DB environment.
00113  *
00114  * @defgroup svn_fs_bdb berkeley db filesystems
00115  * @{
00116  */
00117 
00118 /** Create a new, empty Subversion filesystem, stored in a Berkeley DB
00119  * environment under @a path, a utf8-encoded path.  Make @a fs refer to 
00120  * this new filesystem.  @a fs provides the memory pool, warning function,
00121  * etc.  If @a path exists, it must be an empty directory.
00122  */
00123 svn_error_t *svn_fs_create_berkeley (svn_fs_t *fs, const char *path);
00124 
00125 
00126 /** Make @a fs refer to the Berkeley DB-based Subversion filesystem at
00127  * @a path.  @a path is utf8-encoded, and must refer to a file or directory
00128  * created by @c svn_fs_create_berkeley.
00129  *
00130  * Only one thread may operate on any given filesystem object at once.
00131  * Two threads may access the same filesystem simultaneously only if
00132  * they open separate filesystem objects.  
00133  *
00134  * NOTE: you probably don't want to use this directly, especially not
00135  * if it's immediately preceded by a call to @c svn_fs_new().  Take a
00136  * look at @c svn_repos_open() instead.
00137  */
00138 svn_error_t *svn_fs_open_berkeley (svn_fs_t *fs, const char *path);
00139 
00140 
00141 /** Return the utf8-encoded path to @a fs's repository, allocated in
00142  * @a pool.  Note: this is just what was passed to
00143  * @c svn_fs_create_berkeley() or @a svn_fs_open_berkeley() -- might be
00144  * absolute, might not.
00145  */
00146 const char *svn_fs_berkeley_path (svn_fs_t *fs, apr_pool_t *pool);
00147 
00148 
00149 /** Register an error handling function for Berkeley DB error messages.
00150  * If a Berkeley DB error occurs, the filesystem will call @a handler
00151  * with two strings: an error message prefix, which will be zero, and
00152  * an error message.  @a handler should print it out, log it somewhere,
00153  * etc.
00154  *
00155  * Since Berkeley DB's error messages are sometimes much more
00156  * informative than the error codes the functions return, it's worth
00157  * calling this function and providing some kind of error message
00158  * handler.
00159  *
00160  * This function calls @c DBENV->set_errcall, with @a handler as the
00161  * @c db_errcall_fcn argument.
00162  */
00163 svn_error_t *svn_fs_set_berkeley_errcall (svn_fs_t *fs, 
00164                                           void (*handler) (const char *errpfx,
00165                                                            char *msg));
00166 
00167 /** Delete the Berkeley DB-based filesystem @a path.  This deletes the
00168  * database files, log files, shared memory segments, etc.  @a path should
00169  * refer to a file or directory created by @c svn_fs_create_berkeley.
00170  */
00171 svn_error_t *svn_fs_delete_berkeley (const char *path, apr_pool_t *pool);
00172 
00173 
00174 /** Hot copy Subversion filesystem, stored in a Berkeley DB environment under 
00175  * @a src_path to @a dest_path. If @a clean_logs is used is @c TRUE, 
00176  * delete copied, unused log files from source repository at @a src_path
00177  * Using @a pool for any necessary memory allocations.
00178  */
00179 svn_error_t *svn_fs_hotcopy_berkeley (const char *src_path, 
00180                                       const char *dest_path, 
00181                                       svn_boolean_t clean_logs,
00182                                       apr_pool_t *pool);
00183 
00184 /** Perform any necessary non-catastrophic recovery on a Berkeley
00185  * DB-based Subversion filesystem, stored in the environment @a path.
00186  * Do any necessary allocation within @a pool.
00187  *
00188  * After an unexpected server exit, due to a server crash or a system
00189  * crash, a Subversion filesystem based on Berkeley DB needs to run
00190  * recovery procedures to bring the database back into a consistent
00191  * state and release any locks that were held by the deceased process.
00192  * The recovery procedures require exclusive access to the database
00193  * --- while they execute, no other process or thread may access the
00194  * database.
00195  *
00196  * In a server with multiple worker processes, like Apache, if a
00197  * worker process accessing the filesystem dies, you must stop the
00198  * other worker processes, and run recovery.  Then, the other worker
00199  * processes can re-open the database and resume work.
00200  *
00201  * If the server exited cleanly, there is no need to run recovery, but
00202  * there is no harm in it, either, and it take very little time.  So
00203  * it's a fine idea to run recovery when the server process starts,
00204  * before it begins handling any requests.
00205  */
00206 svn_error_t *svn_fs_berkeley_recover (const char *path,
00207                                       apr_pool_t *pool);
00208 
00209 
00210 /** Set @a *logfiles to array of <tt>const char *</tt> log file names
00211  * of Berkeley DB-based Subversion filesystem.
00212  *
00213  * If @a only_unused is used is @c TRUE, @a *logfiles will contain
00214  * only the names of Berkeley DB log files still in use by the
00215  * filesystem.  Otherwise, all log files (used and unused) are returned.
00216  *
00217  * This function wraps the Berkeley DB 'log_archive' function
00218  * called by the db_archive binary.  Repository administrators may
00219  * want to run this function periodically and delete the unused log
00220  * files, as a way of reclaiming disk space.
00221  */
00222 svn_error_t *svn_fs_berkeley_logfiles (apr_array_header_t **logfiles,
00223                                        const char *path,
00224                                        svn_boolean_t only_unused,
00225                                        apr_pool_t *pool);
00226 
00227 
00228 /** @} */
00229 
00230 
00231 /** Filesystem Nodes.
00232  *
00233  * In a Subversion filesystem, a `node' corresponds roughly to an
00234  * `inode' in a Unix filesystem:
00235  * - A node is either a file or a directory.
00236  * - A node's contents change over time.
00237  * - When you change a node's contents, it's still the same node; it's
00238  *   just been changed.  So a node's identity isn't bound to a specific
00239  *   set of contents.
00240  * - If you rename a node, it's still the same node, just under a
00241  *   different name.  So a node's identity isn't bound to a particular
00242  *   filename.
00243  *
00244  * A `node revision' refers to a node's contents at a specific point in
00245  * time.  Changing a node's contents always creates a new revision of that
00246  * node.  Once created, a node revision's contents never change.
00247  *
00248  * When we create a node, its initial contents are the initial revision of
00249  * the node.  As users make changes to the node over time, we create new
00250  * revisions of that same node.  When a user commits a change that deletes
00251  * a file from the filesystem, we don't delete the node, or any revision
00252  * of it --- those stick around to allow us to recreate prior revisions of
00253  * the filesystem.  Instead, we just remove the reference to the node
00254  * from the directory.
00255  *
00256  * @defgroup svn_fs_nodes filesystem nodes
00257  * @{
00258  */
00259 
00260 /** An object representing a node-id.  */
00261 typedef struct svn_fs_id_t svn_fs_id_t;
00262 
00263 
00264 /** Return -1, 0, or 1 if node revisions @a a and @a B are unrelated,
00265  * equivalent, or otherwise related (respectively).
00266  */
00267 int svn_fs_compare_ids (const svn_fs_id_t *a, const svn_fs_id_t *b);
00268 
00269 
00270 
00271 /** Return non-zero IFF the nodes associated with @a id1 and @a id2 are
00272  * related, else return zero.  
00273  *
00274  * NOTE: While this might seem redundant in the presence of
00275  * @c svn_fs_compare_ids (looking for a return value != -1), it is
00276  * slightly faster to run if the equality case is not interesting to
00277  * you.
00278  */
00279 svn_boolean_t svn_fs_check_related (const svn_fs_id_t *id1,
00280                                     const svn_fs_id_t *id2);
00281 
00282 
00283 /** Parse the @a len bytes at @a data as a node revision @a id.  Return zero 
00284  * if the bytes are not a properly-formed @a id.  Allocate the parsed @a id 
00285  * in @a pool.
00286  */
00287 svn_fs_id_t *svn_fs_parse_id (const char *data, 
00288                               apr_size_t len,
00289                               apr_pool_t *pool);
00290 
00291 
00292 /** Return a Subversion string containing the unparsed form of the
00293  * node or node revision id @a id.  Allocate the string containing the
00294  * unparsed form in @a pool.
00295  */
00296 svn_string_t *svn_fs_unparse_id (const svn_fs_id_t *id, 
00297                                  apr_pool_t *pool);
00298 
00299 /** @} */
00300 
00301 
00302 /** Filesystem Transactions.
00303  *
00304  * To make a change to a Subversion filesystem:
00305  * - Create a transaction object, using @c svn_fs_begin_txn.
00306  * - Call @c svn_fs_txn_root, to get the transaction's root directory.
00307  * - Make whatever changes you like in that tree.
00308  * - Commit the transaction, using @c svn_fs_commit_txn.
00309  *
00310  * The filesystem implementation guarantees that your commit will
00311  * either:
00312  * - succeed completely, so that all of the changes are committed to
00313  *   create a new revision of the filesystem, or
00314  * - fail completely, leaving the filesystem unchanged.
00315  *
00316  * Until you commit the transaction, any changes you make are
00317  * invisible.  Only when your commit succeeds do they become visible
00318  * to the outside world, as a new revision of the filesystem.
00319  *
00320  * If you begin a transaction, and then decide you don't want to make
00321  * the change after all (say, because your net connection with the
00322  * client disappeared before the change was complete), you can call
00323  * @c svn_fs_abort_txn, to cancel the entire transaction; this
00324  * leaves the filesystem unchanged.
00325  *
00326  * The only way to change the contents of files or directories, or
00327  * their properties, is by making a transaction and creating a new
00328  * revision, as described above.  Once a revision has been committed, it
00329  * never changes again; the filesystem interface provides no means to
00330  * go back and edit the contents of an old revision.  Once history has
00331  * been recorded, it is set in stone.  Clients depend on this property
00332  * to do updates and commits reliably; proxies depend on this property
00333  * to cache changes accurately; and so on.
00334  *
00335  * There are two kinds of nodes in the filesystem: mutable, and
00336  * immutable.  Revisions in the filesystem consist entirely of
00337  * immutable nodes, whose contents never change.  A transaction in
00338  * progress, which the user is still constructing, uses mutable nodes
00339  * for those nodes which have been changed so far, and refers to
00340  * immutable nodes from existing revisions for portions of the tree
00341  * which haven't been changed yet in that transaction.
00342  *
00343  * Immutable nodes, as part of revisions, never refer to mutable
00344  * nodes, which are part of uncommitted transactions.  Mutable nodes
00345  * may refer to immutable nodes, or other mutable nodes.
00346  *
00347  * Note that the terms "immutable" and "mutable" describe whether or
00348  * not the nodes have been changed as part of a transaction --- not
00349  * the permissions on the nodes they refer to.  Even if you aren't
00350  * authorized to modify the filesystem's root directory, you might be
00351  * authorized to change some descendant of the root; doing so would
00352  * create a new mutable copy of the root directory.  Mutability refers
00353  * to the role of the node: part of an existing revision, or part of a
00354  * new one.  This is independent of your authorization to make changes
00355  * to a given node.
00356  *
00357  * Transactions are actually persistent objects, stored in the
00358  * database.  You can open a filesystem, begin a transaction, and
00359  * close the filesystem, and then a separate process could open the
00360  * filesystem, pick up the same transaction, and continue work on it.
00361  * When a transaction is successfully committed, it is removed from
00362  * the database.
00363  *
00364  * Every transaction is assigned a name.  You can open a transaction
00365  * by name, and resume work on it, or find out the name of a
00366  * transaction you already have open.  You can also list all the
00367  * transactions currently present in the database.
00368  *
00369  * Transaction names are guaranteed to contain only letters (upper-
00370  * and lower-case), digits, `-', and `.', from the ASCII character
00371  * set.
00372  *
00373  * @defgroup svn_fs_txns filesystem transactions
00374  * @{
00375  */
00376 
00377 /** The type of a Subversion transaction object.  */
00378 typedef struct svn_fs_txn_t svn_fs_txn_t;
00379 
00380 
00381 /** Begin a new transaction on the filesystem @a fs, based on existing
00382  * revision @a rev.  Set @a *txn_p to a pointer to the new transaction.
00383  * When committed, this transaction will create a new revision.
00384  *
00385  * Allocate the new transaction in @a pool; when @a pool is freed, the new
00386  * transaction will be closed (neither committed nor aborted).
00387  *
00388  *<pre>   >> Note: if you're building a txn for committing, you probably <<
00389  *   >> don't want to call this directly.  Instead, call            <<
00390  *   >> @c svn_repos_fs_begin_txn_for_commit(), which honors the       <<
00391  *   >> repository's hook configurations.                           <<</pre>
00392  */
00393 svn_error_t *svn_fs_begin_txn (svn_fs_txn_t **txn_p,
00394                                svn_fs_t *fs,
00395                                svn_revnum_t rev,
00396                                apr_pool_t *pool);
00397 
00398 
00399 /** Commit @a txn.
00400  *
00401  *<pre>   >> Note: you usually don't want to call this directly.        <<
00402  *   >> Instead, call @c svn_repos_fs_commit_txn(), which honors the  <<
00403  *   >> repository's hook configurations.                          <<</pre>
00404  *
00405  * If the transaction conflicts with other changes committed to the
00406  * repository, return an @c SVN_ERR_FS_CONFLICT error.  Otherwise, create
00407  * a new filesystem revision containing the changes made in @a txn,
00408  * storing that new revision number in @a *new_rev, and return zero.
00409  *
00410  * If @a conflict_p is non-zero, use it to provide details on any
00411  * conflicts encountered merging @a txn with the most recent committed
00412  * revisions.  If a conflict occurs, set @a *conflict_p to the path of
00413  * the conflict in @a txn, with the same lifetime as @a txn;
00414  * otherwise, set @a *conflict_p to null.
00415  *
00416  * If the commit succeeds, @a txn is invalid.
00417  *
00418  * If the commit fails, @a txn is still valid; you can make more
00419  * operations to resolve the conflict, or call @c svn_fs_abort_txn to
00420  * abort the transaction.
00421  *
00422  * NOTE:  Success or failure of the commit of @a txn is determined by
00423  * examining the value of @a *new_rev upon this function's return.  If
00424  * the value is a valid revision number, the commit was successful,
00425  * even though a non-@c NULL function return value may indicate that
00426  * something else went wrong.
00427  */
00428 svn_error_t *svn_fs_commit_txn (const char **conflict_p,
00429                                 svn_revnum_t *new_rev,
00430                                 svn_fs_txn_t *txn,
00431                                 apr_pool_t *pool);
00432 
00433 
00434 /** Abort the transaction @a txn.  Any changes made in @a txn are
00435  * discarded, and the filesystem is left unchanged.  Use @a pool for
00436  * any necessary allocations.
00437  *
00438  * Use @a pool for any necessary allocations.
00439  *
00440  * NOTE: This function first sets the state of the transaction to
00441  * "dead", and then attempts to the purge the txn and any related data
00442  * from the filesystem.  If some part of the cleanup process fails,
00443  * the transaction and some portion of its data may remain in the
00444  * database after this function returns.  Use @c svn_fs_purge_txn() to
00445  * retry the transaction cleanup.
00446  */
00447 svn_error_t *svn_fs_abort_txn (svn_fs_txn_t *txn,
00448                                apr_pool_t *pool);
00449 
00450 
00451 /** Cleanup the dead transaction in @a fs whose ID is @a txn_id.  Use
00452  * @a pool for all allocations.  If the transaction is not yet dead,
00453  * the error @c SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned.  (The
00454  * caller probably forgot to abort the transaction, or the cleanup
00455  * step of that abort failed for some reason.)
00456  */
00457 svn_error_t *svn_fs_purge_txn (svn_fs_t *fs,
00458                                const char *txn_id,
00459                                apr_pool_t *pool);
00460 
00461 
00462 /** Set @a *name_p to the name of the transaction @a txn, as a
00463  * null-terminated string.  Allocate the name in @a pool.
00464  */
00465 svn_error_t *svn_fs_txn_name (const char **name_p,
00466                               svn_fs_txn_t *txn,
00467                               apr_pool_t *pool);
00468 
00469 
00470 /** Return @a txn's base revision.  If @a txn's base root id is an mutable
00471  * node, return 0.
00472  */
00473 svn_revnum_t svn_fs_txn_base_revision (svn_fs_txn_t *txn);
00474 
00475 
00476 
00477 /** Open the transaction named @a name in the filesystem @a fs.  Set @a *txn 
00478  * to the transaction.
00479  *
00480  * If there is no such transaction, @c SVN_ERR_FS_NO_SUCH_TRANSACTION is
00481  * the error returned.
00482  *
00483  * Allocate the new transaction in @a pool; when @a pool is freed, the new
00484  * transaction will be closed (neither committed nor aborted).
00485  */
00486 svn_error_t *svn_fs_open_txn (svn_fs_txn_t **txn,
00487                               svn_fs_t *fs,
00488                               const char *name,
00489                               apr_pool_t *pool);
00490 
00491 
00492 /** Set @a *names_p to an array of <tt>const char *</tt> @a ids which are the 
00493  * names of all the currently active transactions in the filesystem @a fs.
00494  * Allocate the array in @a pool.
00495  */
00496 svn_error_t *svn_fs_list_transactions (apr_array_header_t **names_p,
00497                                        svn_fs_t *fs,
00498                                        apr_pool_t *pool);
00499 
00500 /* Transaction properties */
00501 
00502 /** Set @a *value_p to the value of the property named @a propname on
00503  * transaction @a txn.  If @a txn has no property by that name, set 
00504  * @a *value_p to zero.  Allocate the result in @a pool.
00505  */
00506 svn_error_t *svn_fs_txn_prop (svn_string_t **value_p,
00507                               svn_fs_txn_t *txn,
00508                               const char *propname,
00509                               apr_pool_t *pool);
00510 
00511 
00512 /** Set @a *table_p to the entire property list of transaction @a txn in
00513  * filesystem @a fs, as an APR hash table allocated in @a pool.  The
00514  * resulting table maps property names to pointers to @c svn_string_t
00515  * objects containing the property value.
00516  */
00517 svn_error_t *svn_fs_txn_proplist (apr_hash_t **table_p,
00518                                   svn_fs_txn_t *txn,
00519                                   apr_pool_t *pool);
00520 
00521 
00522 /** Change a transactions @a txn's property's value, or add/delete a
00523  * property.  @a name is the name of the property to change, and @a value 
00524  * is the new value of the property, or zero if the property should be
00525  * removed altogether.  Do any necessary temporary allocation in @a pool.
00526  */
00527 svn_error_t *svn_fs_change_txn_prop (svn_fs_txn_t *txn,
00528                                      const char *name,
00529                                      const svn_string_t *value,
00530                                      apr_pool_t *pool);
00531 
00532 /** @} */
00533 
00534 
00535 /** Roots.
00536  *
00537  * An @c svn_fs_root_t object represents the root directory of some
00538  * revision or transaction in a filesystem.  To refer to particular
00539  * node, you provide a root, and a directory path relative that root.
00540  *
00541  * @defgroup svn_fs_roots filesystem roots
00542  * @{
00543  */
00544 
00545 /** The Filesystem Root object. */
00546 typedef struct svn_fs_root_t svn_fs_root_t;
00547 
00548 
00549 /** Set @a *root_p to the root directory of revision @a rev in filesystem 
00550  * @a fs.  Allocate @a *root_p in @a pool.
00551  */
00552 svn_error_t *svn_fs_revision_root (svn_fs_root_t **root_p,
00553                                    svn_fs_t *fs,
00554                                    svn_revnum_t rev,
00555                                    apr_pool_t *pool);
00556 
00557 
00558 /** Set @a *root_p to the root directory of @a txn.  Allocate @a *root_p in 
00559  * @a pool.
00560  */
00561 svn_error_t *svn_fs_txn_root (svn_fs_root_t **root_p,
00562                               svn_fs_txn_t *txn,
00563                               apr_pool_t *pool);
00564 
00565 
00566 /** Free the root directory @a root.  Simply clearing or destroying the
00567  * pool @a root was allocated in will have the same effect as calling
00568  * this function.
00569  */
00570 void svn_fs_close_root (svn_fs_root_t *root);
00571 
00572 
00573 /** Return the filesystem to which @a root belongs.  */
00574 svn_fs_t *svn_fs_root_fs (svn_fs_root_t *root);
00575 
00576 
00577 /** Return @c TRUE iff @a root is a transaction root.  */
00578 svn_boolean_t svn_fs_is_txn_root (svn_fs_root_t *root);
00579 
00580 /** Return @c TRUE iff @a root is a revision root.  */
00581 svn_boolean_t svn_fs_is_revision_root (svn_fs_root_t *root);
00582 
00583 
00584 /** If @a root is the root of a transaction, return the name of the
00585  * transaction, allocated in @a pool; otherwise, return null.
00586  */
00587 const char *svn_fs_txn_root_name (svn_fs_root_t *root,
00588                                   apr_pool_t *pool);
00589 
00590 
00591 /** If @a root is the root of a revision, return the revision number.
00592  * Otherwise, return @c SVN_INVALID_REVNUM.
00593  */
00594 svn_revnum_t svn_fs_revision_root_revision (svn_fs_root_t *root);
00595 
00596 /** @} */
00597 
00598 
00599 /** Directory entry names and directory paths.
00600  *
00601  * Here are the rules for directory entry names, and directory paths:
00602  *
00603  * A directory entry name is a Unicode string encoded in UTF-8, and
00604  * may not contain the null character (U+0000).  The name should be in
00605  * Unicode canonical decomposition and ordering.  No directory entry
00606  * may be named '.', '..', or the empty string.  Given a directory
00607  * entry name which fails to meet these requirements, a filesystem
00608  * function returns an SVN_ERR_FS_PATH_SYNTAX error.
00609  *
00610  * A directory path is a sequence of zero or more directory entry
00611  * names, separated by slash characters (U+002f), and possibly ending
00612  * with slash characters.  Sequences of two or more consecutive slash
00613  * characters are treated as if they were a single slash.  If a path
00614  * ends with a slash, it refers to the same node it would without the
00615  * slash, but that node must be a directory, or else the function
00616  * returns an SVN_ERR_FS_NOT_DIRECTORY error.
00617  *
00618  * A path consisting of the empty string, or a string containing only
00619  * slashes, refers to the root directory.
00620  *
00621  * @defgroup svn_fs_directories filesystem directories
00622  * @{
00623  */
00624 
00625 
00626 
00627 /** The kind of change that occurred on the path. */
00628 typedef enum
00629 {
00630   /** default value */
00631   svn_fs_path_change_modify = 0,
00632 
00633   /** path added in txn */
00634   svn_fs_path_change_add,
00635 
00636   /** path removed in txn */
00637   svn_fs_path_change_delete,
00638 
00639   /** path removed and re-added in txn */
00640   svn_fs_path_change_replace,
00641 
00642   /** ignore all previous change items for path (internal-use only) */
00643   svn_fs_path_change_reset
00644 
00645 } svn_fs_path_change_kind_t;
00646 
00647 /** Change descriptor. */
00648 typedef struct svn_fs_path_change_t
00649 {
00650   /** node revision id of changed path */
00651   const svn_fs_id_t *node_rev_id;
00652 
00653   /** kind of change (see above) */
00654   svn_fs_path_change_kind_t change_kind;
00655 
00656   /** were there text mods? */
00657   svn_boolean_t text_mod;
00658 
00659   /** were there property mods? */
00660   svn_boolean_t prop_mod;
00661 
00662 } svn_fs_path_change_t;
00663 
00664 
00665 /** Determine what has changed under a @a root.
00666  *
00667  * Allocate and return a hash @a *changed_paths_p containing descriptions
00668  * of the paths changed under @a root.  The hash is keyed with 
00669  * <tt>const char *</tt> paths, and has @c svn_fs_path_change_t * values.  
00670  * Use @c pool for all allocations, including the hash and its values.
00671  */
00672 svn_error_t *svn_fs_paths_changed (apr_hash_t **changed_paths_p,
00673                                    svn_fs_root_t *root,
00674                                    apr_pool_t *pool);
00675 
00676 /** @} */
00677 
00678 
00679 /* Operations appropriate to all kinds of nodes.  */
00680 
00681 /** Set @a *kind_p to the type of node present at @a path under @a
00682  * root.  If @a path does not exist under @a root, set @a *kind to @c
00683  * svn_node_none.  Use @a pool for temporary allocation.
00684  */
00685 svn_error_t *svn_fs_check_path (svn_node_kind_t *kind_p,
00686                                 svn_fs_root_t *root,
00687                                 const char *path,
00688                                 apr_pool_t *pool);
00689 
00690 
00691 /** An opaque node history object. */
00692 typedef struct svn_fs_history_t svn_fs_history_t;
00693 
00694 
00695 /** Set @a *history_p to an opaque node history object which
00696  * represents @a path under @a root.  @a root must be a revision root.
00697  * Use @a pool for all allocations.
00698  */
00699 svn_error_t *svn_fs_node_history (svn_fs_history_t **history_p,
00700                                   svn_fs_root_t *root,
00701                                   const char *path,
00702                                   apr_pool_t *pool);
00703 
00704 
00705 /** Set @a *prev_history_t to an opaque node history object which
00706  * represents the previous (or "next oldest") interesting history
00707  * location for the filesystem node represented by @a history, or @c
00708  * NULL if no such previous history exists.  If @a cross_copies is @c
00709  * FALSE, also return @c NULL if stepping backwards in history to @a
00710  * prev_history_t would cross a filesystem copy operation.  
00711  *
00712  * NOTE: If this is the first call to svn_fs_history_prev() for the @a
00713  * history object, it could return a history object whose location is
00714  * the same as the original.  This will happen if the original
00715  * location was an interested one (where the node was modified, or
00716  * took place in a copy event).  This behavior allows looping callers
00717  * to avoid the calling svn_fs_history_location() on the object
00718  * returned by svn_fs_node_history(), and instead go ahead and begin
00719  * calling svn_fs_history_prev().
00720  *
00721  * NOTE: This function uses node-id ancestry alone to determine
00722  * modifiedness, and therefore does NOT claim that in any of the
00723  * returned revisions file contents changed, properties changed,
00724  * directory entries lists changed, etc.  
00725  *
00726  * ALSO NOTE: The revisions returned for @a path will be older than or
00727  * the same age as the revision of that path in @a root.  That is, if
00728  * @a root is a revision root based on revision X, and @a path was
00729  * modified in some revision(s) younger than X, those revisions
00730  * younger than X will not be included for @a path.  */
00731 svn_error_t *svn_fs_history_prev (svn_fs_history_t **prev_history_p,
00732                                   svn_fs_history_t *history,
00733                                   svn_boolean_t cross_copies,
00734                                   apr_pool_t *pool);
00735 
00736 
00737 /** Set @a *path and @a *revision to the path and revision,
00738  * respectively, of the @a history object.  Use @a pool for all
00739  * allocations. 
00740  */
00741 svn_error_t *svn_fs_history_location (const char **path,
00742                                       svn_revnum_t *revision,
00743                                       svn_fs_history_t *history,
00744                                       apr_pool_t *pool);
00745                                       
00746 
00747 /** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory.
00748  * Do any necessary temporary allocation in @a pool.
00749  */
00750 svn_error_t *svn_fs_is_dir (svn_boolean_t *is_dir,
00751                             svn_fs_root_t *root,
00752                             const char *path,
00753                             apr_pool_t *pool);
00754 
00755 
00756 /** Set @a *is_file to @c TRUE iff @a path in @a root is a file.
00757  * Do any necessary temporary allocation in @a pool.
00758  */
00759 svn_error_t *svn_fs_is_file (svn_boolean_t *is_file,
00760                              svn_fs_root_t *root,
00761                              const char *path,
00762                              apr_pool_t *pool);
00763 
00764 
00765 /** Get the id of a node.
00766  *
00767  * Set @a *id_p to the node revision ID of @a path in @a root, allocated in 
00768  * @a pool.
00769  *
00770  * If @a root is the root of a transaction, keep in mind that other
00771  * changes to the transaction can change which node @a path refers to,
00772  * and even whether the path exists at all.
00773  */
00774 svn_error_t *svn_fs_node_id (const svn_fs_id_t **id_p,
00775                              svn_fs_root_t *root,
00776                              const char *path,
00777                              apr_pool_t *pool);
00778 
00779 /** Set @a *revision to the revision in which @a path under @a root was 
00780  * created.  Use @a pool for any temporary allocations.  @a *revision will 
00781  * be set to @c SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes 
00782  * under a transaction root).
00783  */
00784 svn_error_t *svn_fs_node_created_rev (svn_revnum_t *revision,
00785                                       svn_fs_root_t *root,
00786                                       const char *path,
00787                                       apr_pool_t *pool);
00788 
00789 /** Set @a *created_path to the path at with @a path under @root was
00790  * created.  Use @a pool for all allocations.  Callers may use this
00791  * function in conjunction with svn_fs_node_created_rev() perform a
00792  * reverse lookup of the mapping of (path, revision) -> node-id that
00793  * svn_fs_node_id() performs.
00794  */
00795 svn_error_t *svn_fs_node_created_path (const char **created_path,
00796                                        svn_fs_root_t *root,
00797                                        const char *path,
00798                                        apr_pool_t *pool);
00799 
00800 
00801 /** Set @a *value_p to the value of the property named @a propname of 
00802  * @a path in @a root.  If the node has no property by that name, set 
00803  * @a *value_p to zero.  Allocate the result in @a pool.
00804  */
00805 svn_error_t *svn_fs_node_prop (svn_string_t **value_p,
00806                                svn_fs_root_t *root,
00807                                const char *path,
00808                                const char *propname,
00809                                apr_pool_t *pool);
00810    
00811 
00812 /** Set @a *table_p to the entire property list of @a path in @a root, 
00813  * as an APR hash table allocated in @a pool.  The resulting table maps 
00814  * property names to pointers to @c svn_string_t objects containing the 
00815  * property value.
00816  */
00817 svn_error_t *svn_fs_node_proplist (apr_hash_t **table_p,
00818                                    svn_fs_root_t *root,
00819                                    const char *path,
00820                                    apr_pool_t *pool);
00821 
00822 
00823 /** Change a node's property's value, or add/delete a property.
00824  *
00825  * - @a root and @a path indicate the node whose property should change.
00826  *   @a root must be the root of a transaction, not the root of a revision.
00827  * - @a name is the name of the property to change.
00828  * - @a value is the new value of the property, or zero if the property should
00829  *   be removed altogether.
00830  * Do any necessary temporary allocation in @a pool.
00831  */
00832 svn_error_t *svn_fs_change_node_prop (svn_fs_root_t *root,
00833                                       const char *path,
00834                                       const char *name,
00835                                       const svn_string_t *value,
00836                                       apr_pool_t *pool);
00837 
00838 
00839 /** Determine if the properties of two path/root combinations are different.
00840  *
00841  * Set @a *changed_p to 1 if the properties at @a path1 under @a root1 differ
00842  * from those at @a path2 under @a root2, or set it to 0 if they are the
00843  * same.  Both paths must exist under their respective roots, and both
00844  * roots must be in the same filesystem.
00845  */
00846 svn_error_t *svn_fs_props_changed (svn_boolean_t *changed_p,
00847                                    svn_fs_root_t *root1,
00848                                    const char *path1,
00849                                    svn_fs_root_t *root2,
00850                                    const char *path2,
00851                                    apr_pool_t *pool);
00852 
00853 
00854 /** Discover a node's copy ancestry, if any.
00855  *
00856  * If the node at @a path in @a root was copied from some other node, set
00857  * @a *rev_p and @a *path_p to the revision and path of the other node,
00858  * allocating @a *path_p in @a pool.
00859  *
00860  * Else if there is no copy ancestry for the node, set @a *rev_p to
00861  * @c SVN_INVALID_REVNUM and @a *path_p to null.
00862  *
00863  * If an error is returned, the values of @a *rev_p and @a *path_p are
00864  * undefined, but otherwise, if one of them is set as described above,
00865  * you may assume the other is set correspondingly.
00866  *
00867  * @a root may be a revision root or a transaction root.
00868  *
00869  * Notes:
00870  *    - Copy ancestry does not descend.  After copying directory D to
00871  *      E, E will have copy ancestry referring to D, but E's children
00872  *      may not.  See also @c svn_fs_copy().
00873  *
00874  *    - Copy ancestry *under* a copy is preserved.  That is, if you
00875  *      copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then
00876  *      /G/pi2 will still have copy ancestry pointing to /A/D/G/pi.
00877  *      We don't know if this is a feature or a bug yet; if it turns
00878  *      out to be a bug, then the fix is to make @c svn_fs_copied_from()
00879  *      observe the following logic, which currently callers may
00880  *      choose to follow themselves: if node X has copy history, but
00881  *      its ancestor A also has copy history, then you may ignore X's
00882  *      history if X's revision-of-origin is earlier than A's --
00883  *      because that would mean that X's copy history was preserved in
00884  *      a copy-under-a-copy scenario.  If X's revision-of-origin is
00885  *      the same as A's, then it was copied under A during the same
00886  *      transaction that created A.  (X's revision-of-origin cannot be
00887  *      greater than A's, if X has copy history.)  ### todo: See how
00888  *      people like this, it can always be hidden behind the curtain
00889  *      if necessary.
00890  *
00891  *    - Copy ancestry is not stored as a regular subversion property
00892  *      because it is not inherited.  Copying foo to bar results in a
00893  *      revision of bar with copy ancestry; but committing a text
00894  *      change to bar right after that results in a new revision of
00895  *      bar without copy ancestry.
00896  */
00897 svn_error_t *svn_fs_copied_from (svn_revnum_t *rev_p,
00898                                  const char **path_p,
00899                                  svn_fs_root_t *root,
00900                                  const char *path,
00901                                  apr_pool_t *pool);
00902 
00903 
00904 /** Merge changes between two nodes into a third node.
00905  *
00906  * Given nodes @a source and @a target, and a common ancestor @a ancestor,
00907  * modify @a target to contain all the changes made between @a ancestor and
00908  * @a source, as well as the changes made between @a ancestor and @a target.
00909  * @a target_root must be the root of a transaction, not a revision.
00910  *
00911  * @a source, @a target, and @a ancestor are generally directories; this
00912  * function recursively merges the directories' contents.  If they are
00913  * files, this function simply returns an error whenever @a source,
00914  * @a target, and @a ancestor are all distinct node revisions.
00915  *
00916  * If there are differences between @a ancestor and @a source that conflict
00917  * with changes between @a ancestor and @a target, this function returns an
00918  * @c SVN_ERR_FS_CONFLICT error.
00919  *
00920  * If the merge is successful, @a target is left in the merged state, and
00921  * the base root of @a target's txn is set to the root node of @a source.
00922  * If an error is returned (whether for conflict or otherwise), @a target
00923  * is left unaffected.
00924  *
00925  * If @a conflict_p is non-null, then: a conflict error sets @a *conflict_p
00926  * to the name of the node in @a target which couldn't be merged,
00927  * otherwise, success sets @a *conflict_p to null.
00928  *
00929  * Do any necessary temporary allocation in @a pool.
00930  */
00931 svn_error_t *svn_fs_merge (const char **conflict_p,
00932                            svn_fs_root_t *source_root,
00933                            const char *source_path,
00934                            svn_fs_root_t *target_root,
00935                            const char *target_path,
00936                            svn_fs_root_t *ancestor_root,
00937                            const char *ancestor_path,
00938                            apr_pool_t *pool);
00939 
00940 
00941 
00942 /* Directories.  */
00943 
00944 
00945 /** The type of a Subversion directory entry.  */
00946 typedef struct svn_fs_dirent_t
00947 {
00948 
00949   /** The name of this directory entry.  */
00950   const char *name;
00951 
00952   /** The node revision ID it names.  */
00953   const svn_fs_id_t *id;
00954 
00955   /** The node kind. */
00956   svn_node_kind_t kind;
00957 
00958 } svn_fs_dirent_t;
00959 
00960 
00961 /** Set @a *table_p to a newly allocated APR hash table containing the
00962  * entries of the directory at @a path in @a root.  The keys of the table
00963  * are entry names, as byte strings, excluding the final null
00964  * character; the table's values are pointers to @c svn_fs_dirent_t
00965  * structures.  Allocate the table and its contents in @a pool.
00966  */
00967 svn_error_t *svn_fs_dir_entries (apr_hash_t **entries_p,
00968                                  svn_fs_root_t *root,
00969                                  const char *path,
00970                                  apr_pool_t *pool);
00971 
00972 
00973 /** Create a new directory named @a path in @a root.  The new directory has
00974  * no entries, and no properties.  @a root must be the root of a transaction, 
00975  * not a revision.
00976  *
00977  * Do any necessary temporary allocation in @a pool.
00978  */
00979 svn_error_t *svn_fs_make_dir (svn_fs_root_t *root,
00980                               const char *path,
00981                               apr_pool_t *pool);
00982                               
00983 
00984 /** Delete the node named @a path in @a root.  If the node being deleted is
00985  * a directory, its contents will be deleted recursively.  @a root must be
00986  * the root of a transaction, not of a revision.  Use @a pool for
00987  * temporary allocation.
00988  *
00989  * This function may be more efficient than making the equivalent
00990  * series of calls to @c svn_fs_delete, because it takes advantage of the
00991  * fact that, to delete an immutable subtree, shared with some
00992  * committed revision, you need only remove the directory entry.  The
00993  * dumb algorithm would recurse into the subtree and end up cloning
00994  * each non-empty directory it contains, only to delete it later.
00995  *
00996  * If return @c SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is
00997  * missing from its parent, that is, the final target of the deletion
00998  * is missing.
00999  *
01000  * Attempting to remove the root dir also results in an error,
01001  * @c SVN_ERR_FS_ROOT_DIR, even if the dir is empty.
01002  */
01003 svn_error_t *svn_fs_delete (svn_fs_root_t *root,
01004                             const char *path,
01005                             apr_pool_t *pool);
01006 
01007 
01008 /** Create a copy of @a from_path in @a from_root named @a to_path in 
01009  * @a to_root.  If @a from_path in @a from_root is a directory, copy the 
01010  * tree it refers to recursively.
01011  *
01012  * The copy will remember its source; use @c svn_fs_copied_from() to
01013  * access this information.
01014  *
01015  * @a to_root must be the root of a transaction; @a from_path must be the
01016  * root of a revision.  (Requiring @a from_path to be the root of a
01017  * revision makes the implementation trivial: there is no detectable
01018  * difference (modulo node revision ID's) between copying @a from and
01019  * simply adding a reference to it.  So the operation takes place in
01020  * constant time.  However, there's no reason not to extend this to
01021  * mutable nodes --- it's just more code.)
01022  *
01023  * Note: to do a copy without preserving copy history, use
01024  * @c svn_fs_revision_link().
01025  *
01026  * Do any necessary temporary allocation in @a pool.
01027  */
01028 svn_error_t *svn_fs_copy (svn_fs_root_t *from_root,
01029                           const char *from_path,
01030                           svn_fs_root_t *to_root,
01031                           const char *to_path,
01032                           apr_pool_t *pool);
01033 
01034 
01035 /** Like @c svn_fs_copy(), but doesn't record copy history, and preserves
01036  * the PATH.  You cannot use @c svn_fs_copied_from() later to find out
01037  * where this copy came from.
01038  *
01039  * Use @c svn_fs_revision_link() in situations where you don't care
01040  * about the copy history, and where @a to_path and @a from_path are
01041  * the same, because it is cheaper than @c svn_fs_copy().
01042  */
01043 svn_error_t *svn_fs_revision_link (svn_fs_root_t *from_root,
01044                                    svn_fs_root_t *to_root,
01045                                    const char *path,
01046                                    apr_pool_t *pool);
01047 
01048 /* Files.  */
01049 
01050 /** Set @a *length_p to the length of the file @a path in @a root, in bytes. 
01051  * Do any necessary temporary allocation in @a pool.
01052  */
01053 svn_error_t *svn_fs_file_length (svn_filesize_t *length_p,
01054                                  svn_fs_root_t *root,
01055                                  const char *path,
01056                                  apr_pool_t *pool);
01057 
01058 
01059 /** Put the MD5 checksum of file @a path into @a digest, which points
01060  * to @c APR_MD5_DIGESTSIZE bytes of storage.  Use @a pool only for temporary
01061  * allocations.
01062  *
01063  * If the filesystem does not have a prerecorded checksum for @a path,
01064  * do not calculate a checksum dynamically, just put all 0's into @a
01065  * digest.  (By convention, the all-zero checksum is considered to
01066  * match any checksum.)
01067  *
01068  * Notes:
01069  *
01070  * You might wonder, why do we only provide this interface for file
01071  * contents, and not for properties or directories?
01072  *
01073  * The answer is that property lists and directory entry lists are
01074  * essentially data structures, not text.  We serialize them for
01075  * transmission, but there is no guarantee that the consumer will
01076  * parse them into the same form, or even the same order, as the
01077  * producer.  It's difficult to find a checksumming method that
01078  * reaches the same result given such variation in input.  (I suppose
01079  * we could calculate an independent MD5 sum for each propname and
01080  * value, and XOR them together; same with directory entry names.
01081  * Maybe that's the solution?)  Anyway, for now we punt.  The most
01082  * important data, and the only data that goes through svndiff
01083  * processing, is file contents, so that's what we provide
01084  * checksumming for.
01085  *
01086  * Internally, of course, the filesystem checksums everything, because
01087  * it has access to the lowest level storage forms: strings behind
01088  * representations.
01089  */
01090 svn_error_t *svn_fs_file_md5_checksum (unsigned char digest[],
01091                                        svn_fs_root_t *root,
01092                                        const char *path,
01093                                        apr_pool_t *pool);
01094 
01095 
01096 /** Set @a *contents to a readable generic stream that will yield the
01097  * contents of the file @a path in @a root.  Allocate the stream in 
01098  * @a pool.  You can only use @a *contents for as long as the underlying
01099  * filesystem is open.  If @a path is not a file, return 
01100  * @c SVN_ERR_FS_NOT_FILE.
01101  *
01102  * If @a root is the root of a transaction, it is possible that the
01103  * contents of the file @a path will change between calls to
01104  * @c svn_fs_file_contents().  In that case, the result of reading from
01105  * @a *contents is undefined.  
01106  *
01107  * ### kff todo: I am worried about lifetime issues with this pool vs
01108  * the trail created farther down the call stack.  Trace this function
01109  * to investigate...
01110  */
01111 svn_error_t *svn_fs_file_contents (svn_stream_t **contents,
01112                                    svn_fs_root_t *root,
01113                                    const char *path,
01114                                    apr_pool_t *pool);
01115 
01116 
01117 /** Create a new file named @a path in @a root.  The file's initial contents
01118  * are the empty string, and it has no properties.  @a root must be the
01119  * root of a transaction, not a revision.
01120  *
01121  * Do any necessary temporary allocation in @a pool.
01122  */
01123 svn_error_t *svn_fs_make_file (svn_fs_root_t *root,
01124                                const char *path,
01125                                apr_pool_t *pool);
01126 
01127 
01128 /** Apply a text delta to the file @a path in @a root.  @a root must be the 
01129  * root of a transaction, not a revision.
01130  *
01131  * Set @a *contents_p to a function ready to receive text delta windows
01132  * describing how to change the file's contents, relative to its
01133  * current contents.  Set @a *contents_baton_p to a baton to pass to
01134  * @a *contents_p.
01135  *
01136  * If @a path does not exist in @a root, return an error.  (You cannot use
01137  * this routine to create new files;  use @c svn_fs_make_file to create
01138  * an empty file first.)
01139  *
01140  * @a base_checksum is the hex MD5 digest for the base text against
01141  * which the delta is to be applied; it is ignored if null, and may be
01142  * ignored even if not null.  If it is not ignored, it must match the
01143  * checksum of the base text against which svndiff data is being
01144  * applied; if not, svn_fs_apply_textdelta or the @a *contents_p call
01145  * which detects the mismatch will return the error
01146  * @c SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
01147  * still be an error if @a base_checksum is neither null nor the
01148  * checksum of the empty string).
01149  *
01150  * @a result_checksum is the hex MD5 digest for the fulltext that
01151  * results from this delta application.  It is ignored if null, but if
01152  * not null, it must match the checksum of the result; if it does not,
01153  * then the @a *contents_p call which detects the mismatch will return
01154  * the error @c SVN_ERR_CHECKSUM_MISMATCH.
01155  *
01156  * Do temporary allocation in @a pool.
01157  */
01158 svn_error_t *svn_fs_apply_textdelta (svn_txdelta_window_handler_t *contents_p,
01159                                      void **contents_baton_p,
01160                                      svn_fs_root_t *root,
01161                                      const char *path,
01162                                      const char *base_checksum,
01163                                      const char *result_checksum,
01164                                      apr_pool_t *pool);
01165 
01166 
01167 /** Write data directly to the file @a path in @a root.  @a root must be the
01168  * root of a transaction, not a revision.
01169  *
01170  * Set @a *contents_p to a stream ready to receive full textual data.
01171  * When the caller closes this stream, the data replaces the previous
01172  * contents of the file.
01173  *
01174  * If @a path does not exist in @a root, return an error.  (You cannot use
01175  * this routine to create new files;  use @c svn_fs_make_file to create
01176  * an empty file first.)
01177  *
01178  * @a result_checksum is the hex MD5 digest for the final fulltext
01179  * written to the stream.  It is ignored if null, but if not null, it
01180  * must match the checksum of the result; if it does not, then the @a
01181  * *contents_p call which detects the mismatch will return the error
01182  * @c SVN_ERR_CHECKSUM_MISMATCH.
01183  *
01184  * Do any necessary temporary allocation in @a pool.
01185  *
01186  * ### This is like svn_fs_apply_textdelta, but takes the text
01187  * straight.  It is currently used only by the loader, see
01188  * libsvn_repos/load.c.  It should accept a checksum, of course, which
01189  * would come from an (optional) header in the dump file.  See
01190  * http://subversion.tigris.org/issues/show_bug.cgi?id=1102 for more.
01191  */
01192 svn_error_t *svn_fs_apply_text (svn_stream_t **contents_p,
01193                                 svn_fs_root_t *root,
01194                                 const char *path,
01195                                 const char *result_checksum,
01196                                 apr_pool_t *pool);
01197 
01198 
01199 /** Check if the contents of two root/path combos have changed.
01200  *
01201  * Set @a *changed_p to 1 if the contents at @a path1 under @a root1 differ
01202  * from those at @a path2 under @a root2, or set it to 0 if they are the
01203  * same.  Both paths must exist under their respective roots, and both
01204  * roots must be in the same filesystem. 
01205  */
01206 svn_error_t *svn_fs_contents_changed (svn_boolean_t *changed_p,
01207                                       svn_fs_root_t *root1,
01208                                       const char *path1,
01209                                       svn_fs_root_t *root2,
01210                                       const char *path2,
01211                                       apr_pool_t *pool);
01212 
01213 
01214 
01215 /* Filesystem revisions.  */
01216 
01217 
01218 /** Set @a *youngest_p to the number of the youngest revision in filesystem 
01219  * @a fs.  Use @a pool for all temporary allocation.
01220  *
01221  * The oldest revision in any filesystem is numbered zero.
01222  */
01223 svn_error_t *svn_fs_youngest_rev (svn_revnum_t *youngest_p,
01224                                   svn_fs_t *fs,
01225                                   apr_pool_t *pool);
01226 
01227 
01228 /** Deltify predecessors of paths modified in @a revision in
01229  * filesystem @a fs.  Use @a pool for all allocations. 
01230  * 
01231  * NOTE:  This can be a time-consuming process, depending the breadth
01232  * of the changes made in @a revision, and the depth of the history of
01233  * those changed paths. 
01234  */
01235 svn_error_t *svn_fs_deltify_revision (svn_fs_t *fs,
01236                                       svn_revnum_t revision,
01237                                       apr_pool_t *pool);
01238 
01239 
01240 /** Set @a *value_p to the value of the property named @a propname on
01241  * revision @a rev in the filesystem @a fs.  If @a rev has no property by 
01242  * that name, set @a *value_p to zero.  Allocate the result in @a pool.
01243  */
01244 svn_error_t *svn_fs_revision_prop (svn_string_t **value_p,
01245                                    svn_fs_t *fs,
01246                                    svn_revnum_t rev,
01247                                    const char *propname,
01248                                    apr_pool_t *pool);
01249 
01250 
01251 /** Set @a *table_p to the entire property list of revision @a rev in
01252  * filesystem @a fs, as an APR hash table allocated in @a pool.  The table
01253  * maps <tt>char *</tt> property names to @c svn_string_t * values; the names
01254  * and values are allocated in @a pool.
01255  */
01256 svn_error_t *svn_fs_revision_proplist (apr_hash_t **table_p,
01257                                        svn_fs_t *fs,
01258                                        svn_revnum_t rev,
01259                                        apr_pool_t *pool);
01260 
01261 
01262 /** Change a revision's property's value, or add/delete a property.
01263  *
01264  * - @a fs is a filesystem, and @a rev is the revision in that filesystem
01265  *   whose property should change.
01266  * - @a name is the name of the property to change.
01267  * - @a VALUE is the new value of the property, or zero if the property should
01268  *   be removed altogether.
01269  *
01270  * Note that revision properties are non-historied --- you can change
01271  * them after the revision has been committed.  They are not protected
01272  * via transactions.
01273  *
01274  * Do any necessary temporary allocation in @a pool.
01275  */
01276 svn_error_t *svn_fs_change_rev_prop (svn_fs_t *fs,
01277                                      svn_revnum_t rev,
01278                                      const char *name,
01279                                      const svn_string_t *value,
01280                                      apr_pool_t *pool);
01281 
01282 
01283 
01284 /* Computing deltas.  */
01285 
01286 
01287 /** Set @a *stream_p to a pointer to a delta stream that will turn the
01288  * contents of the file @a source into the contents of the file @a target.
01289  * If @a source_root is zero, use a file with zero length as the source.
01290  *
01291  * This function does not compare the two files' properties.
01292  *
01293  * Allocate @a *stream_p, and do any necessary temporary allocation, in
01294  * @a pool.
01295  */
01296 svn_error_t *svn_fs_get_file_delta_stream (svn_txdelta_stream_t **stream_p,
01297                                            svn_fs_root_t *source_root,
01298                                            const char *source_path,
01299                                            svn_fs_root_t *target_root,
01300                                            const char *target_path,
01301                                            apr_pool_t *pool);
01302 
01303 
01304 
01305 /* UUID manipulation. */
01306 
01307 /** Populate @a *uuid with the UUID associated with @a fs.  Allocate
01308     @a *uuid in @a pool.  */
01309 svn_error_t *svn_fs_get_uuid (svn_fs_t *fs,
01310                               const char **uuid,
01311                               apr_pool_t *pool);
01312 
01313 
01314 /** Associate @a *uuid with @a fs.  Use @a pool for any scratchwork. */
01315 svn_error_t *svn_fs_set_uuid (svn_fs_t *fs,
01316                               const char *uuid,
01317                               apr_pool_t *pool);
01318 
01319 
01320 /* Non-historical properties.  */
01321 
01322 /* [[Yes, do tell.]] */
01323 
01324 #ifdef __cplusplus
01325 }
01326 #endif /* __cplusplus */
01327 
01328 #endif /* SVN_FS_H */

Generated on Wed Oct 13 23:55:34 2004 for Subversion by doxygen 1.3.4