svn_fs.h

linux subdivision ying gai ke yi le ba

 * This function may be more efficient than making the equivalent
 * series of calls to @c svn_fs_delete, because it takes advantage of the
 * fact that, to delete an immutable subtree, shared with some
 * committed revision, you need only remove the directory entry.  The
 * dumb algorithm would recurse into the subtree and end up cloning
 * each non-empty directory it contains, only to delete it later.
 *
 * If return @c SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is
 * missing from its parent, that is, the final target of the deletion
 * is missing.
 *
 * Attempting to remove the root dir also results in an error,
 * @c SVN_ERR_FS_ROOT_DIR, even if the dir is empty.
 */
svn_error_t *svn_fs_delete (svn_fs_root_t *root,
                            const char *path,
                            apr_pool_t *pool);


/** Create a copy of @a from_path in @a from_root named @a to_path in 
 * @a to_root.  If @a from_path in @a from_root is a directory, copy the 
 * tree it refers to recursively.
 *
 * The copy will remember its source; use @c svn_fs_copied_from() to
 * access this information.
 *
 * @a to_root must be the root of a transaction; @a from_path must be the
 * root of a revision.  (Requiring @a from_path to be the root of a
 * revision makes the implementation trivial: there is no detectable
 * difference (modulo node revision ID's) between copying @a from and
 * simply adding a reference to it.  So the operation takes place in
 * constant time.  However, there's no reason not to extend this to
 * mutable nodes --- it's just more code.)  Further, @a to_root and @a
 * from_root must represent the same filesystem.
 *
 * Note: to do a copy without preserving copy history, use
 * @c svn_fs_revision_link().
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_copy (svn_fs_root_t *from_root,
                          const char *from_path,
                          svn_fs_root_t *to_root,
                          const char *to_path,
                          apr_pool_t *pool);


/** Like @c svn_fs_copy(), but doesn't record copy history, and preserves
 * the PATH.  You cannot use @c svn_fs_copied_from() later to find out
 * where this copy came from.
 *
 * Use @c svn_fs_revision_link() in situations where you don't care
 * about the copy history, and where @a to_path and @a from_path are
 * the same, because it is cheaper than @c svn_fs_copy().
 */
svn_error_t *svn_fs_revision_link (svn_fs_root_t *from_root,
                                   svn_fs_root_t *to_root,
                                   const char *path,
                                   apr_pool_t *pool);

/* Files.  */

/** Set @a *length_p to the length of the file @a path in @a root, in bytes. 
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_file_length (svn_filesize_t *length_p,
                                 svn_fs_root_t *root,
                                 const char *path,
                                 apr_pool_t *pool);


/** Put the MD5 checksum of file @a path into @a digest, which points
 * to @c APR_MD5_DIGESTSIZE bytes of storage.  Use @a pool only for temporary
 * allocations.
 *
 * If the filesystem does not have a prerecorded checksum for @a path,
 * do not calculate a checksum dynamically, just put all 0's into @a
 * digest.  (By convention, the all-zero checksum is considered to
 * match any checksum.)
 *
 * Notes:
 *
 * You might wonder, why do we only provide this interface for file
 * contents, and not for properties or directories?
 *
 * The answer is that property lists and directory entry lists are
 * essentially data structures, not text.  We serialize them for
 * transmission, but there is no guarantee that the consumer will
 * parse them into the same form, or even the same order, as the
 * producer.  It's difficult to find a checksumming method that
 * reaches the same result given such variation in input.  (I suppose
 * we could calculate an independent MD5 sum for each propname and
 * value, and XOR them together; same with directory entry names.
 * Maybe that's the solution?)  Anyway, for now we punt.  The most
 * important data, and the only data that goes through svndiff
 * processing, is file contents, so that's what we provide
 * checksumming for.
 *
 * Internally, of course, the filesystem checksums everything, because
 * it has access to the lowest level storage forms: strings behind
 * representations.
 */
svn_error_t *svn_fs_file_md5_checksum (unsigned char digest[],
                                       svn_fs_root_t *root,
                                       const char *path,
                                       apr_pool_t *pool);


/** Set @a *contents to a readable generic stream that will yield the
 * contents of the file @a path in @a root.  Allocate the stream in 
 * @a pool.  You can only use @a *contents for as long as the underlying
 * filesystem is open.  If @a path is not a file, return 
 * @c SVN_ERR_FS_NOT_FILE.
 *
 * If @a root is the root of a transaction, it is possible that the
 * contents of the file @a path will change between calls to
 * @c svn_fs_file_contents().  In that case, the result of reading from
 * @a *contents is undefined.  
 *
 * ### kff todo: I am worried about lifetime issues with this pool vs
 * the trail created farther down the call stack.  Trace this function
 * to investigate...
 */
svn_error_t *svn_fs_file_contents (svn_stream_t **contents,
                                   svn_fs_root_t *root,
                                   const char *path,
                                   apr_pool_t *pool);


/** Create a new file named @a path in @a root.  The file's initial contents
 * are the empty string, and it has no properties.  @a root must be the
 * root of a transaction, not a revision.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_make_file (svn_fs_root_t *root,
                               const char *path,
                               apr_pool_t *pool);


/** Apply a text delta to the file @a path in @a root.  @a root must be the 
 * root of a transaction, not a revision.
 *
 * Set @a *contents_p to a function ready to receive text delta windows
 * describing how to change the file's contents, relative to its
 * current contents.  Set @a *contents_baton_p to a baton to pass to
 * @a *contents_p.
 *
 * If @a path does not exist in @a root, return an error.  (You cannot use
 * this routine to create new files;  use @c svn_fs_make_file to create
 * an empty file first.)
 *
 * @a base_checksum is the hex MD5 digest for the base text against
 * which the delta is to be applied; it is ignored if null, and may be
 * ignored even if not null.  If it is not ignored, it must match the
 * checksum of the base text against which svndiff data is being
 * applied; if not, svn_fs_apply_textdelta or the @a *contents_p call
 * which detects the mismatch will return the error
 * @c SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
 * still be an error if @a base_checksum is neither null nor the
 * checksum of the empty string).
 *
 * @a result_checksum is the hex MD5 digest for the fulltext that
 * results from this delta application.  It is ignored if null, but if
 * not null, it must match the checksum of the result; if it does not,
 * then the @a *contents_p call which detects the mismatch will return
 * the error @c SVN_ERR_CHECKSUM_MISMATCH.
 *
 * Do temporary allocation in @a pool.
 */
svn_error_t *svn_fs_apply_textdelta (svn_txdelta_window_handler_t *contents_p,
                                     void **contents_baton_p,
                                     svn_fs_root_t *root,
                                     const char *path,
                                     const char *base_checksum,
                                     const char *result_checksum,
                                     apr_pool_t *pool);


/** Write data directly to the file @a path in @a root.  @a root must be the
 * root of a transaction, not a revision.
 *
 * Set @a *contents_p to a stream ready to receive full textual data.
 * When the caller closes this stream, the data replaces the previous
 * contents of the file.
 *
 * If @a path does not exist in @a root, return an error.  (You cannot use
 * this routine to create new files;  use @c svn_fs_make_file to create
 * an empty file first.)
 *
 * @a result_checksum is the hex MD5 digest for the final fulltext
 * written to the stream.  It is ignored if null, but if not null, it
 * must match the checksum of the result; if it does not, then the @a
 * *contents_p call which detects the mismatch will return the error
 * @c SVN_ERR_CHECKSUM_MISMATCH.
 *
 * Do any necessary temporary allocation in @a pool.
 *
 * ### This is like svn_fs_apply_textdelta, but takes the text
 * straight.  It is currently used only by the loader, see
 * libsvn_repos/load.c.  It should accept a checksum, of course, which
 * would come from an (optional) header in the dump file.  See
 * http://subversion.tigris.org/issues/show_bug.cgi?id=1102 for more.
 */
svn_error_t *svn_fs_apply_text (svn_stream_t **contents_p,
                                svn_fs_root_t *root,
                                const char *path,
                                const char *result_checksum,
                                apr_pool_t *pool);


