interface/wx/filefn.h

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