interface/wx/filefn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filefn.h
   3 // Purpose:     interface of wxPathList and file functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPathList
  11
  12     The path list is a convenient way of storing a number of directories, and
  13     when presented with a filename without a directory, searching for an
  14     existing file in those directories.
  15
  16     Be sure to look also at wxStandardPaths if you only want to search files in
  17     some standard paths.
  18
  19     @library{wxbase}
  20     @category{file}
  21
  22     @see wxArrayString, wxStandardPaths, wxFileName
  23 */
  24 class wxPathList : public wxArrayString
  25 {
  26 public:
  27     wxPathList();
  28
  29     /**
  30         Constructs the object calling the Add() function.
  31     */
  32     wxPathList(const wxArrayString& arr);
  33
  34     /**
  35         Adds the given directory to the path list, if the @a path is not already in the list.
  36         If the path cannot be normalized for some reason, it returns @false.
  37
  38         The @a path is always considered to be a directory but no existence checks will be
  39         done on it (because if it doesn't exist, it could be created later and thus result a
  40         valid path when FindValidPath() is called).
  41
  42         @note if the given path is relative, it won't be made absolute before adding it
  43               (this is why FindValidPath() may return relative paths).
  44     */
  45     bool Add(const wxString& path);
  46
  47     /**
  48         Adds all elements of the given array as paths.
  49     */
  50     void Add(const wxArrayString& arr);
  51
  52     /**
  53         Finds the value of the given environment variable, and adds all paths
  54         to the path list.
  55
  56         Useful for finding files in the @c PATH variable, for example.
  57     */
  58     void AddEnvList(const wxString& env_variable);
  59
  60     /**
  61         Given a full filename (with path), calls Add() with the path of the file.
  62     */
  63     bool EnsureFileAccessible(const wxString& filename);
  64
  65     /**
  66         Like FindValidPath() but this function always returns an absolute path
  67         (eventually prepending the current working directory to the value returned
  68         wxPathList::FindValidPath()) or an empty string.
  69     */
  70     wxString FindAbsoluteValidPath(const wxString& file) const;
  71
  72     /**
  73         Searches the given file in all paths stored in this class.
  74
  75         The first path which concatenated to the given string points to an existing
  76         file (see wxFileExists()) is returned.
  77
  78         If the file wasn't found in any of the stored paths, an empty string is returned.
  79
  80         The given string must be a file name, eventually with a path prefix (if the path
  81         prefix is absolute, only its name will be searched); i.e. it must not end with
  82         a directory separator (see wxFileName::GetPathSeparator) otherwise an assertion
  83         will fail.
  84
  85         The returned path may be relative to the current working directory.
  86
  87         Note in fact that wxPathList can be used to store both relative and absolute
  88         paths so that if you added relative paths, then the current working directory
  89         (see wxGetCwd() and wxSetWorkingDirectory()) may affect the value returned
  90         by this function!
  91     */
  92     wxString FindValidPath(const wxString& file) const;
  93 };
  94
  95
  96
  97 // ============================================================================
  98 // Global functions/macros
  99 // ============================================================================
 100
 101 /** @addtogroup group_funcmacro_file */
 102 //@{
 103
 104 /**
 105     A special return value of many wxWidgets classes to indicate that
 106     an invalid offset was given.
 107 */
 108 const int wxInvalidOffset = -1;
 109
 110 /**
 111     The type used to store and provide byte offsets or byte sizes for files or streams.
 112
 113     It is type-defined as @c off_t on POSIX platforms
 114     (see http://www.gnu.org/software/libc/manual/html_node/File-Position-Primitive.html)
 115     or to @c wxLongLong_t on Windows when @c wxHAS_HUGE_FILES is defined.
 116 */
 117 typedef off_t wxFileOffset;
 118
 119 /**
 120     Under Unix this macro changes the current process umask to the given value,
 121     unless it is equal to -1 in which case nothing is done, and restores it to
 122     the original value on scope exit. It works by declaring a variable which
 123     sets umask to @a mask in its constructor and restores it in its destructor.
 124     Under other platforms this macro expands to nothing.
 125
 126     @header{wx/filefn.h}
 127 */
 128 #define wxCHANGE_UMASK(mask)
 129
 130 /**
 131     This function returns the total number of bytes and number of free bytes on
 132     the disk containing the directory @a path (it should exist). Both @a total
 133     and @a free parameters may be @NULL if the corresponding information is not
 134     needed.
 135
 136     @since 2.3.2
 137
 138     @note The generic Unix implementation depends on the system having the
 139           @c statfs() or @c statvfs() function.
 140
 141     @return @true on success, @false if an error occurred (for example, the
 142              directory doesn’t exist).
 143
 144     @header{wx/filefn.h}
 145 */
 146 bool wxGetDiskSpace(const wxString& path,
 147                     wxLongLong total = NULL,
 148                     wxLongLong free = NULL);
 149
 150 /**
 151     Returns the Windows directory under Windows; other platforms return an
 152     empty string.
 153
 154     @header{wx/filefn.h}
 155 */
 156 wxString wxGetOSDirectory();
 157
 158 /**
 159     Parses the @a wildCard, returning the number of filters. Returns 0 if none
 160     or if there's a problem.
 161
 162     The arrays will contain an equal number of items found before the error. On
 163     platforms where native dialogs handle only one filter per entry, entries in
 164     arrays are automatically adjusted. @a wildCard is in the form:
 165
 166     @code
 167     "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
 168     @endcode
 169
 170     @header{wx/filefn.h}
 171 */
 172 int wxParseCommonDialogsFilter(const wxString& wildCard,
 173                                wxArrayString& descriptions,
 174                                wxArrayString& filters);
 175
 176 /**
 177     Converts a DOS to a Unix filename by replacing backslashes with forward
 178     slashes.
 179
 180     @deprecated
 181         Construct a wxFileName with wxPATH_DOS and then use
 182         wxFileName::GetFullPath(wxPATH_UNIX) instead.
 183
 184     @header{wx/filefn.h}
 185 */
 186 void wxDos2UnixFilename(wxChar* s);
 187
 188 /**
 189     Converts a Unix to a DOS filename by replacing forward slashes with
 190     backslashes.
 191
 192     @deprecated
 193         Construct a wxFileName with wxPATH_UNIX and then use
 194         wxFileName::GetFullPath(wxPATH_DOS) instead.
 195
 196     @header{wx/filefn.h}
 197 */
 198 void wxUnix2DosFilename(wxChar* s);
 199
 200 /**
 201     Returns @true if @a dirname exists and is a directory.
 202
 203     @header{wx/filefn.h}
 204 */
 205 bool wxDirExists(const wxString& dirname);
 206
 207 /**
 208     @deprecated
 209         This function is obsolete, please use wxFileName::SplitPath() instead.
 210
 211     This function splits a full file name into components: the path (including
 212     possible disk/drive specification under Windows), the base name, and the
 213     extension. Any of the output parameters (@a path, @a name or @a ext) may be
 214     @NULL if you are not interested in the value of a particular component.
 215
 216     wxSplitPath() will correctly handle filenames with both DOS and Unix path
 217     separators under Windows, however it will not consider backslashes as path
 218     separators under Unix (where backslash is a valid character in a filename).
 219
 220     On entry, @a fullname should be non-@NULL (it may be empty though).
 221
 222     On return, @a path contains the file path (without the trailing separator),
 223     @a name contains the file name and @c ext contains the file extension
 224     without leading dot. All three of them may be empty if the corresponding
 225     component is. The old contents of the strings pointed to by these
 226     parameters will be overwritten in any case (if the pointers are not @NULL).
 227
 228     @header{wx/filefn.h}
 229 */
 230 void wxSplitPath(const wxString& fullname,
 231                   wxString* path,
 232                   wxString* name,
 233                   wxString* ext);
 234
 235 /**
 236     Returns time of last modification of given file.
 237
 238     The function returns <tt>(time_t)-1</tt> if an error occurred (e.g. file
 239     not found).
 240
 241     @header{wx/filefn.h}
 242 */
 243 time_t wxFileModificationTime(const wxString& filename);
 244
 245 /**
 246     Renames @a file1 to @e file2, returning @true if successful.
 247
 248     If @a overwrite parameter is @true (default), the destination file is
 249     overwritten if it exists, but if @a overwrite is @false, the functions
 250     fails in this case.
 251
 252     @header{wx/filefn.h}
 253 */
 254 bool wxRenameFile(const wxString& file1,
 255                    const wxString& file2,
 256                    bool overwrite = true);
 257
 258 /**
 259     Copies @a file1 to @e file2, returning @true if successful. If @a overwrite
 260     parameter is @true (default), the destination file is overwritten if it
 261     exists, but if @a overwrite is @false, the functions fails in this case.
 262
 263     This function supports resources forks under Mac OS.
 264
 265     @header{wx/filefn.h}
 266 */
 267 bool wxCopyFile(const wxString& file1,
 268                  const wxString& file2,
 269                  bool overwrite = true);
 270
 271 /**
 272     Returns @true if the file exists and is a plain file.
 273
 274     @header{wx/filefn.h}
 275 */
 276 bool wxFileExists(const wxString& filename);
 277
 278 /**
 279     Returns @true if the @a pattern matches the @e text; if @a dot_special is
 280     @true, filenames beginning with a dot are not matched with wildcard
 281     characters.
 282
 283     @see wxIsWild()
 284
 285     @header{wx/filefn.h}
 286 */
 287 bool wxMatchWild(const wxString& pattern,
 288                   const wxString& text,
 289                   bool dot_special);
 290
 291 /**
 292     @deprecated This function is deprecated, use wxGetCwd() instead.
 293
 294     Copies the current working directory into the buffer if supplied, or copies
 295     the working directory into new storage (which you must delete yourself) if
 296     the buffer is @NULL.
 297
 298     @a sz is the size of the buffer if supplied.
 299
 300     @header{wx/filefn.h}
 301 */
 302 wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000);
 303
 304 /**
 305     Returns the directory part of the filename.
 306
 307     @header{wx/filefn.h}
 308 */
 309 wxString wxPathOnly(const wxString& path);
 310
 311 /**
 312     Returns @true if the pattern contains wildcards.
 313
 314     @see wxMatchWild()
 315
 316     @header{wx/filefn.h}
 317 */
 318 bool wxIsWild(const wxString& pattern);
 319
 320 /**
 321     Returns @true if the argument is an absolute filename, i.e. with a slash
 322     or drive name at the beginning.
 323
 324     @header{wx/filefn.h}
 325 */
 326 bool wxIsAbsolutePath(const wxString& filename);
 327
 328 /**
 329     Returns a string containing the current (or working) directory.
 330
 331     @header{wx/filefn.h}
 332 */
 333 wxString wxGetCwd();
 334
 335 /**
 336     Sets the current working directory, returning @true if the operation
 337     succeeded. Under MS Windows, the current drive is also changed if @a dir
 338     contains a drive specification.
 339
 340     @header{wx/filefn.h}
 341 */
 342 bool wxSetWorkingDirectory(const wxString& dir);
 343
 344 /**
 345     Concatenates @a file1 and @a file2 to @e file3, returning @true if
 346     successful.
 347
 348     @header{wx/filefn.h}
 349 */
 350 bool wxConcatFiles(const wxString& file1,
 351                     const wxString& file2,
 352                     const wxString& file3);
 353
 354 /**
 355     Removes @e file, returning @true if successful.
 356
 357     @header{wx/filefn.h}
 358 */
 359 bool wxRemoveFile(const wxString& file);
 360
 361 /**
 362     File permission bit names.
 363
 364     We define these constants in wxWidgets because S_IREAD &c are not standard.
 365     However, we do assume that the values correspond to the Unix umask bits.
 366 */
 367 enum wxPosixPermissions
 368 {
 369     /// Standard POSIX names for these permission flags with "wx" prefix.
 370     //@{
 371     wxS_IRUSR = 00400,
 372     wxS_IWUSR = 00200,
 373     wxS_IXUSR = 00100,
 374
 375     wxS_IRGRP = 00040,
 376     wxS_IWGRP = 00020,
 377     wxS_IXGRP = 00010,
 378
 379     wxS_IROTH = 00004,
 380     wxS_IWOTH = 00002,
 381     wxS_IXOTH = 00001,
 382     //@}
 383
 384     /// Longer but more readable synonyms for the constants above.
 385     //@{
 386     wxPOSIX_USER_READ = wxS_IRUSR,
 387     wxPOSIX_USER_WRITE = wxS_IWUSR,
 388     wxPOSIX_USER_EXECUTE = wxS_IXUSR,
 389
 390     wxPOSIX_GROUP_READ = wxS_IRGRP,
 391     wxPOSIX_GROUP_WRITE = wxS_IWGRP,
 392     wxPOSIX_GROUP_EXECUTE = wxS_IXGRP,
 393
 394     wxPOSIX_OTHERS_READ = wxS_IROTH,
 395     wxPOSIX_OTHERS_WRITE = wxS_IWOTH,
 396     wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH,
 397     //@}
 398
 399     /// Default mode for the new files: allow reading/writing them to everybody but
 400     /// the effective file mode will be set after ANDing this value with umask and
 401     /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
 402     wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
 403                    wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
 404                    wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE),
 405
 406     /// Default mode for the new directories (see wxFileName::Mkdir): allow
 407     /// reading/writing/executing them to everybody, but just like wxS_DEFAULT
 408     /// the effective directory mode will be set after ANDing this value with umask
 409     wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
 410                        wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
 411                        wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
 412 };
 413
 414 /**
 415     Makes the directory @a dir, returning @true if successful.
 416
 417     @a perm is the access mask for the directory for the systems on which it is
 418     supported (Unix) and doesn't have any effect on the other ones.
 419
 420     @header{wx/filefn.h}
 421 */
 422 bool wxMkdir(const wxString& dir, int perm = wxS_DIR_DEFAULT);
 423
 424 /**
 425     Removes the directory @a dir, returning @true if successful. Does not work
 426     under VMS.
 427
 428     The @a flags parameter is reserved for future use.
 429
 430     @note There is also a wxRmDir() function which simply wraps the standard
 431           POSIX @c rmdir() function and so return an integer error code instead
 432           of a boolean value (but otherwise is currently identical to
 433           wxRmdir()), don't confuse these two functions.
 434
 435     @header{wx/filefn.h}
 436 */
 437 bool wxRmdir(const wxString& dir, int flags = 0);
 438
 439 /**
 440     Returns the next file that matches the path passed to wxFindFirstFile().
 441
 442     See wxFindFirstFile() for an example.
 443
 444     @header{wx/filefn.h}
 445 */
 446 wxString wxFindNextFile();
 447
 448 /**
 449     This function does directory searching; returns the first file that matches
 450     the path @a spec, or the empty string. Use wxFindNextFile() to get the next
 451     matching file. Neither will report the current directory "." or the parent
 452     directory "..".
 453
 454     @warning As of 2.5.2, these functions are not thread-safe! (they use static
 455              variables). You probably want to use wxDir::GetFirst() or
 456              wxDirTraverser instead.
 457
 458     @a spec may contain wildcards.
 459
 460     @a flags may be wxDIR for restricting the query to directories, wxFILE for
 461     files or zero for either.
 462
 463     For example:
 464
 465     @code
 466     wxString f = wxFindFirstFile("/home/project/*.*");
 467     while ( !f.empty() )
 468     {
 469         ...
 470         f = wxFindNextFile();
 471     }
 472     @endcode
 473
 474     @header{wx/filefn.h}
 475 */
 476 wxString wxFindFirstFile(const wxString& spec, int flags = 0);
 477
 478 /**
 479     File kind enumerations returned from wxGetFileKind().
 480
 481     @header{wx/filefn.h}
 482 */
 483 enum wxFileKind
 484 {
 485     wxFILE_KIND_UNKNOWN,  ///< Unknown file kind, or unable to determine
 486     wxFILE_KIND_DISK,     ///< A file supporting seeking to arbitrary offsets
 487     wxFILE_KIND_TERMINAL, ///< A tty
 488     wxFILE_KIND_PIPE      ///< A pipe
 489 };
 490
 491 //@}
 492
 493 /** @addtogroup group_funcmacro_file */
 494 //@{
 495 /**
 496     Returns the type of an open file. Possible return values are enumerations
 497     of ::wxFileKind.
 498
 499     @header{wx/filefn.h}
 500 */
 501 wxFileKind wxGetFileKind(int fd);
 502 wxFileKind wxGetFileKind(FILE* fp);
 503 //@}
 504
 505 /** @addtogroup group_funcmacro_file */
 506 //@{
 507 /**
 508     @deprecated
 509         This function is obsolete, please use wxFileName::SplitPath() instead.
 510
 511     Returns the filename for a full path. The second form returns a pointer to
 512     temporary storage that should not be deallocated.
 513
 514     @header{wx/filefn.h}
 515 */
 516 wxString wxFileNameFromPath(const wxString& path);
 517 char* wxFileNameFromPath(char* path);
 518 //@}
 519
 520 /** @addtogroup group_funcmacro_file */
 521 //@{
 522 /**
 523     @deprecated
 524         This function is obsolete, please use wxFileName::CreateTempFileName() instead.
 525
 526     @header{wx/filefn.h}
 527 */
 528 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL);
 529 bool wxGetTempFileName(const wxString& prefix, wxString& buf);
 530 //@}
 531