1    :  // Copyright 2012 Google Inc.
   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 "syzygy/pe/pe_file.h"
  23    :  
  24  m :  namespace pe {
  25    :  
  26    :  // Determines if the given PE file and PDB file are indeed matched. Does no
  27    :  // logging.
  28    :  // @param pe_path the path to the PE file to inspect.
  29    :  // @param pdb_path the path to the PDB file to inspect.
  30    :  // @returns true if the files both exist, are valid and are matched, false
  31    :  //     otherwise.
  32  m :  bool PeAndPdbAreMatched(const FilePath& pe_path, const FilePath& pdb_path);
  33    :  
  34    :  // Looks for the module matching a given module signature. Uses the module
  35    :  // signature path as the starting point of the search.
  36    :  //
  37    :  // Given an example module path of "C:\foo\foo.dll", the search strategy
  38    :  // is as follows:
  39    :  //
  40    :  // 1. Looks for "C:\foo\foo.dll".
  41    :  // 2. Looks for "foo.dll" in the current working directory.
  42    :  // 3. Looks for "foo.dll" in each directory in @p search_paths.
  43    :  //
  44    :  // @param module_signature The signature of the module we are searching for.
  45    :  //     This also contains the path to the module from which the signature was
  46    :  //     originally taken, and this is used as the starting point of the search.
  47    :  // @param search_paths A semi-colon separated list of additional search paths.
  48    :  // @param module_path If the module is successfully found, this will contain
  49    :  //     the absolute path to the discovered module.
  50    :  //
  51    :  // @returns false if any errors occur, true otherwise. If the module is found
  52    :  //     its path is returned in @p module_path.
  53  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  54  m :                             const wchar_t* search_paths,
  55  m :                             FilePath* module_path);
  56    :  
  57    :  // Same as 3-parameter FindModuleBySignature, but uses the PATH environment
  58    :  // variable as the list of search paths.
  59  m :  bool FindModuleBySignature(const PEFile::Signature& module_signature,
  60  m :                             FilePath* module_path);
  61    :  
  62    :  // Searches for the PDB file corresponding to the given module. Uses the
  63    :  // path stored in the module's debug information as a starting point, and also
  64    :  // searches in the current working directory.
  65    :  //
  66    :  // Given an example PDB starting path of "C:\foo\foo.pdb", the search strategy
  67    :  // is as follows:
  68    :  //
  69    :  // 1. Looks for "C:\foo\foo.pdb".
  70    :  // 2. Looks for "foo.pdb" in the current working directory.
  71    :  // 3. Looks for "foo.pdb" in each directory in @p search_paths, or looks by
  72    :  //    GUID/age in each symbol server listed in @p search_paths.
  73    :  //
  74    :  // @param module_path The module whose PDB file we are looking for.
  75    :  // @param search_paths A semi-colon separated list of additional search paths.
  76    :  //     May use the svr* and cache* notation of symbol servers.
  77    :  // @param pdb_path If the PDB is successfully found, this will contain the
  78    :  //     absolute path to it. If it is found on a symbol server, it will first
  79    :  //     be downloaded and stored locally.
  80    :  //
  81    :  // @returns false if any errors occur, true otherwise. If the PDB file is found
  82    :  //     its path is returned in @p pdb_path.
  83  m :  bool FindPdbForModule(const FilePath& module_path,
  84  m :                        const wchar_t* search_paths,
  85  m :                        FilePath* pdb_path);
  86    :  
  87    :  // Same 3-parameter FindPdbForModule, but uses the _NT_SYMBOL_PATH environment
  88    :  // variable as the list of search paths.
  89  m :  bool FindPdbForModule(const FilePath& module_path,
  90  m :                        FilePath* pdb_path);
  91    :  
  92  m :  }  // namespace pe
  93    :  
  94    :  #endif  // SYZYGY_PE_FIND_H_