Update doxgen config and some comments.

[simgear.git] / simgear / misc / sg_path.hxx

diff --git a/simgear/misc/sg_path.hxx b/simgear/misc/sg_path.hxx
index bd27694f0dc6f5b6f53893f60cb06f4f92b9c7b0..cce05ebc36a8fd9e9d7499a64974f91583683b67 100644 (file)
--- a/simgear/misc/sg_path.hxx
+++ b/simgear/misc/sg_path.hxx
@@ -52,8 +52,15 @@ class SGPath {
 
 public:
 
+    struct Permissions
+    {
+      bool read : 1;
+      bool write : 1;
+    };
+    typedef Permissions (*PermissionChecker)(const SGPath&);
+
     /** Default constructor */
-    SGPath();
+    explicit SGPath(PermissionChecker validator = NULL);
 
     /** Copy contructor */
     SGPath(const SGPath& p);
@@ -64,14 +71,16 @@ public:
      * Construct a path based on the starting path provided.
      * @param p initial path
      */
-    SGPath( const std::string& p );
+    SGPath( const std::string& p, PermissionChecker validator = NULL );
 
     /**
      * Construct a path based on the starting path provided and a relative subpath
      * @param p initial path
      * @param r relative subpath
      */
-    SGPath( const SGPath& p, const std::string& r );
+    SGPath( const SGPath& p,
+            const std::string& r,
+            PermissionChecker validator = NULL );
 
     /** Destructor */
     ~SGPath();
@@ -85,7 +94,10 @@ public:
 
     bool operator==(const SGPath& other) const;
     bool operator!=(const SGPath& other) const;
-    
+
+    void setPermissionChecker(PermissionChecker validator);
+    PermissionChecker getPermissionChecker() const;
+
     /**
      * Set if file information (exists, type, mod-time) is cached or
      * retrieved each time it is queried. Caching is enabled by default
@@ -198,6 +210,17 @@ public:
      */
     int create_dir(mode_t mode);
 
+    /**
+     * Check if reading file is allowed. Readabilty does not imply the existance
+     * of the file.
+     *
+     * @note By default all files will be marked as readable. No check is made
+     *       if the operating system allows the given file to be read. Derived
+     *       classes may actually implement custom read/write rights.
+     */
+    bool canRead() const;
+    bool canWrite() const;
+
     bool isFile() const;
     bool isDir() const;
     
@@ -234,6 +257,18 @@ public:
      */
     bool rename(const SGPath& newName);
 
+    enum StandardLocation
+    {
+      HOME,
+      DESKTOP,
+      DOWNLOADS,
+      DOCUMENTS,
+      PICTURES
+    };
+
+    static SGPath standardLocation( StandardLocation type,
+                                    const SGPath& def = SGPath() );
+
     /**
      * Get a path stored in the environment variable with the given \a name.
      *
@@ -246,23 +281,33 @@ public:
     /**
      * Get path to user's home directory
      */
-    static SGPath home();
+    static SGPath home(const SGPath& def = SGPath());
 
     /**
      * Get path to the user's desktop directory
      */
-    static SGPath desktop();
+    static SGPath desktop(const SGPath& def = SGPath());
+
+       /**
+     * Get path to the user's documents directory
+     */
+    static SGPath documents(const SGPath& def = SGPath());
 
 private:
 
     void fix();
 
     void validate() const;
+    void checkAccess() const;
 
     std::string path;
-    
+    PermissionChecker _permission_checker;
+
     mutable bool _cached : 1;
+    mutable bool _rwCached : 1;
     bool _cacheEnabled : 1; ///< cacheing can be disbled if required
+    mutable bool _canRead : 1;
+    mutable bool _canWrite : 1;
     mutable bool _exists : 1;
     mutable bool _isDir : 1;
     mutable bool _isFile : 1;