svn_dirent_uri.h

Go to the documentation of this file.

/**
 * @copyright
 * ====================================================================
 *    Licensed to the Apache Software Foundation (ASF) under one
 *    or more contributor license agreements.  See the NOTICE file
 *    distributed with this work for additional information
 *    regarding copyright ownership.  The ASF licenses this file
 *    to you under the Apache License, Version 2.0 (the
 *    "License"); you may not use this file except in compliance
 *    with the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing,
 *    software distributed under the License is distributed on an
 *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *    KIND, either express or implied.  See the License for the
 *    specific language governing permissions and limitations
 *    under the License.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_dirent_uri.h
 * @brief A library to manipulate URIs, relative paths and directory entries.
 *
 * This library makes a clear distinction between several path formats:
 *
 *  - a dirent is a path on (local) disc or a UNC path (Windows) in
 *    either relative or absolute format.
 *    Examples:
 *       "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only), ""
 *    But not:
 *       "http://server"
 *
 *  - a uri, for our purposes, is a percent-encoded, absolute path
 *    (URI) that starts with a schema definition.  In practice, these
 *    tend to look like URLs, but never carry query strings.
 *    Examples:
 *       "http://server", "file:///path/to/repos",
 *       "svn+ssh://user@host:123/My%20Stuff/file.doc"
 *    But not:
 *       "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc", ""
 *
 *  - a relative path (relpath) is an unrooted path that can be joined
 *    to any other relative path, uri or dirent. A relative path is
 *    never rooted/prefixed by a '/'.
 *    Examples:
 *       "file", "dir/file", "dir/subdir/../file", ""
 *    But not:
 *       "/file", "http://server/file"
 *
 * This distinction is needed because on Windows we have to handle some
 * dirents and URIs differently. Since it's not possible to determine from
 * the path string if it's a dirent or a URI, it's up to the API user to
 * make this choice. See also issue #2028.
 *
 * All incoming and outgoing paths are non-NULL unless otherwise documented.
 *
 * All of these functions expect paths passed into them to be in canonical
 * form, except:
 *
 *    - @c svn_dirent_canonicalize()
 *    - @c svn_dirent_canonicalize_safe()
 *    - @c svn_dirent_is_canonical()
 *    - @c svn_dirent_internal_style()
 *    - @c svn_relpath_canonicalize()
 *    - @c svn_relpath_canonicalize_safe()
 *    - @c svn_relpath_is_canonical()
 *    - @c svn_uri_canonicalize()
 *    - @c svn_uri_canonicalize_safe()
 *    - @c svn_uri_is_canonical()
 *
 * The Subversion codebase also recognizes some other classes of path:
 *
 *  - A Subversion filesystem path (fspath) -- otherwise known as a
 *    path within a repository -- is a path relative to the root of
 *    the repository filesystem, that starts with a slash ("/").  The
 *    rules for a fspath are the same as for a relpath except for the
 *    leading '/'.  A fspath never ends with '/' except when the whole
 *    path is just '/'.  The fspath API is private (see
 *    private/svn_fspath.h).
 *
 *  - A URL path (urlpath) is just the path part of a URL (the part
 *    that follows the schema, username, hostname, and port).  These
 *    are also like relpaths, except that they have a leading slash
 *    (like fspaths) and are URI-encoded.  The urlpath API is also
 *    private (see private/svn_fspath.h)
 *    Example:
 *       "/svn/repos/trunk/README",
 *       "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"
 *
 * So, which path API is appropriate for your use-case?
 *
 *  - If your path refers to a local file, directory, symlink, etc. of
 *    the sort that you can examine and operate on with other software
 *    on your computer, it's a dirent.
 *
 *  - If your path is a full URL -- with a schema, hostname (maybe),
 *    and path portion -- it's a uri.
 *
 *  - If your path is relative, and is somewhat ambiguous unless it's
 *    joined to some other more explicit (possible absolute) base
 *    (such as a dirent or URL), it's a relpath.
 *
 *  - If your path is the virtual path of a versioned object inside a
 *    Subversion repository, it could be one of two different types of
 *    paths.  We'd prefer to use relpaths (relative to the root
 *    directory of the virtual repository filesystem) for that stuff,
 *    but some legacy code uses fspaths.  You'll need to figure out if
 *    your code expects repository paths to have a leading '/' or not.
 *    If so, they are fspaths; otherwise they are relpaths.
 *
 *  - If your path refers only to the path part of URL -- as if
 *    someone hacked off the initial schema and hostname portion --
 *    it's a urlpath.  To date, the ra_dav modules are the only ones
 *    within Subversion that make use of urlpaths, and this is because
 *    WebDAV makes heavy use of that form of path specification.
 *
 * When translating between local paths (dirents) and uris code should
 * always go via the relative path format, perhaps by truncating a
 * parent portion from a path with svn_*_skip_ancestor(), or by
 * converting portions to basenames and then joining to existing
 * paths.
 *
 * SECURITY WARNING: If a path that is received from an untrusted
 * source -- such as from the network -- is converted to a dirent it
 * should be tested with svn_dirent_is_under_root() before you can
 * assume the path to be a safe local path.
 *
 * MEMORY ALLOCATION: A function documented as allocating the result
 * in a pool may instead return a static string such as "." or "". If
 * the result is equal to an input, it will duplicate the input.
 */
 
