Note: This class is not thread-safe since it maintains a table of source code locations for error reporting. However, when a DescriptorPool wraps a DescriptorDatabase, it uses mutex locking to make sure only one method of the database is called at a time, even if the DescriptorPool is used from multiple threads. Therefore, there is only a problem if you create multiple DescriptorPools wrapping the same SourceTreeDescriptorDatabase and use them from multiple threads.

A particular Importer object will only report errors for a particular file once. All future attempts to import the same file will return NULL without reporting any errors. The idea is that you might want to import a lot of files without seeing the same errors over and over again. If you want to see errors for the same files repeatedly, you can use a separate Importer object to import each one (but use the same DescriptorPool so that they can be cross-linked).

The path may be either a file or a directory. If it is a directory, the entire tree under it will be mapped to the given virtual location. To map a directory to the root of the source tree, pass an empty string for virtual_path.

If multiple mapped paths apply when opening a file, they will be searched in order. For example, if you do:

Given a path to a file on disk, find a virtual path mapping to that file.

The first mapping created with MapPath() whose disk_path contains the filename is used. However, that virtual path may not actually be usable to open the given file. Possible return values are:

SUCCESS: The mapping was found. *virtual_file is filled in so that calling Open(*virtual_file) will open the file named by disk_file.

SHADOWED: A mapping was found, but using Open() to open this virtual path will end up returning some different file. This is because some other mapping with a higher precedence also matches this virtual path and maps it to a different file that exists on disk. *virtual_file is filled in as it would be in the SUCCESS case. *shadowing_disk_file is filled in with the disk path of the file which would be opened if you were to call Open(*virtual_file).

CANNOT_OPEN: The mapping was found and was not shadowed, but the file specified cannot be opened. When this value is returned, errno will indicate the reason the file cannot be opened. *virtual_file will be set to the virtual path as in the SUCCESS case, even though it is not useful.

NO_MAPPING: Indicates that no mapping was found which contains this file.