/thirdparty/breakpad/client/minidump_file_writer.h

http://github.com/tomahawk-player/tomahawk · C Header · 251 lines · 89 code · 46 blank · 116 comment · 2 complexity · 4c9dc2521b91b72ba04f38a4771aa42b MD5 · raw file

  1. // Copyright (c) 2006, Google Inc.
  2. // All rights reserved.
  3. //
  4. // Redistribution and use in source and binary forms, with or without
  5. // modification, are permitted provided that the following conditions are
  6. // met:
  7. //
  8. // * Redistributions of source code must retain the above copyright
  9. // notice, this list of conditions and the following disclaimer.
  10. // * Redistributions in binary form must reproduce the above
  11. // copyright notice, this list of conditions and the following disclaimer
  12. // in the documentation and/or other materials provided with the
  13. // distribution.
  14. // * Neither the name of Google Inc. nor the names of its
  15. // contributors may be used to endorse or promote products derived from
  16. // this software without specific prior written permission.
  17. //
  18. // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22. // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23. // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24. // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25. // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26. // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28. // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. // minidump_file_writer.h: Implements file-based minidump generation. It's
  30. // intended to be used with the Google Breakpad open source crash handling
  31. // project.
  32. #ifndef CLIENT_MINIDUMP_FILE_WRITER_H__
  33. #define CLIENT_MINIDUMP_FILE_WRITER_H__
  34. #include <string>
  35. #include "google_breakpad/common/minidump_format.h"
  36. namespace google_breakpad {
  37. class UntypedMDRVA;
  38. template<typename MDType> class TypedMDRVA;
  39. // The user of this class can Open() a file and add minidump streams, data, and
  40. // strings using the definitions in minidump_format.h. Since this class is
  41. // expected to be used in a situation where the current process may be
  42. // damaged, it will not allocate heap memory.
  43. // Sample usage:
  44. // MinidumpFileWriter writer;
  45. // writer.Open("/tmp/minidump.dmp");
  46. // TypedMDRVA<MDRawHeader> header(&writer_);
  47. // header.Allocate();
  48. // header->get()->signature = MD_HEADER_SIGNATURE;
  49. // :
  50. // writer.Close();
  51. class MinidumpFileWriter {
  52. public:
  53. // Invalid MDRVA (Minidump Relative Virtual Address)
  54. // returned on failed allocation
  55. static const MDRVA kInvalidMDRVA;
  56. MinidumpFileWriter();
  57. ~MinidumpFileWriter();
  58. // Open |path| as the destination of the minidump data. Any existing file
  59. // will be overwritten.
  60. // Return true on success, or false on failure
  61. bool Open(const char *path);
  62. // Close the current file
  63. // Return true on success, or false on failure
  64. bool Close();
  65. // Copy the contents of |str| to a MDString and write it to the file.
  66. // |str| is expected to be either UTF-16 or UTF-32 depending on the size
  67. // of wchar_t.
  68. // Maximum |length| of characters to copy from |str|, or specify 0 to use the
  69. // entire NULL terminated string. Copying will stop at the first NULL.
  70. // |location| the allocated location
  71. // Return true on success, or false on failure
  72. bool WriteString(const wchar_t *str, unsigned int length,
  73. MDLocationDescriptor *location);
  74. // Same as above, except with |str| as a UTF-8 string
  75. bool WriteString(const char *str, unsigned int length,
  76. MDLocationDescriptor *location);
  77. // Write |size| bytes starting at |src| into the current position.
  78. // Return true on success and set |output| to position, or false on failure
  79. bool WriteMemory(const void *src, size_t size, MDMemoryDescriptor *output);
  80. // Copies |size| bytes from |src| to |position|
  81. // Return true on success, or false on failure
  82. bool Copy(MDRVA position, const void *src, ssize_t size);
  83. // Return the current position for writing to the minidump
  84. inline MDRVA position() const { return position_; }
  85. private:
  86. friend class UntypedMDRVA;
  87. // Allocates an area of |size| bytes.
  88. // Returns the position of the allocation, or kInvalidMDRVA if it was
  89. // unable to allocate the bytes.
  90. MDRVA Allocate(size_t size);
  91. // The file descriptor for the output file
  92. int file_;
  93. // Current position in buffer
  94. MDRVA position_;
  95. // Current allocated size
  96. size_t size_;
  97. // Copy |length| characters from |str| to |mdstring|. These are distinct
  98. // because the underlying MDString is a UTF-16 based string. The wchar_t
  99. // variant may need to create a MDString that has more characters than the
  100. // source |str|, whereas the UTF-8 variant may coalesce characters to form
  101. // a single UTF-16 character.
  102. bool CopyStringToMDString(const wchar_t *str, unsigned int length,
  103. TypedMDRVA<MDString> *mdstring);
  104. bool CopyStringToMDString(const char *str, unsigned int length,
  105. TypedMDRVA<MDString> *mdstring);
  106. // The common templated code for writing a string
  107. template <typename CharType>
  108. bool WriteStringCore(const CharType *str, unsigned int length,
  109. MDLocationDescriptor *location);
  110. };
  111. // Represents an untyped allocated chunk
  112. class UntypedMDRVA {
  113. public:
  114. explicit UntypedMDRVA(MinidumpFileWriter *writer)
  115. : writer_(writer),
  116. position_(writer->position()),
  117. size_(0) {}
  118. // Allocates |size| bytes. Must not call more than once.
  119. // Return true on success, or false on failure
  120. bool Allocate(size_t size);
  121. // Returns the current position or kInvalidMDRVA if allocation failed
  122. inline MDRVA position() const { return position_; }
  123. // Number of bytes allocated
  124. inline size_t size() const { return size_; }
  125. // Return size and position
  126. inline MDLocationDescriptor location() const {
  127. MDLocationDescriptor location = { static_cast<u_int32_t>(size_),
  128. position_ };
  129. return location;
  130. }
  131. // Copy |size| bytes starting at |src| into the minidump at |position|
  132. // Return true on success, or false on failure
  133. bool Copy(MDRVA position, const void *src, size_t size);
  134. // Copy |size| bytes from |src| to the current position
  135. inline bool Copy(const void *src, size_t size) {
  136. return Copy(position_, src, size);
  137. }
  138. protected:
  139. // Writer we associate with
  140. MinidumpFileWriter *writer_;
  141. // Position of the start of the data
  142. MDRVA position_;
  143. // Allocated size
  144. size_t size_;
  145. };
  146. // Represents a Minidump object chunk. Additional memory can be allocated at
  147. // the end of the object as a:
  148. // - single allocation
  149. // - Array of MDType objects
  150. // - A MDType object followed by an array
  151. template<typename MDType>
  152. class TypedMDRVA : public UntypedMDRVA {
  153. public:
  154. // Constructs an unallocated MDRVA
  155. explicit TypedMDRVA(MinidumpFileWriter *writer)
  156. : UntypedMDRVA(writer),
  157. data_(),
  158. allocation_state_(UNALLOCATED) {}
  159. inline ~TypedMDRVA() {
  160. // Ensure that the data_ object is written out
  161. if (allocation_state_ != ARRAY)
  162. Flush();
  163. }
  164. // Address of object data_ of MDType. This is not declared const as the
  165. // typical usage will be to access the underlying |data_| object as to
  166. // alter its contents.
  167. MDType *get() { return &data_; }
  168. // Allocates minidump_size<MDType>::size() bytes.
  169. // Must not call more than once.
  170. // Return true on success, or false on failure
  171. bool Allocate();
  172. // Allocates minidump_size<MDType>::size() + |additional| bytes.
  173. // Must not call more than once.
  174. // Return true on success, or false on failure
  175. bool Allocate(size_t additional);
  176. // Allocate an array of |count| elements of MDType.
  177. // Must not call more than once.
  178. // Return true on success, or false on failure
  179. bool AllocateArray(size_t count);
  180. // Allocate an array of |count| elements of |size| after object of MDType
  181. // Must not call more than once.
  182. // Return true on success, or false on failure
  183. bool AllocateObjectAndArray(size_t count, size_t size);
  184. // Copy |item| to |index|
  185. // Must have been allocated using AllocateArray().
  186. // Return true on success, or false on failure
  187. bool CopyIndex(unsigned int index, MDType *item);
  188. // Copy |size| bytes starting at |str| to |index|
  189. // Must have been allocated using AllocateObjectAndArray().
  190. // Return true on success, or false on failure
  191. bool CopyIndexAfterObject(unsigned int index, const void *src, size_t size);
  192. // Write data_
  193. bool Flush();
  194. private:
  195. enum AllocationState {
  196. UNALLOCATED = 0,
  197. SINGLE_OBJECT,
  198. ARRAY,
  199. SINGLE_OBJECT_WITH_ARRAY
  200. };
  201. MDType data_;
  202. AllocationState allocation_state_;
  203. };
  204. } // namespace google_breakpad
  205. #endif // CLIENT_MINIDUMP_FILE_WRITER_H__