sal/osl/os2/file_path_helper.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: file_path_helper.h,v $
  10  * $Revision: 1.4 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31  #ifndef _OSL_FILE_PATH_HELPER_H_
  32  #define _OSL_FILE_PATH_HELPER_H_
  33
  34
  35  #ifndef _SAL_TYPES_H_
  36  #include <sal/types.h>
  37  #endif
  38
  39  #ifndef _RTL_USTRING_H_
  40  #include <rtl/ustring.h>
  41  #endif
  42
  43
  44  #ifdef __cplusplus
  45  extern "C"
  46  {
  47  #endif
  48
  49
  50  /*******************************************
  51     osl_systemPathRemoveSeparator
  52     Removes the last separator from the
  53     given system path if any and if the path
  54     is not the root path '/'
  55
  56     @param      ppustrPath [inout] a system path
  57             if the path is not the root path
  58             and the last character is a
  59             path separator it will be cut off
  60                ppustrPath must not be NULL and
  61             must point to a valid rtl_uString
  62
  63     @returns nothing
  64
  65   ******************************************/
  66
  67  void SAL_CALL osl_systemPathRemoveSeparator(
  68      /*inout*/ rtl_uString* pustrPath);
  69
  70  /*******************************************
  71     osl_systemPathEnsureSeparator
  72     Adds a trailing path separator to the
  73     given system path if not already there
  74     and if the path is not the root path '/'
  75
  76       @param    pustrPath [inout] a system path
  77             if the path is not the root path
  78             '/' and has no trailing separator
  79             a separator will be added
  80             ppustrPath must not be NULL and
  81             must point to a valid rtl_uString
  82
  83     @returns nothing
  84
  85   ******************************************/
  86
  87  void SAL_CALL osl_systemPathEnsureSeparator(
  88      /*inout*/ rtl_uString** ppustrPath);
  89
  90  /*******************************************
  91     osl_systemPathIsRelativePath
  92     Returns true if the given path is a
  93     relative path and so starts not with '/'
  94
  95     @param      pustrPath [in] a system path
  96             pustrPath must not be NULL
  97
  98     @returns sal_True if the given path
  99              doesn't start with a separator
 100              else sal_False will be returned
 101
 102   ******************************************/
 103
 104  sal_Bool SAL_CALL osl_systemPathIsRelativePath(
 105      const rtl_uString* pustrPath);
 106
 107  /******************************************
 108     osl_systemPathIsAbsolutePath
 109     Returns true if the given path is an
 110     absolute path and so starts with a '/'
 111
 112     @param pustrPath [in] a system path
 113            pustrPath must not be NULL
 114
 115     @returns sal_True if the given path
 116              start's with a separator else
 117              sal_False will be returned
 118
 119   *****************************************/
 120
 121  sal_Bool SAL_CALL osl_systemPathIsAbsolutePath(
 122      const rtl_uString* pustrPath);
 123
 124  /******************************************
 125     osl_systemPathMakeAbsolutePath
 126     Append a relative path to a base path
 127
 128     @param      pustrBasePath [in] a system
 129             path that will be considered as
 130             base path
 131             pustrBasePath must not be NULL
 132
 133     @param      pustrRelPath [in] a system path
 134             that will be considered as
 135             relative path
 136             pustrBasePath must not be NULL
 137
 138     @param      ppustrAbsolutePath [out] the
 139             resulting path which is a
 140             concatination of the base and
 141             the relative path
 142             if base path is empty the
 143             resulting absolute path is the
 144             relative path
 145             if relative path is empty the
 146             resulting absolute path is the
 147             base path
 148             if base and relative path are
 149             empty the resulting absolute
 150             path is also empty
 151             ppustrAbsolutePath must not be
 152             NULL and *ppustrAbsolutePath
 153             must be 0 or point to a valid
 154             rtl_uString
 155
 156   *****************************************/
 157
 158  void SAL_CALL osl_systemPathMakeAbsolutePath(
 159      const rtl_uString* pustrBasePath,
 160     const rtl_uString* pustrRelPath,
 161     rtl_uString**          ppustrAbsolutePath);
 162
 163  /*****************************************
 164     osl_systemPathGetParent
 165     Replaces the last occurrance of a path
 166     separator with '\0' and returns the
 167     position where the '/' was replaced
 168
 169     @param      pustrPath [inout] a system
 170             path, the last separator of
 171             this path will be replaced by
 172             a '\0'
 173             if the path is the root path
 174             '/' or the path is considered
 175             as to have no parent, e.g.
 176             '/NoParent' or 'NoParent' or
 177             the path is empty no
 178             replacement will be made
 179             pustrPath must not be NULL
 180
 181     @returns the position of the last path
 182              separator that was replaced
 183              or 0 if no replacement took
 184              place
 185
 186   ****************************************/
 187
 188  sal_Int32 SAL_CALL osl_systemPathGetParent(
 189     /*inout*/ rtl_uString* pustrPath);
 190
 191  /*****************************************
 192      osl_systemPathGetFileOrLastDirectoryPart
 193     Returns the file or the directory part
 194     of the given path
 195
 196     @param pustrPath [in] a system path,
 197            must not be NULL
 198
 199     @param ppustrFileOrDirPart [out] on
 200            return receives the last part
 201            of the given directory or the
 202            file name
 203            if pustrPath is the root path
 204            '/' an empty string will be
 205            returned
 206            if pustrPath has a trailing
 207            '/' the last part before the
 208            '/' will be returned else
 209            the part after the last '/'
 210            will be returned
 211
 212     @returns nothing
 213
 214   ****************************************/
 215  void SAL_CALL osl_systemPathGetFileNameOrLastDirectoryPart(
 216      const rtl_uString*         pustrPath,
 217     rtl_uString**               ppustrFileNameOrLastDirPart);
 218
 219
 220  /********************************************
 221      osl_systemPathIsHiddenFileOrDirectoryEntry
 222     Returns sal_True if the last part of
 223     given system path is not '.' or '..'
 224     alone and starts with a '.'
 225
 226     @param pustrPath [in] a system path,
 227            must not be NULL
 228
 229     @returns sal_True if the last part of
 230              the given system path starts
 231              with '.' or sal_False the last
 232              part is '.' or     '..' alone or
 233              doesn't start with a dot
 234
 235  *********************************************/
 236
 237  sal_Bool SAL_CALL osl_systemPathIsHiddenFileOrDirectoryEntry(
 238      const rtl_uString* pustrPath);
 239
 240
 241  /************************************************
 242      osl_systemPathIsLocalOrParentDirectoryEntry
 243     Returns sal_True if the last part of the given
 244     system path is the local directory entry '.'
 245     or the parent directory entry '..'
 246
 247     @param pustrPath [in] a system path,
 248            must not be NULL
 249
 250     @returns sal_True if the last part of the
 251              given system path is '.' or '..'
 252              else sal_False
 253
 254  ************************************************/
 255
 256  sal_Bool SAL_CALL osl_systemPathIsLocalOrParentDirectoryEntry(
 257      const rtl_uString* pustrPath);
 258
 259
 260  /************************************************
 261       osl_searchPath
 262     Searches for a file name or path name in all
 263     directories specified by a given path list.
 264     Symbolic links in the resulting path will not be
 265     resolved, it's up to the caller to do this.
 266
 267     @param pustrFilePath [in] a file name or
 268     directory name to search for, the name must
 269     be provided as system path not as a file URL
 270
 271     @param pustrSearchPathList [in] a ':'
 272     separated list of paths in which to search for
 273     the file or directory name
 274
 275     @ppustrPathFound [out] on success receives the
 276     complete path of the file or directory found
 277     as a system path
 278
 279     @returns sal_True if the specified file or
 280     directory was found else sal_False
 281   ***********************************************/
 282
 283  sal_Bool SAL_CALL osl_searchPath(
 284      const rtl_uString* pustrFilePath,
 285     const rtl_uString* pustrSearchPathList,
 286     rtl_uString**      ppustrPathFound);
 287
 288
 289  #ifdef __cplusplus
 290  }
 291  #endif
 292
 293
 294  #endif /* #ifndef _OSL_PATH_HELPER_H_ */
 295