/** * @copyright * ==================================================================== * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. * ==================================================================== * @endcopyright * * @file svn_dirent_uri.h * @brief A library to manipulate URIs, relative paths and directory entries. * * This library makes a clear distinction between several path formats: * * - a dirent is a path on (local) disc or a UNC path (Windows) in * either relative or absolute format. * Examples: * "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only), "" * But not: * "http://server" * * - a uri, for our purposes, is a percent-encoded, absolute path * (URI) that starts with a schema definition. In practice, these * tend to look like URLs, but never carry query strings. * Examples: * "http://server", "file:///path/to/repos", * "svn+ssh://user@host:123/My%20Stuff/file.doc" * But not: * "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc", "" * * - a relative path (relpath) is an unrooted path that can be joined * to any other relative path, uri or dirent. A relative path is * never rooted/prefixed by a '/'. * Examples: * "file", "dir/file", "dir/subdir/../file", "" * But not: * "/file", "http://server/file" * * 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. * * All incoming and outgoing paths are non-NULL unless otherwise documented. * * All of these functions expect paths passed into them to be in canonical * form, except: * * - @c svn_dirent_canonicalize() * - @c svn_dirent_canonicalize_safe() * - @c svn_dirent_is_canonical() * - @c svn_dirent_internal_style() * - @c svn_relpath_canonicalize() * - @c svn_relpath_canonicalize_safe() * - @c svn_relpath_is_canonical() * - @c svn_uri_canonicalize() * - @c svn_uri_canonicalize_safe() * - @c svn_uri_is_canonical() * * The Subversion codebase also recognizes some other classes of path: * * - A Subversion filesystem path (fspath) -- otherwise known as a * path within a repository -- is a path relative to the root of * the repository filesystem, that starts with a slash ("/"). The * rules for a fspath are the same as for a relpath except for the * leading '/'. A fspath never ends with '/' except when the whole * path is just '/'. The fspath API is private (see * private/svn_fspath.h). * * - A URL path (urlpath) is just the path part of a URL (the part * that follows the schema, username, hostname, and port). These * are also like relpaths, except that they have a leading slash * (like fspaths) and are URI-encoded. The urlpath API is also * private (see private/svn_fspath.h) * Example: * "/svn/repos/trunk/README", * "/svn/repos/!svn/bc/45/file%20with%20spaces.txt" * * So, which path API is appropriate for your use-case? * * - If your path refers to a local file, directory, symlink, etc. of * the sort that you can examine and operate on with other software * on your computer, it's a dirent. * * - If your path is a full URL -- with a schema, hostname (maybe), * and path portion -- it's a uri. * * - If your path is relative, and is somewhat ambiguous unless it's * joined to some other more explicit (possible absolute) base * (such as a dirent or URL), it's a relpath. * * - If your path is the virtual path of a versioned object inside a * Subversion repository, it could be one of two different types of * paths. We'd prefer to use relpaths (relative to the root * directory of the virtual repository filesystem) for that stuff, * but some legacy code uses fspaths. You'll need to figure out if * your code expects repository paths to have a leading '/' or not. * If so, they are fspaths; otherwise they are relpaths. * * - If your path refers only to the path part of URL -- as if * someone hacked off the initial schema and hostname portion -- * it's a urlpath. To date, the ra_dav modules are the only ones * within Subversion that make use of urlpaths, and this is because * WebDAV makes heavy use of that form of path specification. * * When translating between local paths (dirents) and uris code should * always go via the relative path format, perhaps by truncating a * parent portion from a path with svn_*_skip_ancestor(), or by * converting portions to basenames and then joining to existing * paths. * * SECURITY WARNING: If a path that is received from an untrusted * source -- such as from the network -- is converted to a dirent it * should be tested with svn_dirent_is_under_root() before you can * assume the path to be a safe local path. * * MEMORY ALLOCATION: A function documented as allocating the result * in a pool may instead return a static string such as "." or "". If * the result is equal to an input, it will duplicate the input. */ #ifndef SVN_DIRENT_URI_H #define SVN_DIRENT_URI_H #include #include #include #include "svn_types.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */