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