/** Check if the contents of two root/path combos have changed.
 *
 * Set @a *changed_p to 1 if the contents at @a path1 under @a root1 differ
 * from those at @a path2 under @a root2, or set it to 0 if they are the
 * same.  Both paths must exist under their respective roots, and both
 * roots must be in the same filesystem. 
 */
svn_error_t *svn_fs_contents_changed (svn_boolean_t *changed_p,
                                      svn_fs_root_t *root1,
                                      const char *path1,
                                      svn_fs_root_t *root2,
                                      const char *path2,
                                      apr_pool_t *pool);



/* Filesystem revisions.  */


/** Set @a *youngest_p to the number of the youngest revision in filesystem 
 * @a fs.  Use @a pool for all temporary allocation.
 *
 * The oldest revision in any filesystem is numbered zero.
 */
svn_error_t *svn_fs_youngest_rev (svn_revnum_t *youngest_p,
                                  svn_fs_t *fs,
                                  apr_pool_t *pool);


/** Deltify predecessors of paths modified in @a revision in
 * filesystem @a fs.  Use @a pool for all allocations. 
 * 
 * NOTE:  This can be a time-consuming process, depending the breadth
 * of the changes made in @a revision, and the depth of the history of
 * those changed paths. 
 */
svn_error_t *svn_fs_deltify_revision (svn_fs_t *fs,
                                      svn_revnum_t revision,
                                      apr_pool_t *pool);


/** Set @a *value_p to the value of the property named @a propname on
 * revision @a rev in the filesystem @a fs.  If @a rev has no property by 
 * that name, set @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *svn_fs_revision_prop (svn_string_t **value_p,
                                   svn_fs_t *fs,
                                   svn_revnum_t rev,
                                   const char *propname,
                                   apr_pool_t *pool);


/** Set @a *table_p to the entire property list of revision @a rev in
 * filesystem @a fs, as an APR hash table allocated in @a pool.  The table
 * maps <tt>char *</tt> property names to @c svn_string_t * values; the names
 * and values are allocated in @a pool.
 */
svn_error_t *svn_fs_revision_proplist (apr_hash_t **table_p,
                                       svn_fs_t *fs,
                                       svn_revnum_t rev,
                                       apr_pool_t *pool);


/** Change a revision's property's value, or add/delete a property.
 *
 * - @a fs is a filesystem, and @a rev is the revision in that filesystem
 *   whose property should change.
 * - @a name is the name of the property to change.
 * - @a VALUE is the new value of the property, or zero if the property should
 *   be removed altogether.
 *
 * Note that revision properties are non-historied --- you can change
 * them after the revision has been committed.  They are not protected
 * via transactions.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *svn_fs_change_rev_prop (svn_fs_t *fs,
                                     svn_revnum_t rev,
                                     const char *name,
                                     const svn_string_t *value,
                                     apr_pool_t *pool);



/* Computing deltas.  */


/** Set @a *stream_p to a pointer to a delta stream that will turn the
 * contents of the file @a source into the contents of the file @a target.
 * If @a source_root is zero, use a file with zero length as the source.
 *
 * This function does not compare the two files' properties.
 *
 * Allocate @a *stream_p, and do any necessary temporary allocation, in
 * @a pool.
 */
svn_error_t *svn_fs_get_file_delta_stream (svn_txdelta_stream_t **stream_p,
                                           svn_fs_root_t *source_root,
                                           const char *source_path,
                                           svn_fs_root_t *target_root,
                                           const char *target_path,
                                           apr_pool_t *pool);



/* UUID manipulation. */

/** Populate @a *uuid with the UUID associated with @a fs.  Allocate
    @a *uuid in @a pool.  */
svn_error_t *svn_fs_get_uuid (svn_fs_t *fs,
                              const char **uuid,
                              apr_pool_t *pool);


/** Associate @a *uuid with @a fs.  Use @a pool for any scratchwork. */
svn_error_t *svn_fs_set_uuid (svn_fs_t *fs,
                              const char *uuid,
                              apr_pool_t *pool);


/* Non-historical properties.  */

/* [[Yes, do tell.]] */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_FS_H */