#ifndef SVN_DIRENT_URI_H
#define SVN_DIRENT_URI_H
 
#include <apr.h>
#include <apr_pools.h>
#include <apr_tables.h>
 
#include "svn_types.h"
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 

/**
 * Convert @a dirent from the local style to the canonical internal style.
 * "Local style" means native path separators and "." for the empty path.
 *
 * Allocate the result in @a result_pool.
 *
 * @warning This function may call @c abort() if the @a dirent parameter
 *          is not a valid local-style path.
 *          Use svn_dirent_internal_style_safe() for tainted input.
 *
 * @since New in 1.6.
 */
const char *
svn_dirent_internal_style(const char *dirent,
                          apr_pool_t *result_pool);
 
/**
 * Convert @a dirent from the local style to the canonical internal style
 * and return it in @a *internal_style_dirent. "Local style" means native
 * path separators and "." for the empty path.
 *
 * Similar to svn_dirent_internal_style() (which see), but returns an error
 * if the @a dirent can not be canonicalized or of the result does not pass
 * the svn_dirent_is_canonical() test.
 *
 * If the function fails and @a non_canonical_result is not @c NULL, the
 * result of the failed canonicalization attempt (which may be @c NULL)
 * will be returned in @a *non_canonical_result.
 *
 * Allocates the results in @a result_pool. Uses @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_dirent_internal_style_safe(const char **internal_style_dirent,
                               const char **non_canonical_result,
                               const char *dirent,
                               apr_pool_t *result_pool,
                               apr_pool_t *scratch_pool);
 
/** Convert @a dirent from the internal style to the local style.
 * "Local style" means native path separators and "." for the empty path.
 * If the input is not canonical, the output may not be canonical.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
const char *
svn_dirent_local_style(const char *dirent,
                       apr_pool_t *result_pool);
 
/** Join a base dirent (@a base) with a component (@a component).
 *
 * If either @a base or @a component is the empty string, then the other
 * argument will be copied and returned.  If both are the empty string then
 * empty string is returned.
 *
 * If the @a component is an absolute dirent, then it is copied and returned.
 * The platform specific rules for joining paths are used to join the components.
 *
 * This function is NOT appropriate for native (local) file
 * dirents. Only for "internal" canonicalized dirents, since it uses '/'
 * for the separator.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
char *
svn_dirent_join(const char *base,
                const char *component,
                apr_pool_t *result_pool);
 
/** Join multiple components onto a @a base dirent. The components are
 * terminated by a @c SVN_VA_NULL.
 *
 * If any component is the empty string, it will be ignored.
 *
 * If any component is an absolute dirent, then it resets the base and
 * further components will be appended to it.
 *
 * See svn_dirent_join() for further notes about joining dirents.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
char *
svn_dirent_join_many(apr_pool_t *result_pool,
                     const char *base,
                     ...) SVN_NEEDS_SENTINEL_NULL;
 
/** Join a base relpath (@a base) with a component (@a component).
 * @a component need not be a single component.
 *
 * If either @a base or @a component is the empty path, then the other
 * argument will be copied and returned.  If both are the empty path the
 * empty path is returned.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
char *
svn_relpath_join(const char *base,
                 const char *component,
                 apr_pool_t *result_pool);
 
/** Gets the name of the specified canonicalized @a dirent as it is known
 * within its parent directory. If the @a dirent is root, return "". The
 * returned value will not have slashes in it.
 *
 * Example: svn_dirent_basename("/foo/bar") -> "bar"
 *
 * If @a result_pool is NULL, return a pointer to the basename in @a dirent,
 * otherwise allocate the result in @a result_pool.
 *
 * @note If an empty string is passed, then an empty string will be returned.
 *
 * @since New in 1.7.
 */
