1  // Copyright 2006 Google LLC
 2  //
 3  // Redistribution and use in source and binary forms, with or without
 4  // modification, are permitted provided that the following conditions are
 5  // met:
 6  //
 7  //     * Redistributions of source code must retain the above copyright
 8  // notice, this list of conditions and the following disclaimer.
 9  //     * Redistributions in binary form must reproduce the above
10  // copyright notice, this list of conditions and the following disclaimer
11  // in the documentation and/or other materials provided with the
12  // distribution.
13  //     * Neither the name of Google LLC nor the names of its
14  // contributors may be used to endorse or promote products derived from
15  // this software without specific prior written permission.
16  //
17  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20  // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21  // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22  // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23  // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24  // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25  // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26  // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27  // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  
29  // The caller may implement the SymbolSupplier abstract base class
30  // to provide symbols for a given module.
31  
32  #ifndef GOOGLE_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H__
33  #define GOOGLE_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H__
34  
35  #include <string>
36  #include "common/using_std_string.h"
37  
38  namespace google_breakpad {
39  
40  class CodeModule;
41  struct SystemInfo;
42  
43  class SymbolSupplier {
44   public:
45    // Result type for GetSymbolFile
46    enum SymbolResult {
47      // no symbols were found, but continue processing
48      NOT_FOUND,
49  
50      // symbols were found, and the path has been placed in symbol_file
51      FOUND,
52  
53      // stops processing the minidump immediately
54      INTERRUPT
55    };
56  
57    virtual ~SymbolSupplier() {}
58  
59    // Retrieves the symbol file for the given CodeModule, placing the
60    // path in symbol_file if successful.  system_info contains strings
61    // identifying the operating system and CPU; SymbolSupplier may use
62    // to help locate the symbol file.  system_info may be NULL or its
63    // fields may be empty if these values are unknown.  symbol_file
64    // must be a pointer to a valid string
65    virtual SymbolResult GetSymbolFile(const CodeModule* module,
66                                       const SystemInfo* system_info,
67                                       string* symbol_file) = 0;
68    // Same as above, except also places symbol data into symbol_data.
69    // If symbol_data is NULL, the data is not returned.
70    // TODO(nealsid) Once we have symbol data caching behavior implemented
71    // investigate making all symbol suppliers implement all methods,
72    // and make this pure virtual
73    virtual SymbolResult GetSymbolFile(const CodeModule* module,
74                                       const SystemInfo* system_info,
75                                       string* symbol_file,
76                                       string* symbol_data) = 0;
77  
78    // Same as above, except allocates data buffer on heap and then places the
79    // symbol data into the buffer as C-string.
80    // SymbolSupplier is responsible for deleting the data buffer. After the call
81    // to GetCStringSymbolData(), the caller should call FreeSymbolData(const
82    // Module* module) once the data buffer is no longer needed.
83    // If symbol_data is not NULL, symbol supplier won't return FOUND unless it
84    // returns a valid buffer in symbol_data, e.g., returns INTERRUPT on memory
85    // allocation failure.
86    virtual SymbolResult GetCStringSymbolData(const CodeModule* module,
87                                              const SystemInfo* system_info,
88                                              string* symbol_file,
89                                              char** symbol_data,
90                                              size_t* symbol_data_size) = 0;
91  
92    // Frees the data buffer allocated for the module in GetCStringSymbolData.
93    virtual void FreeSymbolData(const CodeModule* module) = 0;
94  };
95  
96  }  // namespace google_breakpad
97  
98  #endif  // GOOGLE_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H__