1    :  // Copyright 2012 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  //
  15    :  // Declares utility functions for finding a module and a PDB file corresponding
  16    :  // to the given module signature.
  17    :  
  18    :  #ifndef SYZYGY_PE_FIND_H_
  19    :  #define SYZYGY_PE_FIND_H_
  20    :  
  21    :  #include "base/files/file_path.h"
  22    :  #include "base/strings/string_piece.h"
  23    :  #include "syzygy/pe/pe_file.h"
  24    :  
  25  m :  namespace pe {
  26    :  
  27    :  // Determines if the given PE file and PDB file are indeed matched. Does no
  28    :  // logging.
  29    :  // @param pe_path the path to the PE file to inspect.
  30    :  // @param pdb_path the path to the PDB file to inspect.
  31    :  // @returns true if the files both exist, are valid and are matched, false
  32    :  //     otherwise.
  33  m :  bool PeAndPdbAreMatched(const base::FilePath& pe_path,
  34  m :                          const base::FilePath& pdb_path);
  35    :  
  36    :  // Looks for the module matching a given module signature. If @p module_path is
  37    :  // not empty uses it as a starting point for the search using the following
  38    :  // search strategy. If that fails (or is not present) it uses the path in
  39    :  /// @p module_signature as a starting point using the following strategy.
  40    :  //
  41    :  // Given an example module path of "C:\foo\foo.dll", the search strategy
  42    :  // is as follows:
  43    :  //
  44    :  // 1. Looks for "C:\foo\foo.dll".
  45    :  // 2. Looks for "foo.dll" in the current working directory.
  46    :  // 3. Looks for "foo.dll" in each directory in @p search_paths.
  47    :  //
  48    :  // @param module_signature The signature of the module we are searching for.
  49    :  //     This also contains the path to the module from which the signature was
  50    :  //     originally taken, and this is used as the starting point of the search.
  51    :  // @param search_paths A semi-colon separated list of additional search paths.
  52    :  // @param module_path If the module is successfully found, this will contain
  53    :  //     the absolute path to the discovered module.
  54    :  //
  55    :  // @returns false if any errors occur, true otherwise. If the module is found
  56    :  //     its path is returned in @p module_path. If the module is not found
  57    :  //     but there were no errors, this will return true and @p module_path will
  58    :  //     be empty.
  59  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  60  m :                             const base::StringPiece16& search_paths,
  61  m :                             base::FilePath* module_path);
  62    :  
  63    :  // Same as 3-parameter FindModuleBySignature, but uses the PATH environment
  64    :  // variable as the list of search paths.
  65  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  66  m :                             base::FilePath* module_path);
  67    :  
  68    :  // Searches for the PDB file corresponding to the given module. If not empty,
  69    :  // uses @p pdb_path as a starting point with the following strategy. If that
  70    :  // fails (or @p pdb_path is empty), uses the path stored in the module's debug
  71    :  // information as a starting point with the the following strategy.
  72    :  //
  73    :  // Given an example PDB starting path of "C:\foo\foo.pdb", the search strategy
  74    :  // is as follows:
  75    :  //
  76    :  // 1. Looks for "C:\foo\foo.pdb".
  77    :  // 2. Looks for "foo.pdb" in the current working directory.
  78    :  // 3. Looks for "foo.pdb" in each directory in @p search_paths, or looks by
  79    :  //    GUID/age in each symbol server listed in @p search_paths.
  80    :  //
  81    :  // @param module_path The module whose PDB file we are looking for.
  82    :  // @param search_paths A semi-colon separated list of additional search paths.
  83    :  //     May use the svr* and cache* notation of symbol servers.
  84    :  // @param pdb_path If the PDB is successfully found, this will contain the
  85    :  //     absolute path to it. If it is found on a symbol server, it will first
  86    :  //     be downloaded and stored locally.
  87    :  //
  88    :  // @returns false if any errors occur, true otherwise. If the PDB file is found
  89    :  //     its path is returned in @p pdb_path. If the PDB file is not found
  90    :  //     but there were no errors, this will return true and @p pdb_path will
  91    :  //     be empty.
  92  m :  bool FindPdbForModule(const base::FilePath& module_path,
  93  m :                        const base::StringPiece16& search_paths,
  94  m :                        base::FilePath* pdb_path);
  95    :  
  96    :  // Same 3-parameter FindPdbForModule, but uses the _NT_SYMBOL_PATH environment
  97    :  // variable as the list of search paths.
  98  m :  bool FindPdbForModule(const base::FilePath& module_path,
  99  m :                        base::FilePath* pdb_path);
 100    :  
 101  m :  }  // namespace pe
 102    :  
 103    :  #endif  // SYZYGY_PE_FIND_H_