const char *
svn_dirent_basename(const char *dirent,
                    apr_pool_t *result_pool);
 
/** Get the dirname of the specified canonicalized @a dirent, defined as
 * the dirent with its basename removed.
 *
 * If @a dirent is root  ("/", "X:/", "//server/share/") or "", it is returned
 * unchanged.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
char *
svn_dirent_dirname(const char *dirent,
                   apr_pool_t *result_pool);
 
/** Divide the canonicalized @a dirent into @a *dirpath and @a *base_name.
 *
 * If @a dirpath or @a base_name is NULL, then don't set that one.
 *
 * Either @a dirpath or @a base_name may be @a dirent's own address, but they
 * may not both be the same address, or the results are undefined.
 *
 * If @a dirent has two or more components, the separator between @a dirpath
 * and @a base_name is not included in either of the new names.
 *
 * Examples:
 *             - <pre>"/foo/bar/baz"  ==>  "/foo/bar" and "baz"</pre>
 *             - <pre>"/bar"          ==>  "/"  and "bar"</pre>
 *             - <pre>"/"             ==>  "/"  and ""</pre>
 *             - <pre>"bar"           ==>  ""   and "bar"</pre>
 *             - <pre>""              ==>  ""   and ""</pre>
 *  Windows:   - <pre>"X:/"           ==>  "X:/" and ""</pre>
 *             - <pre>"X:/foo"        ==>  "X:/" and "foo"</pre>
 *             - <pre>"X:foo"         ==>  "X:" and "foo"</pre>
 *  Posix:     - <pre>"X:foo"         ==>  ""   and "X:foo"</pre>
 *
 * Allocate the results in @a result_pool.
 *
 * @since New in 1.7.
 */
void
svn_dirent_split(const char **dirpath,
                 const char **base_name,
                 const char *dirent,
                 apr_pool_t *result_pool);
 
/** Divide the canonicalized @a relpath into @a *dirpath and @a *base_name.
 *
 * If @a dirpath or @a base_name is NULL, then don't set that one.
 *
 * Either @a dirpath or @a base_name may be @a relpaths's own address, but
 * they may not both be the same address, or the results are undefined.
 *
 * If @a relpath has two or more components, the separator between @a dirpath
 * and @a base_name is not included in either of the new names.
 *
 *   examples:
 *             - <pre>"foo/bar/baz"  ==>  "foo/bar" and "baz"</pre>
 *             - <pre>"bar"          ==>  ""  and "bar"</pre>
 *             - <pre>""              ==>  ""   and ""</pre>
 *
 * Allocate the results in @a result_pool.
 *
 * @since New in 1.7.
 */
void
svn_relpath_split(const char **dirpath,
                  const char **base_name,
                  const char *relpath,
                  apr_pool_t *result_pool);
 
/** Get the basename of the specified canonicalized @a relpath.  The
 * basename is defined as the last component of the relpath.  If the @a
 * relpath has only one component then that is returned. The returned
 * value will have no slashes in it.
 *
 * Example: svn_relpath_basename("/trunk/foo/bar") -> "bar"
 *
 * If @a result_pool is NULL, return a pointer to the basename in @a relpath,
 * otherwise allocate the result in @a result_pool.
 *
 * @note If an empty string is passed, then an empty string will be returned.
 *
 * @since New in 1.7.
 */
const char *
svn_relpath_basename(const char *relpath,
                     apr_pool_t *result_pool);
 
/** Get the dirname of the specified canonicalized @a relpath, defined as
 * the relpath with its basename removed.
 *
 * If @a relpath is empty, "" is returned.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
char *
svn_relpath_dirname(const char *relpath,
                    apr_pool_t *result_pool);
 
/** Return a maximum of @a max_components components of @a relpath. This is
 * an efficient way of calling svn_relpath_dirname() multiple times until only
 * a specific number of components is left.
 *
 * Allocate the result in @a result_pool (or statically in case of 0)
 *
 * @since New in 1.9.
 */
const char *
svn_relpath_prefix(const char *relpath,
                   int max_components,
                   apr_pool_t *result_pool);
 
 
/** Divide the canonicalized @a uri into a uri @a *dirpath and a
 * (URI-decoded) relpath @a *base_name.
 *
 * If @a dirpath or @a base_name is NULL, then don't set that one.
 *
 * Either @a dirpath or @a base_name may be @a uri's own address, but they
 * may not both be the same address, or the results are undefined.
 *
 * If @a uri has two or more components, the separator between @a dirpath
 * and @a base_name is not included in either of the new names.
 *
 * Examples:
 *   - <pre>"http://server/foo/bar"  ==>  "http://server/foo" and "bar"</pre>
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
void
svn_uri_split(const char **dirpath,
              const char **base_name,
              const char *uri,
              apr_pool_t *result_pool);
 
/** Get the (URI-decoded) basename of the specified canonicalized @a
 * uri.  The basename is defined as the last component of the uri.  If
 * the @a uri is root, return "".  The returned value will have no
 * slashes in it.
 *
 * Example: svn_uri_basename("http://server/foo/bar") -> "bar"
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
const char *
svn_uri_basename(const char *uri,
                 apr_pool_t *result_pool);
 
/** Get the dirname of the specified canonicalized @a uri, defined as
 * the uri with its basename removed.
 *
 * If @a uri is root (e.g. "http://server"), it is returned
 * unchanged.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
char *
svn_uri_dirname(const char *uri,
                apr_pool_t *result_pool);
 
/** Return TRUE if @a dirent is considered absolute on the platform at
 * hand. E.g. '/foo' on Posix platforms or 'X:/foo', '//server/share/foo'
 * on Windows.
 *
 * @since New in 1.6.
 */
svn_boolean_t
svn_dirent_is_absolute(const char *dirent);
 
/** Return TRUE if @a dirent is considered a root directory on the platform
 * at hand.
 * E.g.:
 *  On Posix:   '/'
 *  On Windows: '/', 'X:/', '//server/share', 'X:'
 *
 * Note that on Windows '/' and 'X:' are roots, but paths starting with this
 * root are not absolute.
 *
 * @since New in 1.5.
 */
svn_boolean_t
svn_dirent_is_root(const char *dirent,
                   apr_size_t len);
 
/** Return TRUE if @a uri is a root URL (e.g., "http://server").
 *
 * @since New in 1.7
 */
svn_boolean_t
svn_uri_is_root(const char *uri,
                apr_size_t len);
 
/**
 * Return a new dirent like @a dirent, but transformed such that some types
 * of dirent specification redundancies are removed.
 *
 * This involves:
 *   - collapsing redundant "/./" elements
 *   - removing multiple adjacent separator characters
 *   - removing trailing separator characters
 *   - converting the server name of a UNC path to lower case (on Windows)
 *   - converting a drive letter to upper case (on Windows)
 *
 * and possibly other semantically inoperative transformations.
 *
 * Allocate the result in @a result_pool.
 *
 * @warning This function may call @c abort() if @a dirent can not be
 *          canonicalized.
 *          Use svn_dirent_canonicalize_safe() for tainted input.
 *
 * @since New in 1.6.
 */
const char *
svn_dirent_canonicalize(const char *dirent,
                        apr_pool_t *result_pool);
 
/**
 * Return a new @a *canonical_dirent like @a dirent, but transformed such
 * that some types of dirent specification redundancies are removed.
 *
 * Similar to svn_dirent_canonicalize() (which see), but returns an error
 * if the @a dirent can not be canonicalized or of the result does not pass
 * the svn_dirent_is_canonical() test.
 *
 * If the function fails and @a non_canonical_result is not @c NULL, the
 * result of the failed canonicalization attempt (which may be @c NULL)
 * will be returned in @a *non_canonical_result.
 *
 * Allocates the results in @a result_pool. Uses @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_dirent_canonicalize_safe(const char **canonical_dirent,
                             const char **non_canonical_result,
                             const char *dirent,
                             apr_pool_t *result_pool,
                             apr_pool_t *scratch_pool);
 
 
/**
 * Return a new relpath like @a relpath, but transformed such that some types
 * of relpath specification redundancies are removed.
 *
 * This involves:
 *   - collapsing redundant "/./" elements
 *   - removing multiple adjacent separator characters
 *   - removing trailing separator characters
 *
 * and possibly other semantically inoperative transformations.
 *
 * Allocate the result in @a result_pool.
 *
 * @warning This function may call @c abort() if @a relpath can not be
 *          canonicalized.
 *          Use svn_relpath_canonicalize_safe() for tainted input.
 *
 * @since New in 1.7.
 */
const char *
svn_relpath_canonicalize(const char *relpath,
                         apr_pool_t *result_pool);
 
/**
 * Return a new @a *canonical_relpath like @a relpath, but transformed such
 * that some types of relpath specification redundancies are removed.
 *
 * Similar to svn_relpath_canonicalize() (which see), but returns an error
 * if the @a relpath can not be canonicalized or of the result does not
 * pass the svn_relpath_is_canonical() test.
 *
 * If the function fails and @a non_canonical_result is not @c NULL, the
 * result of the failed canonicalization attempt (which may be @c NULL)
 * will be returned in @a *non_canonical_result.
 *
 * Allocates the results in @a result_pool. Uses @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.12.
 */
 
svn_error_t *
svn_relpath_canonicalize_safe(const char **canonical_relpath,
                              const char **non_canonical_result,
                              const char *relpath,
                              apr_pool_t *result_pool,
                              apr_pool_t *scratch_pool);
 
 
/**
 * Return a new uri like @a uri, but transformed such that some types
 * of uri specification redundancies are removed.
 *
 * This involves:
 *   - collapsing redundant "/./" elements
 *   - removing multiple adjacent separator characters
 *   - removing trailing separator characters
 *   - normalizing the escaping of the path component by unescaping
 *     characters that don't need escaping and escaping characters that do
 *     need escaping but weren't
 *   - removing the port number if it is the default port number (80 for
 *     http, 443 for https, 3690 for svn)
 *
 * and possibly other semantically inoperative transformations.
 *
 * Allocate the result in @a result_pool.
 *
 * @warning This function may call @c abort() if @a uri can not be
 *          canonicalized.
 *          Use svn_uri_canonicalize_safe() for tainted input.
 *
  * @since New in 1.7.
 */
const char *
svn_uri_canonicalize(const char *uri,
                     apr_pool_t *result_pool);
 
/**
 *  Return a new @a *canonical_uri like @a uri, but transformed such that
 * some types of uri specification redundancies are removed.
 *
 * Similar to svn_uri_canonicalize() (which see), but returns an error if
 * the @a uri can not be canonicalized or of the result does not pass the
 * svn_uri_is_canonical() test.
 *
 * If the function fails and @a non_canonical_result is not @c NULL, the
 * result of the failed canonicalization attempt (which may be @c NULL)
 * will be returned in @a *non_canonical_result.
 *
 * Allocates the results in @a result_pool. Uses @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_uri_canonicalize_safe(const char **canonical_uri,
                          const char **non_canonical_result,
                          const char *uri,
                          apr_pool_t *result_pool,
                          apr_pool_t *scratch_pool);
 
 
/** Return @c TRUE iff @a dirent is canonical.
 *
 * Use @a scratch_pool for temporary allocations.
 *
 * @note The test for canonicalization is currently defined as
 * "looks exactly the same as @c svn_dirent_canonicalize() would make
 * it look".
 *
 * @see svn_dirent_canonicalize()
 * @since New in 1.6.
 */
svn_boolean_t
svn_dirent_is_canonical(const char *dirent,
                        apr_pool_t *scratch_pool);
 
/** Return @c TRUE iff @a relpath is canonical.
 *
 * @see svn_relpath_canonicalize()
 * @since New in 1.7.
 */
svn_boolean_t
svn_relpath_is_canonical(const char *relpath);
 
/** Return @c TRUE iff @a uri is canonical.
 *
 * Use @a scratch_pool for temporary allocations.
 *
 * @see svn_uri_canonicalize()
 * @since New in 1.7.
 */
svn_boolean_t
svn_uri_is_canonical(const char *uri,
                     apr_pool_t *scratch_pool);
 
