• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef BASE_PATH_SERVICE_H_
6 #define BASE_PATH_SERVICE_H_
7 
8 #include <string>
9 
10 #include "base/base_export.h"
11 #include "base/base_paths.h"
12 #include "base/gtest_prod_util.h"
13 #include "build/build_config.h"
14 
15 namespace base {
16 
17 class FilePath;
18 class ScopedPathOverride;
19 
20 // The path service is a global table mapping keys to file system paths.  It is
21 // OK to use this service from multiple threads.
22 //
23 class BASE_EXPORT PathService {
24  public:
25   // Retrieves a path to a special directory or file and places it into the
26   // string pointed to by 'path'. If you ask for a directory it is guaranteed
27   // to NOT have a path separator at the end. For example, "c:\windows\temp"
28   // Directories are also guaranteed to exist when this function succeeds.
29   //
30   // Returns true if the directory or file was successfully retrieved. On
31   // failure, 'path' will not be changed.
32   static bool Get(int key, FilePath* path);
33 
34   // Overrides the path to a special directory or file.  This cannot be used to
35   // change the value of DIR_CURRENT, but that should be obvious.  Also, if the
36   // path specifies a directory that does not exist, the directory will be
37   // created by this method.  This method returns true if successful.
38   //
39   // If the given path is relative, then it will be resolved against
40   // DIR_CURRENT.
41   //
42   // WARNING: Consumers of PathService::Get may expect paths to be constant
43   // over the lifetime of the app, so this method should be used with caution.
44   //
45   // Unit tests generally should use ScopedPathOverride instead. Overrides from
46   // one test should not carry over to another.
47   static bool Override(int key, const FilePath& path);
48 
49   // This function does the same as PathService::Override but it takes extra
50   // parameters:
51   // - |is_absolute| indicates that |path| has already been expanded into an
52   // absolute path, otherwise MakeAbsoluteFilePath() will be used. This is
53   // useful to override paths that may not exist yet, since MakeAbsoluteFilePath
54   // fails for those. Note that MakeAbsoluteFilePath also expands symbolic
55   // links, even if path.IsAbsolute() is already true.
56   // - |create| guides whether the directory to be overriden must
57   // be created in case it doesn't exist already.
58   static bool OverrideAndCreateIfNeeded(int key,
59                                         const FilePath& path,
60                                         bool is_absolute,
61                                         bool create);
62 
63   // To extend the set of supported keys, you can register a path provider,
64   // which is just a function mirroring PathService::Get.  The ProviderFunc
65   // returns false if it cannot provide a non-empty path for the given key.
66   // Otherwise, true is returned.
67   //
68   // WARNING: This function could be called on any thread from which the
69   // PathService is used, so a the ProviderFunc MUST BE THREADSAFE.
70   //
71   typedef bool (*ProviderFunc)(int, FilePath*);
72 
73   // Call to register a path provider.  You must specify the range "[key_start,
74   // key_end)" of supported path keys.
75   static void RegisterProvider(ProviderFunc provider,
76                                int key_start,
77                                int key_end);
78 
79   // Disable internal cache.
80   static void DisableCache();
81 
82  private:
83   friend class ScopedPathOverride;
84   FRIEND_TEST_ALL_PREFIXES(PathServiceTest, RemoveOverride);
85 
86   // Removes an override for a special directory or file. Returns true if there
87   // was an override to remove or false if none was present.
88   // NOTE: This function is intended to be used by tests only!
89   static bool RemoveOverride(int key);
90 };
91 
92 }  // namespace base
93 
94 #endif  // BASE_PATH_SERVICE_H_
95