Subversion 1.6.16

svn_dirent_uri.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2008 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_dirent_uri.h
00019  * @brief A library to manipulate URIs and directory entries.
00020  *
00021  * This library makes a clear distinction between directory entries (dirents)
00022  * and URIs where:
00023  *  - a dirent is a path on (local) disc or a UNC path (Windows)
00024  *    examples: "/foo/bar", "X:/temp", "//server/share"
00025  *  - a URI is a path in a repository or a URL
00026  *    examples: "/trunk/README", "http://hostname/svn/repos"
00027  *
00028  * This distinction is needed because on Windows we have to handle some
00029  * dirents and URIs differently. Since it's not possible to determine from
00030  * the path string if it's a dirent or a URI, it's up to the API user to
00031  * make this choice. See also issue #2028.
00032  *
00033  * Nearly all the @c svn_dirent_xxx functions expect paths passed into them
00034  * to be in canonical form.  The only functions which do *not* have such 
00035  * expectations are:
00036  *
00037  *    - @c svn_dirent_canonicalize()
00038  *    - @c svn_dirent_is_canonical()
00039  *    - @c svn_dirent_internal_style()
00040  *    - @c svn_dirent_local_style()
00041  *
00042  * ### TODO: add description in line with svn_path.h, once more functions
00043  * are moved.
00044  * ### END TODO
00045  */
00046 
00047 #ifndef SVN_DIRENT_URI_H
00048 #define SVN_DIRENT_URI_H
00049 
00050 #include <apr.h>
00051 #include <apr_pools.h>
00052 #include <apr_tables.h>
00053 
00054 #include "svn_types.h"
00055 
00056 #ifdef __cplusplus
00057 extern "C" {
00058 #endif /* __cplusplus */
00059 
00060 
00061 /** Convert @a dirent from the local style to the canonical internal style.
00062  *
00063  * @since New in 1.6.
00064  */
00065 const char *
00066 svn_dirent_internal_style(const char *dirent,
00067                           apr_pool_t *pool);
00068 
00069 /** Convert @a dirent from the canonical internal style to the local style.
00070  *
00071  * @since New in 1.6.
00072  */
00073 const char *
00074 svn_dirent_local_style(const char *dirent,
00075                        apr_pool_t *pool);
00076 
00077 /** Join a base dirent (@a base) with a component (@a component), allocated in
00078  * @a pool.
00079  *
00080  * If either @a base or @a component is the empty string, then the other
00081  * argument will be copied and returned.  If both are the empty string then
00082  * empty string is returned.
00083  *
00084  * If the @a component is an absolute dirent, then it is copied and returned.
00085  * The platform specific rules for joining paths are used to join the components.
00086  *
00087  * This function is NOT appropriate for native (local) file
00088  * dirents. Only for "internal" canonicalized dirents, since it uses '/'
00089  * for the separator.
00090  *
00091  * @since New in 1.6.
00092  */
00093 char *
00094 svn_dirent_join(const char *base,
00095                 const char *component,
00096                 apr_pool_t *pool);
00097 
00098 /** Join multiple components onto a @a base dirent, allocated in @a pool. The
00099  * components are terminated by a @c NULL.
00100  *
00101  * If any component is the empty string, it will be ignored.
00102  *
00103  * If any component is an absolute dirent, then it resets the base and
00104  * further components will be appended to it.
00105  *
00106  * See svn_dirent_join() for further notes about joining dirents.
00107  *
00108  * @since New in 1.6.
00109  */
00110 char *
00111 svn_dirent_join_many(apr_pool_t *pool,
00112                      const char *base,
00113                      ...);
00114 
00115 /** Get the dirname of the specified canonicalized @a dirent, defined as
00116  * the dirent with its basename removed.
00117  *
00118  * If @a dirent is root  ("/", "X:/", "//server/share/"), it is returned
00119  * unchanged.
00120  *
00121  * The returned dirname will be allocated in @a pool.
00122  *
00123  * @since New in 1.6.
00124  */
00125 char *
00126 svn_dirent_dirname(const char *dirent,
00127                    apr_pool_t *pool);
00128 
00129 /** Return TRUE if @a dirent is considered absolute on the platform at
00130  * hand. E.g. '/foo' on posix or 'X:/foo', '//server/share/foo' 
00131  * on Windows.
00132  *
00133  * @since New in 1.6.
00134  */
00135 svn_boolean_t
00136 svn_dirent_is_absolute(const char *dirent);
00137 
00138 /** Return TRUE if @a dirent is considered a root directory on the platform
00139  * at hand. E.g. '/' on posix platforms or 'X:/', '//server/share'
00140  * on Windows.
00141  *
00142  * @since New in 1.5.
00143  */
00144 svn_boolean_t
00145 svn_dirent_is_root(const char *dirent,
00146                    apr_size_t len);
00147 
00148 /** Return a new dirent like @a dirent, but transformed such that some types
00149  * of dirent specification redundancies are removed.
00150  *
00151  * This involves collapsing redundant "/./" elements, removing
00152  * multiple adjacent separator characters, removing trailing
00153  * separator characters, and possibly other semantically inoperative
00154  * transformations.
00155  *
00156  * Convert the server name of UNC paths lowercase on Windows.
00157  *
00158  * The returned dirent may be statically allocated, equal to @a dirent, or
00159  * allocated from @a pool.
00160  *
00161  * @since New in 1.6.
00162  */
00163 const char *
00164 svn_dirent_canonicalize(const char *dirent,
00165                         apr_pool_t *pool);
00166 
00167 /** Return @c TRUE iff @a dirent is canonical.  Use @a pool for temporary
00168  * allocations.
00169  *
00170  * @note The test for canonicalization is currently defined as
00171  * "looks exactly the same as @c svn_dirent_canonicalize() would make
00172  * it look".
00173  *
00174  * @since New in 1.6.
00175  */
00176 svn_boolean_t
00177 svn_dirent_is_canonical(const char *dirent,
00178                         apr_pool_t *pool);
00179 
00180 /** Return the longest common dirent shared by two canonicalized dirents,
00181  * @a dirent1 and @a dirent2.  If there's no common ancestor, return the
00182  * empty path.
00183  *
00184  * @since New in 1.6.
00185  */
00186 char *
00187 svn_dirent_get_longest_ancestor(const char *dirent1,
00188                                 const char *dirent2,
00189                                 apr_pool_t *pool);
00190 
00191 /** Convert @a relative canonicalized dirent to an absolute dirent and
00192  * return the results in @a *pabsolute, allocated in @a pool.
00193  *
00194  * @since New in 1.6.
00195  */
00196 svn_error_t *
00197 svn_dirent_get_absolute(const char **pabsolute,
00198                         const char *relative,
00199                         apr_pool_t *pool);
00200 
00201 /**
00202  * This function is similar as @c svn_path_is_child, except that it supports
00203  * Windows dirents and UNC paths on Windows.
00204  *
00205  * @since New in 1.6.
00206  */
00207 const char *
00208 svn_dirent_is_child(const char *dirent1,
00209                     const char *dirent2,
00210                     apr_pool_t *pool);
00211 
00212 /** Return TRUE if @a dirent1 is an ancestor of @a dirent2 or the dirents are
00213  * equal and FALSE otherwise.
00214  *
00215  * @since New in 1.6.
00216  */
00217 svn_boolean_t
00218 svn_dirent_is_ancestor(const char *path1,
00219                        const char *path2);
00220 
00221 #ifdef __cplusplus
00222 }
00223 #endif /* __cplusplus */
00224 
00225 #endif /* SVN_DIRENT_URI_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines