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/file_path.h"
  22    :  #include "base/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 FilePath& pe_path, const FilePath& pdb_path);
  34    :  
  35    :  // Looks for the module matching a given module signature. If @p module_path is
  36    :  // not empty uses it as a starting point for the search using the following
  37    :  // search strategy. If that fails (or is not present) it uses the path in
  38    :  /// @p module_signature as a starting point using the following strategy.
  39    :  //
  40    :  // Given an example module path of "C:\foo\foo.dll", the search strategy
  41    :  // is as follows:
  42    :  //
  43    :  // 1. Looks for "C:\foo\foo.dll".
  44    :  // 2. Looks for "foo.dll" in the current working directory.
  45    :  // 3. Looks for "foo.dll" in each directory in @p search_paths.
  46    :  //
  47    :  // @param module_signature The signature of the module we are searching for.
  48    :  //     This also contains the path to the module from which the signature was
  49    :  //     originally taken, and this is used as the starting point of the search.
  50    :  // @param search_paths A semi-colon separated list of additional search paths.
  51    :  // @param module_path If the module is successfully found, this will contain
  52    :  //     the absolute path to the discovered module.
  53    :  //
  54    :  // @returns false if any errors occur, true otherwise. If the module is found
  55    :  //     its path is returned in @p module_path. If the module is not found
  56    :  //     but there were no errors, this will return true and @p module_path will
  57    :  //     be empty.
  58  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  59  m :                             const base::StringPiece16& search_paths,
  60  m :                             FilePath* module_path);
  61    :  
  62    :  // Same as 3-parameter FindModuleBySignature, but uses the PATH environment
  63    :  // variable as the list of search paths.
  64  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  65  m :                             FilePath* module_path);
  66    :  
  67    :  // Searches for the PDB file corresponding to the given module. If not empty,
  68    :  // uses @p pdb_path as a starting point with the following strategy. If that
  69    :  // fails (or @p pdb_path is empty), uses the path stored in the module's debug
  70    :  // information as a starting point with the the following strategy.
  71    :  //
  72    :  // Given an example PDB starting path of "C:\foo\foo.pdb", the search strategy
  73    :  // is as follows:
  74    :  //
  75    :  // 1. Looks for "C:\foo\foo.pdb".
  76    :  // 2. Looks for "foo.pdb" in the current working directory.
  77    :  // 3. Looks for "foo.pdb" in each directory in @p search_paths, or looks by
  78    :  //    GUID/age in each symbol server listed in @p search_paths.
  79    :  //
  80    :  // @param module_path The module whose PDB file we are looking for.
  81    :  // @param search_paths A semi-colon separated list of additional search paths.
  82    :  //     May use the svr* and cache* notation of symbol servers.
  83    :  // @param pdb_path If the PDB is successfully found, this will contain the
  84    :  //     absolute path to it. If it is found on a symbol server, it will first
  85    :  //     be downloaded and stored locally.
  86    :  //
  87    :  // @returns false if any errors occur, true otherwise. If the PDB file is found
  88    :  //     its path is returned in @p pdb_path. If the PDB file is not found
  89    :  //     but there were no errors, this will return true and @p pdb_path will
  90    :  //     be empty.
  91  m :  bool FindPdbForModule(const FilePath& module_path,
  92  m :                        const base::StringPiece16& search_paths,
  93  m :                        FilePath* pdb_path);
  94    :  
  95    :  // Same 3-parameter FindPdbForModule, but uses the _NT_SYMBOL_PATH environment
  96    :  // variable as the list of search paths.
  97  m :  bool FindPdbForModule(const FilePath& module_path,
  98  m :                        FilePath* pdb_path);
  99    :  
 100  m :  }  // namespace pe
 101    :  
 102    :  #endif  // SYZYGY_PE_FIND_H_