/** * @copyright * ==================================================================== * Copyright (c) 2008 CollabNet. All rights reserved. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms * are also available at http://subversion.tigris.org/license-1.html. * If newer versions of this license are posted there, you may use a * newer version instead, at your option. * * This software consists of voluntary contributions made by many * individuals. For exact contribution history, see the revision * history and logs, available at http://subversion.tigris.org/. * ==================================================================== * @endcopyright * * @file svn_dirent_uri.h * @brief A library to manipulate URIs and directory entries. * * This library makes a clear distinction between directory entries (dirents) * and URIs where: * - a dirent is a path on (local) disc or a UNC path (Windows) * examples: "/foo/bar", "X:/temp", "//server/share" * - a URI is a path in a repository or a URL * examples: "/trunk/README", "http://hostname/svn/repos" * * 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. * * Nearly all the @c svn_dirent_xxx functions expect paths passed into them * to be in canonical form. The only functions which do *not* have such * expectations are: * * - @c svn_dirent_canonicalize() * - @c svn_dirent_is_canonical() * - @c svn_dirent_internal_style() * - @c svn_dirent_local_style() * * ### TODO: add description in line with svn_path.h, once more functions * are moved. * ### END TODO */ #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. * * @since New in 1.6. */ const char * svn_dirent_internal_style(const char *dirent, apr_pool_t *pool); /** Convert @a dirent from the canonical internal style to the local style. * * @since New in 1.6. */ const char * svn_dirent_local_style(const char *dirent, apr_pool_t *pool); /** Join a base dirent (@a base) with a component (@a component), allocated in * @a pool. * * 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. * * @since New in 1.6. */ char * svn_dirent_join(const char *base, const char *component, apr_pool_t *pool); /** Join multiple components onto a @a base dirent, allocated in @a pool. The * components are terminated by a @c 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. * * @since New in 1.6. */ char * svn_dirent_join_many(apr_pool_t *pool, const char *base, ...); /** 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/"), it is returned * unchanged. * * The returned dirname will be allocated in @a pool. * * @since New in 1.6. */ char * svn_dirent_dirname(const char *dirent, apr_pool_t *pool); /** Return TRUE if @a dirent is considered absolute on the platform at * hand. E.g. '/foo' on posix 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 platforms or 'X:/', '//server/share' * on Windows. * * @since New in 1.5. */ svn_boolean_t svn_dirent_is_root(const char *dirent, 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, and possibly other semantically inoperative * transformations. * * Convert the server name of UNC paths lowercase on Windows. * * The returned dirent may be statically allocated, equal to @a dirent, or * allocated from @a pool. * * @since New in 1.6. */ const char * svn_dirent_canonicalize(const char *dirent, apr_pool_t *pool); /** Return @c TRUE iff @a dirent is canonical. Use @a 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". * * @since New in 1.6. */ svn_boolean_t svn_dirent_is_canonical(const char *dirent, apr_pool_t *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. * * @since New in 1.6. */ char * svn_dirent_get_longest_ancestor(const char *dirent1, const char *dirent2, apr_pool_t *pool); /** Convert @a relative canonicalized dirent to an absolute dirent and * return the results in @a *pabsolute, allocated in @a pool. * * @since New in 1.6. */ svn_error_t * svn_dirent_get_absolute(const char **pabsolute, const char *relative, apr_pool_t *pool); /** * This function is similar as @c svn_path_is_child, except that it supports * Windows dirents and UNC paths on Windows. * * @since New in 1.6. */ const char * svn_dirent_is_child(const char *dirent1, const char *dirent2, apr_pool_t *pool); /** Return TRUE if @a dirent1 is an ancestor of @a dirent2 or the dirents are * equal and FALSE otherwise. * * @since New in 1.6. */ svn_boolean_t svn_dirent_is_ancestor(const char *path1, const char *path2); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* SVN_DIRENT_URI_H */