Subversion
svn_dirent_uri.h
Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  *    Licensed to the Apache Software Foundation (ASF) under one
00005  *    or more contributor license agreements.  See the NOTICE file
00006  *    distributed with this work for additional information
00007  *    regarding copyright ownership.  The ASF licenses this file
00008  *    to you under the Apache License, Version 2.0 (the
00009  *    "License"); you may not use this file except in compliance
00010  *    with the License.  You may obtain a copy of the License at
00011  *
00012  *      http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  *    Unless required by applicable law or agreed to in writing,
00015  *    software distributed under the License is distributed on an
00016  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
00017  *    KIND, either express or implied.  See the License for the
00018  *    specific language governing permissions and limitations
00019  *    under the License.
00020  * ====================================================================
00021  * @endcopyright
00022  *
00023  * @file svn_dirent_uri.h
00024  * @brief A library to manipulate URIs, relative paths and directory entries.
00025  *
00026  * This library makes a clear distinction between several path formats:
00027  *
00028  *  - a dirent is a path on (local) disc or a UNC path (Windows) in
00029  *    either relative or absolute format.
00030  *    Examples:
00031  *       "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only)
00032  *    But not:
00033  *       "http://server"
00034  *
00035  * - a uri, for our purposes, is a percent-encoded, absolute path
00036  *    (URI) that starts with a schema definition.  In practice, these
00037  *    tend to look like URLs, but never carry query strings.
00038  *    Examples:
00039  *       "http://server", "file:///path/to/repos",
00040  *       "svn+ssh://user@host:123/My%20Stuff/file.doc"
00041  *    But not:
00042  *       "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc"
00043  *
00044  *  - a relative path (relpath) is an unrooted path that can be joined
00045  *    to any other relative path, uri or dirent. A relative path is
00046  *    never rooted/prefixed by a '/'.
00047  *    Examples:
00048  *       "file", "dir/file", "dir/subdir/../file"
00049  *    But not:
00050  *       "/file", "http://server/file"
00051  *
00052  * This distinction is needed because on Windows we have to handle some
00053  * dirents and URIs differently. Since it's not possible to determine from
00054  * the path string if it's a dirent or a URI, it's up to the API user to
00055  * make this choice. See also issue #2028.
00056  *
00057  * All of these functions expect paths passed into them to be in canonical
00058  * form, except:
00059  *
00060  *    - @c svn_dirent_canonicalize()
00061  *    - @c svn_dirent_is_canonical()
00062  *    - @c svn_dirent_internal_style()
00063  *    - @c svn_relpath_canonicalize()
00064  *    - @c svn_relpath_is_canonical()
00065  *    - @c svn_relpath__internal_style()
00066  *    - @c svn_uri_canonicalize()
00067  *    - @c svn_uri_is_canonical()
00068  *
00069  * The Subversion codebase also recognizes some other classes of path:
00070  *
00071  *  - A Subversion filesystem path (fspath) -- otherwise known as a
00072  *    path within a repository -- is a path relative to the root of
00073  *    the repository filesystem, that starts with a slash ("/").  The
00074  *    rules for a fspath are the same as for a relpath except for the
00075  *    leading '/'.  A fspath never ends with '/' except when the whole
00076  *    path is just '/'.  The fspath API is private (see
00077  *    private/svn_fspath.h).
00078  *
00079  *  - A URL path (urlpath) is just the path part of a URL (the part
00080  *    that follows the schema, username, hostname, and port).  These
00081  *    are also like relpaths, except that they have a leading slash
00082  *    (like fspaths) and are URI-encoded.  The urlpath API is also
00083  *    private (see private/svn_fspath.h)
00084  *    Example:
00085  *       "/svn/repos/trunk/README",
00086  *       "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"
00087  *
00088  * So, which path API is appropriate for your use-case?
00089  *
00090  *  - If your path refers to a local file, directory, symlink, etc. of
00091  *    the sort that you can examine and operate on with other software
00092  *    on your computer, it's a dirent.
00093  *
00094  *  - If your path is a full URL -- with a schema, hostname (maybe),
00095  *    and path portion -- it's a uri.
00096  *
00097  *  - If your path is relative, and is somewhat ambiguous unless it's
00098  *    joined to some other more explicit (possible absolute) base
00099  *    (such as a dirent or URL), it's a relpath.
00100  *
00101  *  - If your path is the virtual path of a versioned object inside a
00102  *    Subversion repository, it could be one of two different types of
00103  *    paths.  We'd prefer to use relpaths (relative to the root
00104  *    directory of the virtual repository filesystem) for that stuff,
00105  *    but some legacy code uses fspaths.  You'll need to figure out if
00106  *    your code expects repository paths to have a leading '/' or not.
00107  *    If so, they are fspaths; otherwise they are relpaths.
00108  *
00109  *  - If your path refers only to the path part of URL -- as if
00110  *    someone hacked off the initial schema and hostname portion --
00111  *    it's a urlpath.  To date, the ra_dav modules are the only ones
00112  *    within Subversion that make use of urlpaths, and this is because
00113  *    WebDAV makes heavy use of that form of path specification.
00114  *
00115  * When translating between local paths (dirents) and uris code should
00116  * always go via the relative path format, perhaps by truncating a
00117  * parent portion from a path with svn_*_skip_ancestor(), or by
00118  * converting portions to basenames and then joining to existing
00119  * paths.
00120  *
00121  * SECURITY WARNING: If a path that is received from an untrusted
00122  * source -- such as from the network -- is converted to a dirent it
00123  * should be tested with svn_dirent_is_under_root() before you can
00124  * assume the path to be a safe local path.
00125  */
00126 
00127 #ifndef SVN_DIRENT_URI_H
00128 #define SVN_DIRENT_URI_H
00129 
00130 #include <apr.h>
00131 #include <apr_pools.h>
00132 #include <apr_tables.h>
00133 
00134 #include "svn_types.h"
00135 
00136 #ifdef __cplusplus
00137 extern "C" {
00138 #endif /* __cplusplus */
00139 
00140 
00141 /** Convert @a dirent from the local style to the canonical internal style.
00142  * "Local style" means native path separators and "." for the empty path.
00143  *
00144  * @since New in 1.6.
00145  */
00146 const char *
00147 svn_dirent_internal_style(const char *dirent,
00148                           apr_pool_t *pool);
00149 
00150 /** Convert @a dirent from the internal style to the local style.
00151  * "Local style" means native path separators and "." for the empty path.
00152  * If the input is not canonical, the output may not be canonical.
00153  *
00154  * @since New in 1.6.
00155  */
00156 const char *
00157 svn_dirent_local_style(const char *dirent,
00158                        apr_pool_t *pool);
00159 
00160 /** Convert @a relpath from the local style to the canonical internal style.
00161  * "Local style" means native path separators and "." for the empty path.
00162  *
00163  * @since New in 1.7.
00164  */
00165 const char *
00166 svn_relpath__internal_style(const char *relpath,
00167                             apr_pool_t *pool);
00168 
00169 
00170 /** Join a base dirent (@a base) with a component (@a component), allocated in
00171  * @a pool.
00172  *
00173  * If either @a base or @a component is the empty string, then the other
00174  * argument will be copied and returned.  If both are the empty string then
00175  * empty string is returned.
00176  *
00177  * If the @a component is an absolute dirent, then it is copied and returned.
00178  * The platform specific rules for joining paths are used to join the components.
00179  *
00180  * This function is NOT appropriate for native (local) file
00181  * dirents. Only for "internal" canonicalized dirents, since it uses '/'
00182  * for the separator.
00183  *
00184  * @since New in 1.6.
00185  */
00186 char *
00187 svn_dirent_join(const char *base,
00188                 const char *component,
00189                 apr_pool_t *pool);
00190 
00191 /** Join multiple components onto a @a base dirent, allocated in @a pool. The
00192  * components are terminated by a @c NULL.
00193  *
00194  * If any component is the empty string, it will be ignored.
00195  *
00196  * If any component is an absolute dirent, then it resets the base and
00197  * further components will be appended to it.
00198  *
00199  * See svn_dirent_join() for further notes about joining dirents.
00200  *
00201  * @since New in 1.6.
00202  */
00203 char *
00204 svn_dirent_join_many(apr_pool_t *pool,
00205                      const char *base,
00206                      ...);
00207 
00208 /** Join a base relpath (@a base) with a component (@a component), allocating
00209  * the result in @a pool. @a component need not be a single component.
00210  *
00211  * If either @a base or @a component is the empty path, then the other
00212  * argument will be copied and returned.  If both are the empty path the
00213  * empty path is returned.
00214  *
00215  * @since New in 1.7.
00216  */
00217 char *
00218 svn_relpath_join(const char *base,
00219                  const char *component,
00220                  apr_pool_t *pool);
00221 
00222 /** Gets the name of the specified canonicalized @a dirent as it is known
00223  * within its parent directory. If the @a dirent is root, return "". The
00224  * returned value will not have slashes in it.
00225  *
00226  * Example: svn_dirent_basename("/foo/bar") -> "bar"
00227  *
00228  * The returned basename will be allocated in @a pool. If @a pool is NULL
00229  * a pointer to the basename in @a dirent is returned.
00230  *
00231  * @note If an empty string is passed, then an empty string will be returned.
00232  *
00233  * @since New in 1.7.
00234  */
00235 const char *
00236 svn_dirent_basename(const char *dirent,
00237                     apr_pool_t *pool);
00238 
00239 /** Get the dirname of the specified canonicalized @a dirent, defined as
00240  * the dirent with its basename removed.
00241  *
00242  * If @a dirent is root  ("/", "X:/", "//server/share/") or "", it is returned
00243  * unchanged.
00244  *
00245  * The returned dirname will be allocated in @a pool.
00246  *
00247  * @since New in 1.6.
00248  */
00249 char *
00250 svn_dirent_dirname(const char *dirent,
00251                    apr_pool_t *pool);
00252 
00253 /** Divide the canonicalized @a dirent into @a *dirpath and @a
00254  * *base_name, allocated in @a pool.
00255  *
00256  * If @a dirpath or @a base_name is NULL, then don't set that one.
00257  *
00258  * Either @a dirpath or @a base_name may be @a dirent's own address, but they
00259  * may not both be the same address, or the results are undefined.
00260  *
00261  * If @a dirent has two or more components, the separator between @a dirpath
00262  * and @a base_name is not included in either of the new names.
00263  *
00264  * Examples:
00265  *             - <pre>"/foo/bar/baz"  ==>  "/foo/bar" and "baz"</pre>
00266  *             - <pre>"/bar"          ==>  "/"  and "bar"</pre>
00267  *             - <pre>"/"             ==>  "/"  and ""</pre>
00268  *             - <pre>"bar"           ==>  ""   and "bar"</pre>
00269  *             - <pre>""              ==>  ""   and ""</pre>
00270  *  Windows:   - <pre>"X:/"           ==>  "X:/" and ""</pre>
00271  *             - <pre>"X:/foo"        ==>  "X:/" and "foo"</pre>
00272  *             - <pre>"X:foo"         ==>  "X:" and "foo"</pre>
00273  *  Posix:     - <pre>"X:foo"         ==>  ""   and "X:foo"</pre>
00274  *
00275  * @since New in 1.7.
00276  */
00277 void
00278 svn_dirent_split(const char **dirpath,
00279                  const char **base_name,
00280                  const char *dirent,
00281                  apr_pool_t *pool);
00282 
00283 /** Divide the canonicalized @a relpath into @a *dirpath and @a
00284  * *base_name, allocated in @a pool.
00285  *
00286  * If @a dirpath or @a base_name is NULL, then don't set that one.
00287  *
00288  * Either @a dirpath or @a base_name may be @a relpaths's own address, but
00289  * they may not both be the same address, or the results are undefined.
00290  *
00291  * If @a relpath has two or more components, the separator between @a dirpath
00292  * and @a base_name is not included in either of the new names.
00293  *
00294  *   examples:
00295  *             - <pre>"foo/bar/baz"  ==>  "foo/bar" and "baz"</pre>
00296  *             - <pre>"bar"          ==>  ""  and "bar"</pre>
00297  *             - <pre>""              ==>  ""   and ""</pre>
00298  *
00299  * @since New in 1.7.
00300  */
00301 void
00302 svn_relpath_split(const char **dirpath,
00303                   const char **base_name,
00304                   const char *relpath,
00305                   apr_pool_t *pool);
00306 
00307 /** Get the basename of the specified canonicalized @a relpath.  The
00308  * basename is defined as the last component of the relpath.  If the @a
00309  * relpath has only one component then that is returned. The returned
00310  * value will have no slashes in it.
00311  *
00312  * Example: svn_relpath_basename("/trunk/foo/bar") -> "bar"
00313  *
00314  * The returned basename will be allocated in @a pool. If @a
00315  * pool is NULL a pointer to the basename in @a relpath is returned.
00316  *
00317  * @note If an empty string is passed, then an empty string will be returned.
00318  *
00319  * @since New in 1.7.
00320  */
00321 const char *
00322 svn_relpath_basename(const char *relpath,
00323                      apr_pool_t *pool);
00324 
00325 /** Get the dirname of the specified canonicalized @a relpath, defined as
00326  * the relpath with its basename removed.
00327  *
00328  * If @a relpath is empty, "" is returned.
00329  *
00330  * The returned relpath will be allocated in @a pool.
00331  *
00332  * @since New in 1.7.
00333  */
00334 char *
00335 svn_relpath_dirname(const char *relpath,
00336                     apr_pool_t *pool);
00337 
00338 
00339 /** Divide the canonicalized @a uri into a uri @a *dirpath and a
00340  * (URI-decoded) relpath @a *base_name, allocated in @a pool.
00341  *
00342  * If @a dirpath or @a base_name is NULL, then don't set that one.
00343  *
00344  * Either @a dirpath or @a base_name may be @a uri's own address, but they
00345  * may not both be the same address, or the results are undefined.
00346  *
00347  * If @a uri has two or more components, the separator between @a dirpath
00348  * and @a base_name is not included in either of the new names.
00349  *
00350  * Examples:
00351  *   - <pre>"http://server/foo/bar"  ==>  "http://server/foo" and "bar"</pre>
00352  *
00353  * @since New in 1.7.
00354  */
00355 void
00356 svn_uri_split(const char **dirpath,
00357               const char **base_name,
00358               const char *uri,
00359               apr_pool_t *pool);
00360 
00361 /** Get the (URI-decoded) basename of the specified canonicalized @a
00362  * uri.  The basename is defined as the last component of the uri.  If
00363  * the @a uri is root then that is returned.  Otherwise, the returned
00364  * value will have no slashes in it.
00365  *
00366  * Example: svn_uri_basename("http://server/foo/bar") -> "bar"
00367  *
00368  * The returned basename will be allocated in @a pool.
00369  *
00370  * @since New in 1.7.
00371  */
00372 const char *
00373 svn_uri_basename(const char *uri,
00374                  apr_pool_t *pool);
00375 
00376 /** Get the dirname of the specified canonicalized @a uri, defined as
00377  * the uri with its basename removed.
00378  *
00379  * If @a uri is root (e.g. "http://server"), it is returned
00380  * unchanged.
00381  *
00382  * The returned dirname will be allocated in @a pool.
00383  *
00384  * @since New in 1.7.
00385  */
00386 char *
00387 svn_uri_dirname(const char *uri,
00388                 apr_pool_t *pool);
00389 
00390 /** Return TRUE if @a dirent is considered absolute on the platform at
00391  * hand. E.g. '/foo' on Posix platforms or 'X:/foo', '//server/share/foo'
00392  * on Windows.
00393  *
00394  * @since New in 1.6.
00395  */
00396 svn_boolean_t
00397 svn_dirent_is_absolute(const char *dirent);
00398 
00399 /** Return TRUE if @a dirent is considered a root directory on the platform
00400  * at hand.
00401  * E.g.:
00402  *  On Posix:   '/'
00403  *  On Windows: '/', 'X:/', '//server/share', 'X:'
00404  *
00405  * Note that on Windows '/' and 'X:' are roots, but paths starting with this
00406  * root are not absolute.
00407  *
00408  * @since New in 1.5.
00409  */
00410 svn_boolean_t
00411 svn_dirent_is_root(const char *dirent,
00412                    apr_size_t len);
00413 
00414 /** Return TRUE if @a uri is a root URL (e.g., "http://server").
00415  *
00416  * @since New in 1.7
00417  */
00418 svn_boolean_t
00419 svn_uri_is_root(const char *uri,
00420                 apr_size_t len);
00421 
00422 /** Return a new dirent like @a dirent, but transformed such that some types
00423  * of dirent specification redundancies are removed.
00424  *
00425  * This involves:
00426  *   - collapsing redundant "/./" elements
00427  *   - removing multiple adjacent separator characters
00428  *   - removing trailing separator characters
00429  *   - converting the server name of a UNC path to lower case (on Windows)
00430  *   - converting a drive letter to upper case (on Windows)
00431  *
00432  * and possibly other semantically inoperative transformations.
00433  *
00434  * The returned dirent may be allocated statically or from @a pool.
00435  *
00436  * @since New in 1.6.
00437  */
00438 const char *
00439 svn_dirent_canonicalize(const char *dirent,
00440                         apr_pool_t *pool);
00441 
00442 
00443 /** Return a new relpath like @a relpath, but transformed such that some types
00444  * of relpath specification redundancies are removed.
00445  *
00446  * This involves:
00447  *   - collapsing redundant "/./" elements
00448  *   - removing multiple adjacent separator characters
00449  *   - removing trailing separator characters
00450  *
00451  * and possibly other semantically inoperative transformations.
00452  *
00453  * The returned relpath may be allocated statically or from @a pool.
00454  *
00455  * @since New in 1.7.
00456  */
00457 const char *
00458 svn_relpath_canonicalize(const char *relpath,
00459                          apr_pool_t *pool);
00460 
00461 
00462 /** Return a new uri like @a uri, but transformed such that some types
00463  * of uri specification redundancies are removed.
00464  *
00465  * This involves:
00466  *   - collapsing redundant "/./" elements
00467  *   - removing multiple adjacent separator characters
00468  *   - removing trailing separator characters
00469  *   - normalizing the escaping of the path component by unescaping
00470  *     characters that don't need escaping and escaping characters that do
00471  *     need escaping but weren't
00472  *   - removing the port number if it is the default port number (80 for
00473  *     http, 443 for https, 3690 for svn)
00474  *
00475  * and possibly other semantically inoperative transformations.
00476  *
00477  * The returned uri may be allocated statically or from @a pool.
00478  *
00479  * @since New in 1.7.
00480  */
00481 const char *
00482 svn_uri_canonicalize(const char *uri,
00483                      apr_pool_t *pool);
00484 
00485 /** Return @c TRUE iff @a dirent is canonical.  Use @a pool for temporary
00486  * allocations.
00487  *
00488  * @note The test for canonicalization is currently defined as
00489  * "looks exactly the same as @c svn_dirent_canonicalize() would make
00490  * it look".
00491  *
00492  * @see svn_dirent_canonicalize()
00493  * @since New in 1.6.
00494  */
00495 svn_boolean_t
00496 svn_dirent_is_canonical(const char *dirent,
00497                         apr_pool_t *pool);
00498 
00499 /** Return @c TRUE iff @a relpath is canonical.
00500  *
00501  * @see svn_relpath_canonicalize()
00502  * @since New in 1.7.
00503  */
00504 svn_boolean_t
00505 svn_relpath_is_canonical(const char *relpath);
00506 
00507 /** Return @c TRUE iff @a uri is canonical.  Use @a pool for temporary
00508  * allocations.
00509  *
00510  * @see svn_uri_canonicalize()
00511  * @since New in 1.7.
00512  */
00513 svn_boolean_t
00514 svn_uri_is_canonical(const char *uri,
00515                      apr_pool_t *pool);
00516 
00517 /** Return the longest common dirent shared by two canonicalized dirents,
00518  * @a dirent1 and @a dirent2.  If there's no common ancestor, return the
00519  * empty path.
00520  *
00521  * @since New in 1.6.
00522  */
00523 char *
00524 svn_dirent_get_longest_ancestor(const char *dirent1,
00525                                 const char *dirent2,
00526                                 apr_pool_t *pool);
00527 
00528 /** Return the longest common path shared by two relative paths,
00529  * @a relpath1 and @a relpath2.  If there's no common ancestor, return the
00530  * empty path.
00531  *
00532  * @since New in 1.7.
00533  */
00534 char *
00535 svn_relpath_get_longest_ancestor(const char *relpath1,
00536                                  const char *relpath2,
00537                                  apr_pool_t *pool);
00538 
00539 /** Return the longest common path shared by two canonicalized uris,
00540  * @a uri1 and @a uri2.  If there's no common ancestor, return the
00541  * empty path.  In order for two URLs to have a common ancestor, they
00542  * must (a) have the same protocol (since two URLs with the same path
00543  * but different protocols may point at completely different
00544  * resources), and (b) share a common ancestor in their path
00545  * component, i.e. 'protocol://' is not a sufficient ancestor.
00546  *
00547  * @since New in 1.7.
00548  */
00549 char *
00550 svn_uri_get_longest_ancestor(const char *uri1,
00551                              const char *uri2,
00552                              apr_pool_t *pool);
00553 
00554 /** Convert @a relative canonicalized dirent to an absolute dirent and
00555  * return the results in @a *pabsolute, allocated in @a pool.
00556  * Raise SVN_ERR_BAD_FILENAME if the absolute dirent cannot be determined.
00557  *
00558  * @since New in 1.6.
00559  */
00560 svn_error_t *
00561 svn_dirent_get_absolute(const char **pabsolute,
00562                         const char *relative,
00563                         apr_pool_t *pool);
00564 
00565 /** Similar to svn_uri_skip_ancestor(), except that if @a child_uri is
00566  * the same as @a parent_uri, it is not considered a child, so the result
00567  * is @c NULL; an empty string is never returned.
00568  */
00569 const char *
00570 svn_uri__is_child(const char *parent_uri,
00571                   const char *child_uri,
00572                   apr_pool_t *pool);
00573 
00574 /** Similar to svn_dirent_skip_ancestor(), except that if @a child_dirent is
00575  * the same as @a parent_dirent, it is not considered a child, so the result
00576  * is @c NULL; an empty string is never returned.
00577  *
00578  * ### TODO: Deprecate, as the semantics are trivially
00579  * obtainable from *_skip_ancestor().
00580  *
00581  * @since New in 1.6.
00582  */
00583 const char *
00584 svn_dirent_is_child(const char *parent_dirent,
00585                     const char *child_dirent,
00586                     apr_pool_t *pool);
00587 
00588 /** Similar to svn_relpath_skip_ancestor(), except that if @a child_relpath is
00589  * the same as @a parent_relpath, it is not considered a child, so the result
00590  * is @c NULL; an empty string is never returned.
00591  */
00592 const char *
00593 svn_relpath__is_child(const char *parent_relpath,
00594                       const char *child_relpath,
00595                       apr_pool_t *pool);
00596 
00597 /** Return TRUE if @a parent_dirent is an ancestor of @a child_dirent or
00598  * the dirents are equal, and FALSE otherwise.
00599  *
00600  * ### TODO: Deprecate, as the semantics are trivially
00601  * obtainable from *_skip_ancestor().
00602  *
00603  * @since New in 1.6.
00604  */
00605 svn_boolean_t
00606 svn_dirent_is_ancestor(const char *parent_dirent,
00607                        const char *child_dirent);
00608 
00609 /** Return TRUE if @a parent_relpath is an ancestor of @a child_relpath or
00610  * the relpaths are equal, and FALSE otherwise.
00611  */
00612 svn_boolean_t
00613 svn_relpath__is_ancestor(const char *parent_relpath,
00614                          const char *child_relpath);
00615 
00616 /** Return TRUE if @a parent_uri is an ancestor of @a child_uri or
00617  * the uris are equal, and FALSE otherwise.
00618  */
00619 svn_boolean_t
00620 svn_uri__is_ancestor(const char *parent_uri,
00621                      const char *child_uri);
00622 
00623 
00624 /** Return the relative path part of @a child_dirent that is below
00625  * @a parent_dirent, or just "" if @a parent_dirent is equal to
00626  * @a child_dirent. If @a child_dirent is not below or equal to
00627  * @a parent_dirent, return NULL.
00628  *
00629  * If one of @a parent_dirent and @a child_dirent is absolute and
00630  * the other relative, return NULL.
00631  *
00632  * @since New in 1.7.
00633  */
00634 const char *
00635 svn_dirent_skip_ancestor(const char *parent_dirent,
00636                          const char *child_dirent);
00637 
00638 /** Return the relative path part of @a child_relpath that is below
00639  * @a parent_relpath, or just "" if @a parent_relpath is equal to
00640  * @a child_relpath. If @a child_relpath is not below or equal to
00641  * @a parent_relpath, return NULL.
00642  *
00643  * @since New in 1.7.
00644  */
00645 const char *
00646 svn_relpath_skip_ancestor(const char *parent_relpath,
00647                           const char *child_relpath);
00648 
00649 /** Return the URI-decoded relative path of @a child_uri that is below
00650  * @a parent_uri, or just "" if @a parent_uri is equal to @a child_uri. If
00651  * @a child_uri is not below or equal to @a parent_uri, return NULL.
00652  * Allocate the result in @a result_pool.
00653  *
00654  * @since New in 1.7.
00655  */
00656 const char *
00657 svn_uri_skip_ancestor(const char *parent_uri,
00658                       const char *child_uri,
00659                       apr_pool_t *result_pool);
00660 
00661 /** Find the common prefix of the canonicalized dirents in @a targets
00662  * (an array of <tt>const char *</tt>'s), and remove redundant dirents if @a
00663  * remove_redundancies is TRUE.
00664  *
00665  *   - Set @a *pcommon to the absolute dirent of the dirent common to
00666  *     all of the targets.  If the targets have no common prefix (e.g.
00667  *     "C:/file" and "D:/file" on Windows), set @a *pcommon to the empty
00668  *     string.
00669  *
00670  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
00671  *     to an array of targets relative to @a *pcommon, and if
00672  *     @a remove_redundancies is TRUE, omit any dirents that are
00673  *     descendants of another dirent in @a targets.  If *pcommon
00674  *     is empty, @a *pcondensed_targets will contain absolute dirents;
00675  *     redundancies can still be removed.  If @a pcondensed_targets is NULL,
00676  *     leave it alone.
00677  *
00678  * Else if there is exactly one target, then
00679  *
00680  *   - Set @a *pcommon to that target, and
00681  *
00682  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
00683  *     to an array containing zero elements.  Else if
00684  *     @a pcondensed_targets is NULL, leave it alone.
00685  *
00686  * If there are no items in @a targets, set @a *pcommon and (if
00687  * applicable) @a *pcondensed_targets to @c NULL.
00688  *
00689  * Allocates @a *pcommon and @a *targets in @a result_pool. All
00690  * intermediate allocations will be performed in @a scratch_pool.
00691  *
00692  * @since New in 1.7.
00693  */
00694 svn_error_t *
00695 svn_dirent_condense_targets(const char **pcommon,
00696                             apr_array_header_t **pcondensed_targets,
00697                             const apr_array_header_t *targets,
00698                             svn_boolean_t remove_redundancies,
00699                             apr_pool_t *result_pool,
00700                             apr_pool_t *scratch_pool);
00701 
00702 /** Find the common prefix of the canonicalized uris in @a targets
00703  * (an array of <tt>const char *</tt>'s), and remove redundant uris if @a
00704  * remove_redundancies is TRUE.
00705  *
00706  *   - Set @a *pcommon to the common base uri of all of the targets.
00707  *     If the targets have no common prefix (e.g. "http://srv1/file"
00708  *     and "http://srv2/file"), set @a *pcommon to the empty
00709  *     string.
00710  *
00711  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
00712  *     to an array of URI-decoded targets relative to @a *pcommon, and
00713  *     if @a remove_redundancies is TRUE, omit any uris that are
00714  *     descendants of another uri in @a targets.  If *pcommon is
00715  *     empty, @a *pcondensed_targets will contain absolute uris;
00716  *     redundancies can still be removed.  If @a pcondensed_targets is
00717  *     NULL, leave it alone.
00718  *
00719  * Else if there is exactly one target, then
00720  *
00721  *   - Set @a *pcommon to that target, and
00722  *
00723  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
00724  *     to an array containing zero elements.  Else if
00725  *     @a pcondensed_targets is NULL, leave it alone.
00726  *
00727  * If there are no items in @a targets, set @a *pcommon and (if
00728  * applicable) @a *pcondensed_targets to @c NULL.
00729  *
00730  * Allocate @a *pcommon and @a *targets in @a result_pool. Temporary
00731  * allocations will be performed in @a scratch_pool.
00732  *
00733  * @since New in 1.7.
00734  */
00735 svn_error_t *
00736 svn_uri_condense_targets(const char **pcommon,
00737                          apr_array_header_t **pcondensed_targets,
00738                          const apr_array_header_t *targets,
00739                          svn_boolean_t remove_redundancies,
00740                          apr_pool_t *result_pool,
00741                          apr_pool_t *scratch_pool);
00742 
00743 /** Join @a path onto @a base_path, checking that @a path does not attempt
00744  * to traverse above @a base_path. If @a path or any ".." component within
00745  * it resolves to a path above @a base_path, or if @a path is an absolute
00746  * path, then set @a *under_root to @c FALSE. Otherwise, set @a *under_root
00747  * to @c TRUE and, if @a result_path is not @c NULL, set @a *result_path to
00748  * the resulting path, allocated in @a result_pool.
00749  *
00750  * @a path need not be canonical. @a base_path must be canonical and
00751  * @a *result_path will be canonical.
00752  *
00753  * Note: Use of this function is strongly encouraged. Do not roll your own.
00754  * (http://cve.mitre.org/cgi-bin/cvename.cgi?name=2007-3846)
00755  *
00756  * @since New in 1.7.
00757  */
00758 svn_error_t *
00759 svn_dirent_is_under_root(svn_boolean_t *under_root,
00760                          const char **result_path,
00761                          const char *base_path,
00762                          const char *path,
00763                          apr_pool_t *result_pool);
00764 
00765 /** Set @a *dirent to the path corresponding to the file:// URL @a url, using
00766  * the platform-specific file:// rules.
00767  *
00768  * @since New in 1.7.
00769  */
00770 svn_error_t *
00771 svn_uri_get_dirent_from_file_url(const char **dirent,
00772                                  const char *url,
00773                                  apr_pool_t *pool);
00774 
00775 /** Set @a *url to a file:// URL, corresponding to @a dirent using the
00776  * platform specific dirent and file:// rules.
00777  *
00778  * @since New in 1.7.
00779  */
00780 svn_error_t *
00781 svn_uri_get_file_url_from_dirent(const char **url,
00782                                  const char *dirent,
00783                                  apr_pool_t *pool);
00784 
00785 #ifdef __cplusplus
00786 }
00787 #endif /* __cplusplus */
00788 
00789 #endif /* SVN_DIRENT_URI_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines