- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# 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