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 some utilities for dealing with PDB files via the DIA interface.
  16    :  #ifndef SYZYGY_PE_DIA_UTIL_H_
  17    :  #define SYZYGY_PE_DIA_UTIL_H_
  18    :  
  19    :  #include <windows.h>  // NOLINT
  20    :  #include <dia2.h>
  21    :  #include <vector>
  22    :  
  23    :  #include "base/file_path.h"
  24    :  
  25  m :  namespace pe {
  26    :  
  27    :  // The name of the DIA SDK DLL.
  28  m :  extern const wchar_t kDiaDllName[];
  29    :  
  30    :  // The names of various debug streams.
  31  m :  extern const wchar_t kFixupDiaDebugStreamName[];
  32  m :  extern const wchar_t kOmapToDiaDebugStreamName[];
  33  m :  extern const wchar_t kOmapFromDiaDebugStreamName[];
  34    :  
  35    :  // A trinary value that is returned by search routines.
  36  m :  enum SearchResult {
  37    :    // The search completed and the object was found.
  38  m :    kSearchSucceeded,
  39    :    // The search completed, but the object was not found.
  40  m :    kSearchFailed,
  41    :    // The search did not complete due to an error.
  42  m :    kSearchErrored,
  43  m :  };
  44    :  
  45    :  // Creates a DiaDataSource object. Logs any errors.
  46    :  //
  47    :  // @param created_source pointer that will receive the created object.
  48    :  // @returns true on success, false otherwise.
  49  m :  bool CreateDiaSource(IDiaDataSource** created_source);
  50    :  
  51    :  // Creates a dia session for the provided object. Logs any errors.
  52    :  //
  53    :  // @param file the file to open.
  54    :  // @param dia_source the DIA source to use.
  55    :  // @param dia_session pointer that will receive the created DIA session.
  56    :  // @return true on success, false otherwise.
  57  m :  bool CreateDiaSession(const FilePath& file,
  58  m :                        IDiaDataSource* dia_source,
  59  m :                        IDiaSession** dia_session);
  60    :  
  61    :  // Find the table with the given IID. Logs any errors.
  62    :  //
  63    :  // @param iid the IID of the table to look for.
  64    :  // @param dia_session the DIA session whose tables are to be queried.
  65    :  // @param out_table a pointer to the object to receive the table. If the table
  66    :  //     is not found this will be NULL on return.
  67    :  // @returns a SearchResult
  68  m :  SearchResult FindDiaTable(const IID& iid,
  69  m :                            IDiaSession* dia_session,
  70  m :                            void** out_table);
  71    :  
  72    :  // Find the table that can be cast to the given Dia interface. Logs any errors.
  73    :  //
  74    :  // @tparam T an IDia* intercace.
  75    :  // @param session the DIA session whose tables are to be queried.
  76    :  // @param out_table a pointer to the object to receive the table. If the table
  77    :  //     is not found this will be NULL on return.
  78    :  // @returns a SearchResult
  79  m :  template <typename T>
  80  m :  SearchResult FindDiaTable(IDiaSession* dia_session, T** out_table);
  81    :  
  82    :  // Finds teh debug stream with the given name. Logs any errors.
  83    :  //
  84    :  // @param name the name of the stream to find.
  85    :  // @param dia_session the DIA session to search.
  86    :  // @param dia_debug_stream the pointer that will receive the debug stream, if
  87    :  //     found.
  88    :  // @returns a SearchResult.
  89  m :  SearchResult FindDiaDebugStream(const wchar_t* name,
  90  m :                                  IDiaSession* dia_session,
  91  m :                                  IDiaEnumDebugStreamData** dia_debug_stream);
  92    :  
  93    :  // This reads a given debug stream into the provided vector. The type T
  94    :  // must be the same size as the debug stream record size. Logs any errors.
  95    :  //
  96    :  // @tparam T the type of object to read from the debug stream.
  97    :  // @param stream the debug stream from which to read objects.
  98    :  // @param list the list to be populated.
  99    :  // @returns true on success, false otherwise.
 100  m :  template <typename T>
 101  m :  bool LoadDiaDebugStream(IDiaEnumDebugStreamData* stream, std::vector<T>* list);
 102    :  
 103    :  // This loads the named debug stream into the provided vector. The type T must
 104    :  // be the same size as the debug stream record size. Logs any errors.
 105    :  //
 106    :  // @tparam T the type of object to read from the debug stream.
 107    :  // @param name the name of the stream to load.
 108    :  // @param dia_session the DIA session to search.
 109    :  // @param list the list to be populated.
 110    :  // @returns a SearchResults.
 111  m :  template <typename T>
 112  m :  SearchResult FindAndLoadDiaDebugStreamByName(const wchar_t* name,
 113  m :                                               IDiaSession* dia_session,
 114  m :                                               std::vector<T>* list);
 115    :  
 116  m :  }  // namespace pe
 117    :  
 118    :  // Bring in the templated implementation details.
 119    :  #include "syzygy/pe/dia_util_internal.h"
 120    :  
 121    :  #endif  // SYZYGY_PE_DIA_UTIL_H_