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     /**
  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 overwrite parameter is @true (default), the destination file is
 252     overwritten if it exists, but if @a overwrite is @false, the functions
 253     fails in this case.
 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     File kind enumerations returned from wxGetFileKind().
 483
 484     @header{wx/filefn.h}
 485 */
 486 enum wxFileKind
 487 {
 488     wxFILE_KIND_UNKNOWN,  ///< Unknown file kind, or unable to determine
 489     wxFILE_KIND_DISK,     ///< A file supporting seeking to arbitrary offsets
 490     wxFILE_KIND_TERMINAL, ///< A tty
 491     wxFILE_KIND_PIPE      ///< A pipe
 492 };
 493
 494 //@}
 495
 496 /** @addtogroup group_funcmacro_file */
 497 //@{
 498 /**
 499     Returns the type of an open file. Possible return values are enumerations
 500     of ::wxFileKind.
 501
 502     @header{wx/filefn.h}
 503 */
 504 wxFileKind wxGetFileKind(int fd);
 505 wxFileKind wxGetFileKind(FILE* fp);
 506 //@}
 507
 508 /** @addtogroup group_funcmacro_file */
 509 //@{
 510 /**
 511     @deprecated
 512         This function is obsolete, please use wxFileName::SplitPath() instead.
 513
 514     Returns the filename for a full path. The second form returns a pointer to
 515     temporary storage that should not be deallocated.
 516
 517     @header{wx/filefn.h}
 518 */
 519 wxString wxFileNameFromPath(const wxString& path);
 520 char* wxFileNameFromPath(char* path);
 521 //@}
 522
 523 /** @addtogroup group_funcmacro_file */
 524 //@{
 525 /**
 526     @deprecated
 527         This function is obsolete, please use wxFileName::CreateTempFileName() instead.
 528
 529     @header{wx/filefn.h}
 530 */
 531 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL);
 532 bool wxGetTempFileName(const wxString& prefix, wxString& buf);
 533 //@}
 534