/** Return the longest common dirent shared by two canonicalized dirents,
 * @a dirent1 and @a dirent2.  If there's no common ancestor, return the
 * empty path.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
char *
svn_dirent_get_longest_ancestor(const char *dirent1,
                                const char *dirent2,
                                apr_pool_t *result_pool);
 
/** Return the longest common path shared by two relative paths,
 * @a relpath1 and @a relpath2.  If there's no common ancestor, return the
 * empty path.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
char *
svn_relpath_get_longest_ancestor(const char *relpath1,
                                 const char *relpath2,
                                 apr_pool_t *result_pool);
 
/** Return the longest common path shared by two canonicalized uris,
 * @a uri1 and @a uri2.  If there's no common ancestor, return the
 * empty path.  In order for two URLs to have a common ancestor, they
 * must (a) have the same protocol (since two URLs with the same path
 * but different protocols may point at completely different
 * resources), and (b) share a common ancestor in their path
 * component, i.e. 'protocol://' is not a sufficient ancestor.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
char *
svn_uri_get_longest_ancestor(const char *uri1,
                             const char *uri2,
                             apr_pool_t *result_pool);
 
/** Convert @a relative canonicalized dirent to an absolute dirent and
 * return the results in @a *pabsolute.
 * Raise SVN_ERR_BAD_FILENAME if the absolute dirent cannot be determined.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_dirent_get_absolute(const char **pabsolute,
                        const char *relative,
                        apr_pool_t *result_pool);
 
/** Similar to svn_dirent_skip_ancestor(), except that if @a child_dirent is
 * the same as @a parent_dirent, it is not considered a child, so the result
 * is @c NULL; an empty string is never returned.
 *
 * If @a result_pool is NULL, return a pointer into @a child_dirent, otherwise
 * allocate the result in @a result_pool.
 *
 * ### TODO: Deprecate, as the semantics are trivially
 * obtainable from *_skip_ancestor().
 *
 * @since New in 1.6.
 */
const char *
svn_dirent_is_child(const char *parent_dirent,
                    const char *child_dirent,
                    apr_pool_t *result_pool);
 
/** Return TRUE if @a parent_dirent is an ancestor of @a child_dirent or
 * the dirents are equal, and FALSE otherwise.
 *
 * ### TODO: Deprecate, as the semantics are trivially
 * obtainable from *_skip_ancestor().
 *
 * @since New in 1.6.
 */
svn_boolean_t
svn_dirent_is_ancestor(const char *parent_dirent,
                       const char *child_dirent);
 
/** Return TRUE if @a parent_uri is an ancestor of @a child_uri or
 * the uris are equal, and FALSE otherwise.
 */
svn_boolean_t
svn_uri__is_ancestor(const char *parent_uri,
                     const char *child_uri);
 
 
/** Return the relative path part of @a child_dirent that is below
 * @a parent_dirent, or just "" if @a parent_dirent is equal to
 * @a child_dirent. If @a child_dirent is not below or equal to
 * @a parent_dirent, return NULL.
 *
 * If one of @a parent_dirent and @a child_dirent is absolute and
 * the other relative, return NULL.
 *
 * @since New in 1.7.
 */
const char *
svn_dirent_skip_ancestor(const char *parent_dirent,
                         const char *child_dirent);
 
/** Return the relative path part of @a child_relpath that is below
 * @a parent_relpath, or just "" if @a parent_relpath is equal to
 * @a child_relpath. If @a child_relpath is not below @a parent_relpath,
 * return NULL.
 *
 * @since New in 1.7.
 */
const char *
svn_relpath_skip_ancestor(const char *parent_relpath,
                          const char *child_relpath);
 
/** Return the URI-decoded relative path of @a child_uri that is below
 * @a parent_uri, or just "" if @a parent_uri is equal to @a child_uri. If
 * @a child_uri is not below @a parent_uri, return NULL.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
const char *
svn_uri_skip_ancestor(const char *parent_uri,
                      const char *child_uri,
                      apr_pool_t *result_pool);
 
/** Find the common prefix of the canonicalized dirents in @a targets
 * (an array of <tt>const char *</tt>'s), and remove redundant dirents if @a
 * remove_redundancies is TRUE.
 *
 *   - Set @a *pcommon to the absolute dirent of the dirent common to
 *     all of the targets.  If the targets have no common prefix (e.g.
 *     "C:/file" and "D:/file" on Windows), set @a *pcommon to the empty
 *     string.
 *
 *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 *     to an array of targets relative to @a *pcommon, and if
 *     @a remove_redundancies is TRUE, omit any dirents that are
 *     descendants of another dirent in @a targets.  If *pcommon
 *     is empty, @a *pcondensed_targets will contain absolute dirents;
 *     redundancies can still be removed.  If @a pcondensed_targets is NULL,
 *     leave it alone.
 *
 * Else if there is exactly one target, then
 *
 *   - Set @a *pcommon to that target, and
 *
 *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 *     to an array containing zero elements.  Else if
 *     @a pcondensed_targets is NULL, leave it alone.
 *
 * If there are no items in @a targets, set @a *pcommon and (if
 * applicable) @a *pcondensed_targets to @c NULL.
 *
 * Allocate the results in @a result_pool. Use @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_dirent_condense_targets(const char **pcommon,
                            apr_array_header_t **pcondensed_targets,
                            const apr_array_header_t *targets,
                            svn_boolean_t remove_redundancies,
                            apr_pool_t *result_pool,
                            apr_pool_t *scratch_pool);
 
/** Find the common prefix of the canonicalized uris in @a targets
 * (an array of <tt>const char *</tt>'s), and remove redundant uris if @a
 * remove_redundancies is TRUE.
 *
 *   - Set @a *pcommon to the common base uri of all of the targets.
 *     If the targets have no common prefix (e.g. "http://srv1/file"
 *     and "http://srv2/file"), set @a *pcommon to the empty
 *     string.
 *
 *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 *     to an array of URI-decoded targets relative to @a *pcommon, and
 *     if @a remove_redundancies is TRUE, omit any uris that are
 *     descendants of another uri in @a targets.  If *pcommon is
 *     empty, @a *pcondensed_targets will contain absolute uris;
 *     redundancies can still be removed.  If @a pcondensed_targets is
 *     NULL, leave it alone.
 *
 * Else if there is exactly one target, then
 *
 *   - Set @a *pcommon to that target, and
 *
 *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 *     to an array containing zero elements.  Else if
 *     @a pcondensed_targets is NULL, leave it alone.
 *
 * If there are no items in @a targets, set @a *pcommon and (if
 * applicable) @a *pcondensed_targets to @c NULL.
 *
 * Allocate the results in @a result_pool. Use @a scratch_pool for
 * temporary allocations.
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_uri_condense_targets(const char **pcommon,
                         apr_array_header_t **pcondensed_targets,
                         const apr_array_header_t *targets,
                         svn_boolean_t remove_redundancies,
                         apr_pool_t *result_pool,
                         apr_pool_t *scratch_pool);
 
/** Join @a path onto @a base_path, checking that @a path does not attempt
 * to traverse above @a base_path. If @a path or any ".." component within
 * it resolves to a path above @a base_path, or if @a path is an absolute
 * path, then set @a *under_root to @c FALSE. Otherwise, set @a *under_root
 * to @c TRUE and, if @a result_path is not @c NULL, set @a *result_path to
 * the resulting path.
 *
 * @a path need not be canonical. @a base_path must be canonical and
 * @a *result_path will be canonical.
 *
 * Allocate the result in @a result_pool.
 *
 * @note Use of this function is strongly encouraged. Do not roll your own.
 * (http://cve.mitre.org/cgi-bin/cvename.cgi?name=2007-3846)
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_dirent_is_under_root(svn_boolean_t *under_root,
                         const char **result_path,
                         const char *base_path,
                         const char *path,
                         apr_pool_t *result_pool);
 
/** Set @a *dirent to the path corresponding to the file:// URL @a url, using
 * the platform-specific file:// rules.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_uri_get_dirent_from_file_url(const char **dirent,
                                 const char *url,
                                 apr_pool_t *result_pool);
 
/** Set @a *url to a file:// URL, corresponding to @a dirent using the
 * platform specific dirent and file:// rules.
 *
 * Allocate the result in @a result_pool.
 *
 * @since New in 1.7.
 */
svn_error_t *
svn_uri_get_file_url_from_dirent(const char **url,
                                 const char *dirent,
                                 apr_pool_t *result_pool);
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#endif /* SVN_DIRENT_URI_H */