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  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_dirent_uri.h
24  * @brief A library to manipulate URIs, relative paths and directory entries.
25  *
26  * This library makes a clear distinction between several path formats:
27  *
28  * - a dirent is a path on (local) disc or a UNC path (Windows) in
29  * either relative or absolute format.
30  * Examples:
31  * "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only)
32  * But not:
33  * "http://server"
34  *
35  * - a uri, for our purposes, is a percent-encoded, absolute path
36  * (URI) that starts with a schema definition. In practice, these
37  * tend to look like URLs, but never carry query strings.
38  * Examples:
39  * "http://server", "file:///path/to/repos",
40  * "svn+ssh://user@host:123/My%20Stuff/file.doc"
41  * But not:
42  * "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc"
43  *
44  * - a relative path (relpath) is an unrooted path that can be joined
45  * to any other relative path, uri or dirent. A relative path is
46  * never rooted/prefixed by a '/'.
47  * Examples:
48  * "file", "dir/file", "dir/subdir/../file"
49  * But not:
50  * "/file", "http://server/file"
51  *
52  * This distinction is needed because on Windows we have to handle some
53  * dirents and URIs differently. Since it's not possible to determine from
54  * the path string if it's a dirent or a URI, it's up to the API user to
55  * make this choice. See also issue #2028.
56  *
57  * All of these functions expect paths passed into them to be in canonical
58  * form, except:
59  *
60  * - @c svn_dirent_canonicalize()
61  * - @c svn_dirent_is_canonical()
62  * - @c svn_dirent_internal_style()
63  * - @c svn_relpath_canonicalize()
64  * - @c svn_relpath_is_canonical()
65  * - @c svn_relpath__internal_style()
66  * - @c svn_uri_canonicalize()
67  * - @c svn_uri_is_canonical()
68  *
69  * The Subversion codebase also recognizes some other classes of path:
70  *
71  * - A Subversion filesystem path (fspath) -- otherwise known as a
72  * path within a repository -- is a path relative to the root of
73  * the repository filesystem, that starts with a slash ("/"). The
74  * rules for a fspath are the same as for a relpath except for the
75  * leading '/'. A fspath never ends with '/' except when the whole
76  * path is just '/'. The fspath API is private (see
77  * private/svn_fspath.h).
78  *
79  * - A URL path (urlpath) is just the path part of a URL (the part
80  * that follows the schema, username, hostname, and port). These
81  * are also like relpaths, except that they have a leading slash
82  * (like fspaths) and are URI-encoded. The urlpath API is also
83  * private (see private/svn_fspath.h)
84  * Example:
85  * "/svn/repos/trunk/README",
86  * "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"
87  *
88  * So, which path API is appropriate for your use-case?
89  *
90  * - If your path refers to a local file, directory, symlink, etc. of
91  * the sort that you can examine and operate on with other software
92  * on your computer, it's a dirent.
93  *
94  * - If your path is a full URL -- with a schema, hostname (maybe),
95  * and path portion -- it's a uri.
96  *
97  * - If your path is relative, and is somewhat ambiguous unless it's
98  * joined to some other more explicit (possible absolute) base
99  * (such as a dirent or URL), it's a relpath.
100  *
101  * - If your path is the virtual path of a versioned object inside a
102  * Subversion repository, it could be one of two different types of
103  * paths. We'd prefer to use relpaths (relative to the root
104  * directory of the virtual repository filesystem) for that stuff,
105  * but some legacy code uses fspaths. You'll need to figure out if
106  * your code expects repository paths to have a leading '/' or not.
107  * If so, they are fspaths; otherwise they are relpaths.
108  *
109  * - If your path refers only to the path part of URL -- as if
110  * someone hacked off the initial schema and hostname portion --
111  * it's a urlpath. To date, the ra_dav modules are the only ones
112  * within Subversion that make use of urlpaths, and this is because
113  * WebDAV makes heavy use of that form of path specification.
114  *
115  * When translating between local paths (dirents) and uris code should
116  * always go via the relative path format, perhaps by truncating a
117  * parent portion from a path with svn_*_skip_ancestor(), or by
118  * converting portions to basenames and then joining to existing
119  * paths.
120  *
121  * SECURITY WARNING: If a path that is received from an untrusted
122  * source -- such as from the network -- is converted to a dirent it
123  * should be tested with svn_dirent_is_under_root() before you can
124  * assume the path to be a safe local path.
125  */
126 
127 #ifndef SVN_DIRENT_URI_H
128 #define SVN_DIRENT_URI_H
129 
130 #include <apr.h>
131 #include <apr_pools.h>
132 #include <apr_tables.h>
133 
134 #include "svn_types.h"
135 
136 #ifdef __cplusplus
137 extern "C" {
138 #endif /* __cplusplus */
139 
140 
141 /** Convert @a dirent from the local style to the canonical internal style.
142  * "Local style" means native path separators and "." for the empty path.
143  *
144  * @since New in 1.6.
145  */
146 const char *
147 svn_dirent_internal_style(const char *dirent,
148  apr_pool_t *pool);
149 
150 /** Convert @a dirent from the internal style to the local style.
151  * "Local style" means native path separators and "." for the empty path.
152  * If the input is not canonical, the output may not be canonical.
153  *
154  * @since New in 1.6.
155  */
156 const char *
157 svn_dirent_local_style(const char *dirent,
158  apr_pool_t *pool);
159 
160 /** Convert @a relpath from the local style to the canonical internal style.
161  * "Local style" means native path separators and "." for the empty path.
162  *
163  * @since New in 1.7.
164  */
165 const char *
166 svn_relpath__internal_style(const char *relpath,
167  apr_pool_t *pool);
168 
169 
170 /** Join a base dirent (@a base) with a component (@a component), allocated in
171  * @a pool.
172  *
173  * If either @a base or @a component is the empty string, then the other
174  * argument will be copied and returned. If both are the empty string then
175  * empty string is returned.
176  *
177  * If the @a component is an absolute dirent, then it is copied and returned.
178  * The platform specific rules for joining paths are used to join the components.
179  *
180  * This function is NOT appropriate for native (local) file
181  * dirents. Only for "internal" canonicalized dirents, since it uses '/'
182  * for the separator.
183  *
184  * @since New in 1.6.
185  */
186 char *
187 svn_dirent_join(const char *base,
188  const char *component,
189  apr_pool_t *pool);
190 
191 /** Join multiple components onto a @a base dirent, allocated in @a pool. The
192  * components are terminated by a @c NULL.
193  *
194  * If any component is the empty string, it will be ignored.
195  *
196  * If any component is an absolute dirent, then it resets the base and
197  * further components will be appended to it.
198  *
199  * See svn_dirent_join() for further notes about joining dirents.
200  *
201  * @since New in 1.6.
202  */
203 char *
204 svn_dirent_join_many(apr_pool_t *pool,
205  const char *base,
206  ...);
207 
208 /** Join a base relpath (@a base) with a component (@a component), allocating
209  * the result in @a pool. @a component need not be a single component.
210  *
211  * If either @a base or @a component is the empty path, then the other
212  * argument will be copied and returned. If both are the empty path the
213  * empty path is returned.
214  *
215  * @since New in 1.7.
216  */
217 char *
218 svn_relpath_join(const char *base,
219  const char *component,
220  apr_pool_t *pool);
221 
222 /** Gets the name of the specified canonicalized @a dirent as it is known
223  * within its parent directory. If the @a dirent is root, return "". The
224  * returned value will not have slashes in it.
225  *
226  * Example: svn_dirent_basename("/foo/bar") -> "bar"
227  *
228  * The returned basename will be allocated in @a pool. If @a pool is NULL
229  * a pointer to the basename in @a dirent is returned.
230  *
231  * @note If an empty string is passed, then an empty string will be returned.
232  *
233  * @since New in 1.7.
234  */
235 const char *
236 svn_dirent_basename(const char *dirent,
237  apr_pool_t *pool);
238 
239 /** Get the dirname of the specified canonicalized @a dirent, defined as
240  * the dirent with its basename removed.
241  *
242  * If @a dirent is root ("/", "X:/", "//server/share/") or "", it is returned
243  * unchanged.
244  *
245  * The returned dirname will be allocated in @a pool.
246  *
247  * @since New in 1.6.
248  */
249 char *
250 svn_dirent_dirname(const char *dirent,
251  apr_pool_t *pool);
252 
253 /** Divide the canonicalized @a dirent into @a *dirpath and @a
254  * *base_name, allocated in @a pool.
255  *
256  * If @a dirpath or @a base_name is NULL, then don't set that one.
257  *
258  * Either @a dirpath or @a base_name may be @a dirent's own address, but they
259  * may not both be the same address, or the results are undefined.
260  *
261  * If @a dirent has two or more components, the separator between @a dirpath
262  * and @a base_name is not included in either of the new names.
263  *
264  * Examples:
265  * - <pre>"/foo/bar/baz" ==> "/foo/bar" and "baz"</pre>
266  * - <pre>"/bar" ==> "/" and "bar"</pre>
267  * - <pre>"/" ==> "/" and ""</pre>
268  * - <pre>"bar" ==> "" and "bar"</pre>
269  * - <pre>"" ==> "" and ""</pre>
270  * Windows: - <pre>"X:/" ==> "X:/" and ""</pre>
271  * - <pre>"X:/foo" ==> "X:/" and "foo"</pre>
272  * - <pre>"X:foo" ==> "X:" and "foo"</pre>
273  * Posix: - <pre>"X:foo" ==> "" and "X:foo"</pre>
274  *
275  * @since New in 1.7.
276  */
277 void
278 svn_dirent_split(const char **dirpath,
279  const char **base_name,
280  const char *dirent,
281  apr_pool_t *pool);
282 
283 /** Divide the canonicalized @a relpath into @a *dirpath and @a
284  * *base_name, allocated in @a pool.
285  *
286  * If @a dirpath or @a base_name is NULL, then don't set that one.
287  *
288  * Either @a dirpath or @a base_name may be @a relpaths's own address, but
289  * they may not both be the same address, or the results are undefined.
290  *
291  * If @a relpath has two or more components, the separator between @a dirpath
292  * and @a base_name is not included in either of the new names.
293  *
294  * examples:
295  * - <pre>"foo/bar/baz" ==> "foo/bar" and "baz"</pre>
296  * - <pre>"bar" ==> "" and "bar"</pre>
297  * - <pre>"" ==> "" and ""</pre>
298  *
299  * @since New in 1.7.
300  */
301 void
302 svn_relpath_split(const char **dirpath,
303  const char **base_name,
304  const char *relpath,
305  apr_pool_t *pool);
306 
307 /** Get the basename of the specified canonicalized @a relpath. The
308  * basename is defined as the last component of the relpath. If the @a
309  * relpath has only one component then that is returned. The returned
310  * value will have no slashes in it.
311  *
312  * Example: svn_relpath_basename("/trunk/foo/bar") -> "bar"
313  *
314  * The returned basename will be allocated in @a pool. If @a
315  * pool is NULL a pointer to the basename in @a relpath is returned.
316  *
317  * @note If an empty string is passed, then an empty string will be returned.
318  *
319  * @since New in 1.7.
320  */
321 const char *
322 svn_relpath_basename(const char *relpath,
323  apr_pool_t *pool);
324 
325 /** Get the dirname of the specified canonicalized @a relpath, defined as
326  * the relpath with its basename removed.
327  *
328  * If @a relpath is empty, "" is returned.
329  *
330  * The returned relpath will be allocated in @a pool.
331  *
332  * @since New in 1.7.
333  */
334 char *
335 svn_relpath_dirname(const char *relpath,
336  apr_pool_t *pool);
337 
338 
339 /** Divide the canonicalized @a uri into a uri @a *dirpath and a
340  * (URI-decoded) relpath @a *base_name, allocated in @a pool.
341  *
342  * If @a dirpath or @a base_name is NULL, then don't set that one.
343  *
344  * Either @a dirpath or @a base_name may be @a uri's own address, but they
345  * may not both be the same address, or the results are undefined.
346  *
347  * If @a uri has two or more components, the separator between @a dirpath
348  * and @a base_name is not included in either of the new names.
349  *
350  * Examples:
351  * - <pre>"http://server/foo/bar" ==> "http://server/foo" and "bar"</pre>
352  *
353  * @since New in 1.7.
354  */
355 void
356 svn_uri_split(const char **dirpath,
357  const char **base_name,
358  const char *uri,
359  apr_pool_t *pool);
360 
361 /** Get the (URI-decoded) basename of the specified canonicalized @a
362  * uri. The basename is defined as the last component of the uri. If
363  * the @a uri is root then that is returned. Otherwise, the returned
364  * value will have no slashes in it.
365  *
366  * Example: svn_uri_basename("http://server/foo/bar") -> "bar"
367  *
368  * The returned basename will be allocated in @a pool.
369  *
370  * @since New in 1.7.
371  */
372 const char *
373 svn_uri_basename(const char *uri,
374  apr_pool_t *pool);
375 
376 /** Get the dirname of the specified canonicalized @a uri, defined as
377  * the uri with its basename removed.
378  *
379  * If @a uri is root (e.g. "http://server"), it is returned
380  * unchanged.
381  *
382  * The returned dirname will be allocated in @a pool.
383  *
384  * @since New in 1.7.
385  */
386 char *
387 svn_uri_dirname(const char *uri,
388  apr_pool_t *pool);
389 
390 /** Return TRUE if @a dirent is considered absolute on the platform at
391  * hand. E.g. '/foo' on Posix platforms or 'X:/foo', '//server/share/foo'
392  * on Windows.
393  *
394  * @since New in 1.6.
395  */
397 svn_dirent_is_absolute(const char *dirent);
398 
399 /** Return TRUE if @a dirent is considered a root directory on the platform
400  * at hand.
401  * E.g.:
402  * On Posix: '/'
403  * On Windows: '/', 'X:/', '//server/share', 'X:'
404  *
405  * Note that on Windows '/' and 'X:' are roots, but paths starting with this
406  * root are not absolute.
407  *
408  * @since New in 1.5.
409  */
411 svn_dirent_is_root(const char *dirent,
412  apr_size_t len);
413 
414 /** Return TRUE if @a uri is a root URL (e.g., "http://server").
415  *
416  * @since New in 1.7
417  */
419 svn_uri_is_root(const char *uri,
420  apr_size_t len);
421 
422 /** Return a new dirent like @a dirent, but transformed such that some types
423  * of dirent specification redundancies are removed.
424  *
425  * This involves:
426  * - collapsing redundant "/./" elements
427  * - removing multiple adjacent separator characters
428  * - removing trailing separator characters
429  * - converting the server name of a UNC path to lower case (on Windows)
430  * - converting a drive letter to upper case (on Windows)
431  *
432  * and possibly other semantically inoperative transformations.
433  *
434  * The returned dirent may be allocated statically or from @a pool.
435  *
436  * @since New in 1.6.
437  */
438 const char *
439 svn_dirent_canonicalize(const char *dirent,
440  apr_pool_t *pool);
441 
442 
443 /** Return a new relpath like @a relpath, but transformed such that some types
444  * of relpath specification redundancies are removed.
445  *
446  * This involves:
447  * - collapsing redundant "/./" elements
448  * - removing multiple adjacent separator characters
449  * - removing trailing separator characters
450  *
451  * and possibly other semantically inoperative transformations.
452  *
453  * The returned relpath may be allocated statically or from @a pool.
454  *
455  * @since New in 1.7.
456  */
457 const char *
458 svn_relpath_canonicalize(const char *relpath,
459  apr_pool_t *pool);
460 
461 
462 /** Return a new uri like @a uri, but transformed such that some types
463  * of uri specification redundancies are removed.
464  *
465  * This involves:
466  * - collapsing redundant "/./" elements
467  * - removing multiple adjacent separator characters
468  * - removing trailing separator characters
469  * - normalizing the escaping of the path component by unescaping
470  * characters that don't need escaping and escaping characters that do
471  * need escaping but weren't
472  * - removing the port number if it is the default port number (80 for
473  * http, 443 for https, 3690 for svn)
474  *
475  * and possibly other semantically inoperative transformations.
476  *
477  * The returned uri may be allocated statically or from @a pool.
478  *
479  * @since New in 1.7.
480  */
481 const char *
482 svn_uri_canonicalize(const char *uri,
483  apr_pool_t *pool);
484 
485 /** Return @c TRUE iff @a dirent is canonical. Use @a pool for temporary
486  * allocations.
487  *
488  * @note The test for canonicalization is currently defined as
489  * "looks exactly the same as @c svn_dirent_canonicalize() would make
490  * it look".
491  *
492  * @see svn_dirent_canonicalize()
493  * @since New in 1.6.
494  */
496 svn_dirent_is_canonical(const char *dirent,
497  apr_pool_t *pool);
498 
499 /** Return @c TRUE iff @a relpath is canonical.
500  *
501  * @see svn_relpath_canonicalize()
502  * @since New in 1.7.
503  */
505 svn_relpath_is_canonical(const char *relpath);
506 
507 /** Return @c TRUE iff @a uri is canonical. Use @a pool for temporary
508  * allocations.
509  *
510  * @see svn_uri_canonicalize()
511  * @since New in 1.7.
512  */
514 svn_uri_is_canonical(const char *uri,
515  apr_pool_t *pool);
516 
517 /** Return the longest common dirent shared by two canonicalized dirents,
518  * @a dirent1 and @a dirent2. If there's no common ancestor, return the
519  * empty path.
520  *
521  * @since New in 1.6.
522  */
523 char *
524 svn_dirent_get_longest_ancestor(const char *dirent1,
525  const char *dirent2,
526  apr_pool_t *pool);
527 
528 /** Return the longest common path shared by two relative paths,
529  * @a relpath1 and @a relpath2. If there's no common ancestor, return the
530  * empty path.
531  *
532  * @since New in 1.7.
533  */
534 char *
535 svn_relpath_get_longest_ancestor(const char *relpath1,
536  const char *relpath2,
537  apr_pool_t *pool);
538 
539 /** Return the longest common path shared by two canonicalized uris,
540  * @a uri1 and @a uri2. If there's no common ancestor, return the
541  * empty path. In order for two URLs to have a common ancestor, they
542  * must (a) have the same protocol (since two URLs with the same path
543  * but different protocols may point at completely different
544  * resources), and (b) share a common ancestor in their path
545  * component, i.e. 'protocol://' is not a sufficient ancestor.
546  *
547  * @since New in 1.7.
548  */
549 char *
550 svn_uri_get_longest_ancestor(const char *uri1,
551  const char *uri2,
552  apr_pool_t *pool);
553 
554 /** Convert @a relative canonicalized dirent to an absolute dirent and
555  * return the results in @a *pabsolute, allocated in @a pool.
556  * Raise SVN_ERR_BAD_FILENAME if the absolute dirent cannot be determined.
557  *
558  * @since New in 1.6.
559  */
560 svn_error_t *
561 svn_dirent_get_absolute(const char **pabsolute,
562  const char *relative,
563  apr_pool_t *pool);
564 
565 /** Similar to svn_uri_skip_ancestor(), except that if @a child_uri is
566  * the same as @a parent_uri, it is not considered a child, so the result
567  * is @c NULL; an empty string is never returned.
568  */
569 const char *
570 svn_uri__is_child(const char *parent_uri,
571  const char *child_uri,
572  apr_pool_t *pool);
573 
574 /** Similar to svn_dirent_skip_ancestor(), except that if @a child_dirent is
575  * the same as @a parent_dirent, it is not considered a child, so the result
576  * is @c NULL; an empty string is never returned.
577  *
578  * ### TODO: Deprecate, as the semantics are trivially
579  * obtainable from *_skip_ancestor().
580  *
581  * @since New in 1.6.
582  */
583 const char *
584 svn_dirent_is_child(const char *parent_dirent,
585  const char *child_dirent,
586  apr_pool_t *pool);
587 
588 /** Similar to svn_relpath_skip_ancestor(), except that if @a child_relpath is
589  * the same as @a parent_relpath, it is not considered a child, so the result
590  * is @c NULL; an empty string is never returned.
591  */
592 const char *
593 svn_relpath__is_child(const char *parent_relpath,
594  const char *child_relpath,
595  apr_pool_t *pool);
596 
597 /** Return TRUE if @a parent_dirent is an ancestor of @a child_dirent or
598  * the dirents are equal, and FALSE otherwise.
599  *
600  * ### TODO: Deprecate, as the semantics are trivially
601  * obtainable from *_skip_ancestor().
602  *
603  * @since New in 1.6.
604  */
606 svn_dirent_is_ancestor(const char *parent_dirent,
607  const char *child_dirent);
608 
609 /** Return TRUE if @a parent_relpath is an ancestor of @a child_relpath or
610  * the relpaths are equal, and FALSE otherwise.
611  */
613 svn_relpath__is_ancestor(const char *parent_relpath,
614  const char *child_relpath);
615 
616 /** Return TRUE if @a parent_uri is an ancestor of @a child_uri or
617  * the uris are equal, and FALSE otherwise.
618  */
620 svn_uri__is_ancestor(const char *parent_uri,
621  const char *child_uri);
622 
623 
624 /** Return the relative path part of @a child_dirent that is below
625  * @a parent_dirent, or just "" if @a parent_dirent is equal to
626  * @a child_dirent. If @a child_dirent is not below or equal to
627  * @a parent_dirent, return NULL.
628  *
629  * If one of @a parent_dirent and @a child_dirent is absolute and
630  * the other relative, return NULL.
631  *
632  * @since New in 1.7.
633  */
634 const char *
635 svn_dirent_skip_ancestor(const char *parent_dirent,
636  const char *child_dirent);
637 
638 /** Return the relative path part of @a child_relpath that is below
639  * @a parent_relpath, or just "" if @a parent_relpath is equal to
640  * @a child_relpath. If @a child_relpath is not below or equal to
641  * @a parent_relpath, return NULL.
642  *
643  * @since New in 1.7.
644  */
645 const char *
646 svn_relpath_skip_ancestor(const char *parent_relpath,
647  const char *child_relpath);
648 
649 /** Return the URI-decoded relative path of @a child_uri that is below
650  * @a parent_uri, or just "" if @a parent_uri is equal to @a child_uri. If
651  * @a child_uri is not below or equal to @a parent_uri, return NULL.
652  * Allocate the result in @a result_pool.
653  *
654  * @since New in 1.7.
655  */
656 const char *
657 svn_uri_skip_ancestor(const char *parent_uri,
658  const char *child_uri,
659  apr_pool_t *result_pool);
660 
661 /** Find the common prefix of the canonicalized dirents in @a targets
662  * (an array of <tt>const char *</tt>'s), and remove redundant dirents if @a
663  * remove_redundancies is TRUE.
664  *
665  * - Set @a *pcommon to the absolute dirent of the dirent common to
666  * all of the targets. If the targets have no common prefix (e.g.
667  * "C:/file" and "D:/file" on Windows), set @a *pcommon to the empty
668  * string.
669  *
670  * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
671  * to an array of targets relative to @a *pcommon, and if
672  * @a remove_redundancies is TRUE, omit any dirents that are
673  * descendants of another dirent in @a targets. If *pcommon
674  * is empty, @a *pcondensed_targets will contain absolute dirents;
675  * redundancies can still be removed. If @a pcondensed_targets is NULL,
676  * leave it alone.
677  *
678  * Else if there is exactly one target, then
679  *
680  * - Set @a *pcommon to that target, and
681  *
682  * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
683  * to an array containing zero elements. Else if
684  * @a pcondensed_targets is NULL, leave it alone.
685  *
686  * If there are no items in @a targets, set @a *pcommon and (if
687  * applicable) @a *pcondensed_targets to @c NULL.
688  *
689  * Allocates @a *pcommon and @a *targets in @a result_pool. All
690  * intermediate allocations will be performed in @a scratch_pool.
691  *
692  * @since New in 1.7.
693  */
694 svn_error_t *
695 svn_dirent_condense_targets(const char **pcommon,
696  apr_array_header_t **pcondensed_targets,
697  const apr_array_header_t *targets,
698  svn_boolean_t remove_redundancies,
699  apr_pool_t *result_pool,
700  apr_pool_t *scratch_pool);
701 
702 /** Find the common prefix of the canonicalized uris in @a targets
703  * (an array of <tt>const char *</tt>'s), and remove redundant uris if @a
704  * remove_redundancies is TRUE.
705  *
706  * - Set @a *pcommon to the common base uri of all of the targets.
707  * If the targets have no common prefix (e.g. "http://srv1/file"
708  * and "http://srv2/file"), set @a *pcommon to the empty
709  * string.
710  *
711  * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
712  * to an array of URI-decoded targets relative to @a *pcommon, and
713  * if @a remove_redundancies is TRUE, omit any uris that are
714  * descendants of another uri in @a targets. If *pcommon is
715  * empty, @a *pcondensed_targets will contain absolute uris;
716  * redundancies can still be removed. If @a pcondensed_targets is
717  * NULL, leave it alone.
718  *
719  * Else if there is exactly one target, then
720  *
721  * - Set @a *pcommon to that target, and
722  *
723  * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
724  * to an array containing zero elements. Else if
725  * @a pcondensed_targets is NULL, leave it alone.
726  *
727  * If there are no items in @a targets, set @a *pcommon and (if
728  * applicable) @a *pcondensed_targets to @c NULL.
729  *
730  * Allocate @a *pcommon and @a *targets in @a result_pool. Temporary
731  * allocations will be performed in @a scratch_pool.
732  *
733  * @since New in 1.7.
734  */
735 svn_error_t *
736 svn_uri_condense_targets(const char **pcommon,
737  apr_array_header_t **pcondensed_targets,
738  const apr_array_header_t *targets,
739  svn_boolean_t remove_redundancies,
740  apr_pool_t *result_pool,
741  apr_pool_t *scratch_pool);
742 
743 /** Join @a path onto @a base_path, checking that @a path does not attempt
744  * to traverse above @a base_path. If @a path or any ".." component within
745  * it resolves to a path above @a base_path, or if @a path is an absolute
746  * path, then set @a *under_root to @c FALSE. Otherwise, set @a *under_root
747  * to @c TRUE and, if @a result_path is not @c NULL, set @a *result_path to
748  * the resulting path, allocated in @a result_pool.
749  *
750  * @a path need not be canonical. @a base_path must be canonical and
751  * @a *result_path will be canonical.
752  *
753  * Note: Use of this function is strongly encouraged. Do not roll your own.
754  * (http://cve.mitre.org/cgi-bin/cvename.cgi?name=2007-3846)
755  *
756  * @since New in 1.7.
757  */
758 svn_error_t *
760  const char **result_path,
761  const char *base_path,
762  const char *path,
763  apr_pool_t *result_pool);
764 
765 /** Set @a *dirent to the path corresponding to the file:// URL @a url, using
766  * the platform-specific file:// rules.
767  *
768  * @since New in 1.7.
769  */
770 svn_error_t *
771 svn_uri_get_dirent_from_file_url(const char **dirent,
772  const char *url,
773  apr_pool_t *pool);
774 
775 /** Set @a *url to a file:// URL, corresponding to @a dirent using the
776  * platform specific dirent and file:// rules.
777  *
778  * @since New in 1.7.
779  */
780 svn_error_t *
781 svn_uri_get_file_url_from_dirent(const char **url,
782  const char *dirent,
783  apr_pool_t *pool);
784 
785 #ifdef __cplusplus
786 }
787 #endif /* __cplusplus */
788 
789 #endif /* SVN_DIRENT_URI_H */
svn_boolean_t svn_dirent_is_absolute(const char *dirent)
Return TRUE if dirent is considered absolute on the platform at hand.
const char * svn_dirent_skip_ancestor(const char *parent_dirent, const char *child_dirent)
Return the relative path part of child_dirent that is below parent_dirent, or just "" if parent_diren...
char * svn_relpath_join(const char *base, const char *component, apr_pool_t *pool)
Join a base relpath (base) with a component (component), allocating the result in pool...
const char * svn_relpath_canonicalize(const char *relpath, apr_pool_t *pool)
Return a new relpath like relpath, but transformed such that some types of relpath specification redu...
svn_boolean_t svn_relpath_is_canonical(const char *relpath)
Return TRUE iff relpath is canonical.
const char * svn_dirent_canonicalize(const char *dirent, apr_pool_t *pool)
Return a new dirent like dirent, but transformed such that some types of dirent specification redunda...
svn_boolean_t svn_uri_is_root(const char *uri, apr_size_t len)
Return TRUE if uri is a root URL (e.g., "http://server").
char * svn_uri_dirname(const char *uri, apr_pool_t *pool)
Get the dirname of the specified canonicalized uri, defined as the uri with its basename removed...
const char * svn_uri__is_child(const char *parent_uri, const char *child_uri, apr_pool_t *pool)
Similar to svn_uri_skip_ancestor(), except that if child_uri is the same as parent_uri, it is not considered a child, so the result is NULL; an empty string is never returned.
svn_boolean_t svn_dirent_is_canonical(const char *dirent, apr_pool_t *pool)
Return TRUE iff dirent is canonical.
char * svn_dirent_dirname(const char *dirent, apr_pool_t *pool)
Get the dirname of the specified canonicalized dirent, defined as the dirent with its basename remove...
const char * svn_dirent_local_style(const char *dirent, apr_pool_t *pool)
Convert dirent from the internal style to the local style.
svn_boolean_t svn_uri__is_ancestor(const char *parent_uri, const char *child_uri)
Return TRUE if parent_uri is an ancestor of child_uri or the uris are equal, and FALSE otherwise...
svn_error_t * svn_dirent_get_absolute(const char **pabsolute, const char *relative, apr_pool_t *pool)
Convert relative canonicalized dirent to an absolute dirent and return the results in *pabsolute...
const char * svn_relpath_basename(const char *relpath, apr_pool_t *pool)
Get the basename of the specified canonicalized relpath.
const char * svn_dirent_is_child(const char *parent_dirent, const char *child_dirent, apr_pool_t *pool)
Similar to svn_dirent_skip_ancestor(), except that if child_dirent is the same as parent_dirent...
svn_error_t * svn_uri_get_dirent_from_file_url(const char **dirent, const char *url, apr_pool_t *pool)
Set *dirent to the path corresponding to the file:// URL url, using the platform-specific file:// rul...
void svn_uri_split(const char **dirpath, const char **base_name, const char *uri, apr_pool_t *pool)
Divide the canonicalized uri into a uri *dirpath and a (URI-decoded) relpath *base_name, allocated in pool.
const char * svn_dirent_basename(const char *dirent, apr_pool_t *pool)
Gets the name of the specified canonicalized dirent as it is known within its parent directory...
Subversion error object.
Definition: svn_types.h:90
const char * svn_relpath__internal_style(const char *relpath, apr_pool_t *pool)
Convert relpath from the local style to the canonical internal style.
void svn_dirent_split(const char **dirpath, const char **base_name, const char *dirent, apr_pool_t *pool)
Divide the canonicalized dirent into *dirpath and *base_name, allocated in pool.
char * svn_relpath_get_longest_ancestor(const char *relpath1, const char *relpath2, apr_pool_t *pool)
Return the longest common path shared by two relative paths, relpath1 and relpath2.
char * svn_dirent_join_many(apr_pool_t *pool, const char *base,...)
Join multiple components onto a base dirent, allocated in pool.
svn_error_t * svn_uri_condense_targets(const char **pcommon, apr_array_header_t **pcondensed_targets, const apr_array_header_t *targets, svn_boolean_t remove_redundancies, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
Find the common prefix of the canonicalized uris in targets (an array of const char *'s)...
svn_boolean_t svn_dirent_is_root(const char *dirent, apr_size_t len)
Return TRUE if dirent is considered a root directory on the platform at hand.
char * svn_dirent_get_longest_ancestor(const char *dirent1, const char *dirent2, apr_pool_t *pool)
Return the longest common dirent shared by two canonicalized dirents, dirent1 and dirent2...
Subversion's data types.
char * svn_uri_get_longest_ancestor(const char *uri1, const char *uri2, apr_pool_t *pool)
Return the longest common path shared by two canonicalized uris, uri1 and uri2.
svn_boolean_t svn_relpath__is_ancestor(const char *parent_relpath, const char *child_relpath)
Return TRUE if parent_relpath is an ancestor of child_relpath or the relpaths are equal...
svn_error_t * svn_dirent_condense_targets(const char **pcommon, apr_array_header_t **pcondensed_targets, const apr_array_header_t *targets, svn_boolean_t remove_redundancies, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
Find the common prefix of the canonicalized dirents in targets (an array of const char *'s)...
char * svn_dirent_join(const char *base, const char *component, apr_pool_t *pool)
Join a base dirent (base) with a component (component), allocated in pool.
const char * svn_relpath_skip_ancestor(const char *parent_relpath, const char *child_relpath)
Return the relative path part of child_relpath that is below parent_relpath, or just "" if parent_rel...
void svn_relpath_split(const char **dirpath, const char **base_name, const char *relpath, apr_pool_t *pool)
Divide the canonicalized relpath into *dirpath and *base_name, allocated in pool. ...
svn_error_t * svn_uri_get_file_url_from_dirent(const char **url, const char *dirent, apr_pool_t *pool)
Set *url to a file:// URL, corresponding to dirent using the platform specific dirent and file:// rul...
int svn_boolean_t
YABT: Yet Another Boolean Type.
Definition: svn_types.h:370
const char * svn_uri_skip_ancestor(const char *parent_uri, const char *child_uri, apr_pool_t *result_pool)
Return the URI-decoded relative path of child_uri that is below parent_uri, or just "" if parent_uri ...
char * svn_relpath_dirname(const char *relpath, apr_pool_t *pool)
Get the dirname of the specified canonicalized relpath, defined as the relpath with its basename remo...
const char * svn_uri_basename(const char *uri, apr_pool_t *pool)
Get the (URI-decoded) basename of the specified canonicalized uri.
svn_error_t * svn_dirent_is_under_root(svn_boolean_t *under_root, const char **result_path, const char *base_path, const char *path, apr_pool_t *result_pool)
Join path onto base_path, checking that path does not attempt to traverse above base_path.
const char * svn_dirent_internal_style(const char *dirent, apr_pool_t *pool)
Convert dirent from the local style to the canonical internal style.
svn_boolean_t svn_dirent_is_ancestor(const char *parent_dirent, const char *child_dirent)
Return TRUE if parent_dirent is an ancestor of child_dirent or the dirents are equal, and FALSE otherwise.
svn_boolean_t svn_uri_is_canonical(const char *uri, apr_pool_t *pool)
Return TRUE iff uri is canonical.
const char * svn_uri_canonicalize(const char *uri, apr_pool_t *pool)
Return a new uri like uri, but transformed such that some types of uri specification redundancies are...
const char * svn_relpath__is_child(const char *parent_relpath, const char *child_relpath, apr_pool_t *pool)
Similar to svn_relpath_skip_ancestor(), except that if child_relpath is the same as parent_relpath...