Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_dirent_uri.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Copyright (c) 2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_dirent_uri.h
19  * @brief A library to manipulate URIs and directory entries.
20  *
21  * This library makes a clear distinction between directory entries (dirents)
22  * and URIs where:
23  * - a dirent is a path on (local) disc or a UNC path (Windows)
24  * examples: "/foo/bar", "X:/temp", "//server/share"
25  * - a URI is a path in a repository or a URL
26  * examples: "/trunk/README", "http://hostname/svn/repos"
27  *
28  * This distinction is needed because on Windows we have to handle some
29  * dirents and URIs differently. Since it's not possible to determine from
30  * the path string if it's a dirent or a URI, it's up to the API user to
31  * make this choice. See also issue #2028.
32  *
33  * Nearly all the @c svn_dirent_xxx functions expect paths passed into them
34  * to be in canonical form. The only functions which do *not* have such
35  * expectations are:
36  *
37  * - @c svn_dirent_canonicalize()
38  * - @c svn_dirent_is_canonical()
39  * - @c svn_dirent_internal_style()
40  * - @c svn_dirent_local_style()
41  *
42  * ### TODO: add description in line with svn_path.h, once more functions
43  * are moved.
44  * ### END TODO
45  */
46 
47 #ifndef SVN_DIRENT_URI_H
48 #define SVN_DIRENT_URI_H
49 
50 #include <apr.h>
51 #include <apr_pools.h>
52 #include <apr_tables.h>
53 
54 #include "svn_types.h"
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif /* __cplusplus */
59 
60 
61 /** Convert @a dirent from the local style to the canonical internal style.
62  *
63  * @since New in 1.6.
64  */
65 const char *
66 svn_dirent_internal_style(const char *dirent,
67  apr_pool_t *pool);
68 
69 /** Convert @a dirent from the canonical internal style to the local style.
70  *
71  * @since New in 1.6.
72  */
73 const char *
74 svn_dirent_local_style(const char *dirent,
75  apr_pool_t *pool);
76 
77 /** Join a base dirent (@a base) with a component (@a component), allocated in
78  * @a pool.
79  *
80  * If either @a base or @a component is the empty string, then the other
81  * argument will be copied and returned. If both are the empty string then
82  * empty string is returned.
83  *
84  * If the @a component is an absolute dirent, then it is copied and returned.
85  * The platform specific rules for joining paths are used to join the components.
86  *
87  * This function is NOT appropriate for native (local) file
88  * dirents. Only for "internal" canonicalized dirents, since it uses '/'
89  * for the separator.
90  *
91  * @since New in 1.6.
92  */
93 char *
94 svn_dirent_join(const char *base,
95  const char *component,
96  apr_pool_t *pool);
97 
98 /** Join multiple components onto a @a base dirent, allocated in @a pool. The
99  * components are terminated by a @c NULL.
100  *
101  * If any component is the empty string, it will be ignored.
102  *
103  * If any component is an absolute dirent, then it resets the base and
104  * further components will be appended to it.
105  *
106  * See svn_dirent_join() for further notes about joining dirents.
107  *
108  * @since New in 1.6.
109  */
110 char *
111 svn_dirent_join_many(apr_pool_t *pool,
112  const char *base,
113  ...);
114 
115 /** Get the dirname of the specified canonicalized @a dirent, defined as
116  * the dirent with its basename removed.
117  *
118  * If @a dirent is root ("/", "X:/", "//server/share/"), it is returned
119  * unchanged.
120  *
121  * The returned dirname will be allocated in @a pool.
122  *
123  * @since New in 1.6.
124  */
125 char *
126 svn_dirent_dirname(const char *dirent,
127  apr_pool_t *pool);
128 
129 /** Return TRUE if @a dirent is considered absolute on the platform at
130  * hand. E.g. '/foo' on posix or 'X:/foo', '//server/share/foo'
131  * on Windows.
132  *
133  * @since New in 1.6.
134  */
136 svn_dirent_is_absolute(const char *dirent);
137 
138 /** Return TRUE if @a dirent is considered a root directory on the platform
139  * at hand. E.g. '/' on posix platforms or 'X:/', '//server/share'
140  * on Windows.
141  *
142  * @since New in 1.5.
143  */
145 svn_dirent_is_root(const char *dirent,
146  apr_size_t len);
147 
148 /** Return a new dirent like @a dirent, but transformed such that some types
149  * of dirent specification redundancies are removed.
150  *
151  * This involves collapsing redundant "/./" elements, removing
152  * multiple adjacent separator characters, removing trailing
153  * separator characters, and possibly other semantically inoperative
154  * transformations.
155  *
156  * Convert the server name of UNC paths lowercase on Windows.
157  *
158  * The returned dirent may be statically allocated, equal to @a dirent, or
159  * allocated from @a pool.
160  *
161  * @since New in 1.6.
162  */
163 const char *
164 svn_dirent_canonicalize(const char *dirent,
165  apr_pool_t *pool);
166 
167 /** Return @c TRUE iff @a dirent is canonical. Use @a pool for temporary
168  * allocations.
169  *
170  * @note The test for canonicalization is currently defined as
171  * "looks exactly the same as @c svn_dirent_canonicalize() would make
172  * it look".
173  *
174  * @since New in 1.6.
175  */
177 svn_dirent_is_canonical(const char *dirent,
178  apr_pool_t *pool);
179 
180 /** Return the longest common dirent shared by two canonicalized dirents,
181  * @a dirent1 and @a dirent2. If there's no common ancestor, return the
182  * empty path.
183  *
184  * @since New in 1.6.
185  */
186 char *
187 svn_dirent_get_longest_ancestor(const char *dirent1,
188  const char *dirent2,
189  apr_pool_t *pool);
190 
191 /** Convert @a relative canonicalized dirent to an absolute dirent and
192  * return the results in @a *pabsolute, allocated in @a pool.
193  *
194  * @since New in 1.6.
195  */
196 svn_error_t *
197 svn_dirent_get_absolute(const char **pabsolute,
198  const char *relative,
199  apr_pool_t *pool);
200 
201 /**
202  * This function is similar as @c svn_path_is_child, except that it supports
203  * Windows dirents and UNC paths on Windows.
204  *
205  * @since New in 1.6.
206  */
207 const char *
208 svn_dirent_is_child(const char *dirent1,
209  const char *dirent2,
210  apr_pool_t *pool);
211 
212 /** Return TRUE if @a dirent1 is an ancestor of @a dirent2 or the dirents are
213  * equal and FALSE otherwise.
214  *
215  * @since New in 1.6.
216  */
218 svn_dirent_is_ancestor(const char *path1,
219  const char *path2);
220 
221 #ifdef __cplusplus
222 }
223 #endif /* __cplusplus */
224 
225 #endif /* SVN_DIRENT_URI_H */