/thirdparty/breakpad/client/mac/Framework/Breakpad.h

http://github.com/tomahawk-player/tomahawk · C++ Header · 280 lines · 28 code · 16 blank · 236 comment · 0 complexity · fb97cbd5a411bb57f971aecaec8ddd74 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. //
  30. // Framework to provide a simple C API to crash reporting for
  31. // applications. By default, if any machine-level exception (e.g.,
  32. // EXC_BAD_ACCESS) occurs, it will be handled by the BreakpadRef
  33. // object as follows:
  34. //
  35. // 1. Create a minidump file (see Breakpad for details)
  36. // 2. Prompt the user (using CFUserNotification)
  37. // 3. Invoke a command line reporting tool to send the minidump to a
  38. // server
  39. //
  40. // By specifying parameters to the BreakpadCreate function, you can
  41. // modify the default behavior to suit your needs and wants and
  42. // desires.
  43. // A service name associated with the original bootstrap parent port, saved in
  44. // OnDemandServer and restored in Inspector.
  45. #define BREAKPAD_BOOTSTRAP_PARENT_PORT "com.Breakpad.BootstrapParent"
  46. typedef void *BreakpadRef;
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50. #include <CoreFoundation/CoreFoundation.h>
  51. #include <Foundation/Foundation.h>
  52. #include "BreakpadDefines.h"
  53. // Optional user-defined function to dec to decide if we should handle
  54. // this crash or forward it along.
  55. // Return true if you want Breakpad to handle it.
  56. // Return false if you want Breakpad to skip it
  57. // The exception handler always returns false, as if SEND_AND_EXIT were false
  58. // (which means the next exception handler will take the exception)
  59. typedef bool (*BreakpadFilterCallback)(int exception_type,
  60. int exception_code,
  61. mach_port_t crashing_thread,
  62. void *context);
  63. // Create a new BreakpadRef object and install it as an exception
  64. // handler. The |parameters| will typically be the contents of your
  65. // bundle's Info.plist.
  66. //
  67. // You can also specify these additional keys for customizable behavior:
  68. // Key: Value:
  69. // BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct")
  70. // This one is used as the key to identify
  71. // the product when uploading. Falls back to
  72. // CFBundleName if not specified.
  73. // REQUIRED
  74. //
  75. // BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty
  76. // name for the product when the crash_sender
  77. // pops up UI for the user. Falls back first to
  78. // CFBundleDisplayName and then to
  79. // BREAKPAD_PRODUCT if not specified.
  80. //
  81. // BREAKPAD_VERSION Product version (e.g., 1.2.3), used
  82. // as metadata for crash report. Falls back to
  83. // CFBundleVersion if not specified.
  84. // REQUIRED
  85. //
  86. // BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has
  87. // been created that you can send to <vendor>")
  88. //
  89. // BREAKPAD_URL URL destination for reporting
  90. // REQUIRED
  91. //
  92. // BREAKPAD_REPORT_INTERVAL # of seconds between sending
  93. // reports. If an additional report is
  94. // generated within this time, it will
  95. // be ignored. Default: 3600sec.
  96. // Specify 0 to send all reports.
  97. //
  98. // BREAKPAD_SKIP_CONFIRM If true, the reporter will send the report
  99. // without any user intervention.
  100. // Defaults to NO
  101. //
  102. // BREAKPAD_CONFIRM_TIMEOUT Number of seconds before the upload
  103. // confirmation dialog will be automatically
  104. // dismissed (cancelling the upload).
  105. // Default: 300 seconds (min of 60).
  106. // Specify 0 to prevent timeout.
  107. //
  108. // BREAKPAD_SEND_AND_EXIT If true, the handler will exit after sending.
  109. // This will prevent any other handler (e.g.,
  110. // CrashReporter) from getting the crash.
  111. // Defaults TO YES
  112. //
  113. // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps
  114. // in. By default, we use
  115. // ~/Library/Breakpad/<BREAKPAD_PRODUCT>
  116. // The path you specify here is tilde-expanded.
  117. //
  118. // BREAKPAD_INSPECTOR_LOCATION The full path to the Inspector executable.
  119. // Defaults to <Framework resources>/Inspector
  120. //
  121. // BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender
  122. // executable.
  123. // Default:
  124. // <Framework Resources>/crash_report_sender.app
  125. //
  126. // BREAKPAD_LOGFILES Indicates an array of log file paths that
  127. // should be uploaded at crash time.
  128. //
  129. // BREAKPAD_REQUEST_COMMENTS If true, the message dialog will have a
  130. // text box for the user to enter comments.
  131. // Default: NO
  132. //
  133. // BREAKPAD_REQUEST_EMAIL If true and BREAKPAD_REQUEST_COMMENTS is also
  134. // true, the message dialog will have a text
  135. // box for the user to enter their email address.
  136. // Default: NO
  137. //
  138. // BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to
  139. // rewrite the upload parameters for a specific
  140. // server type. The currently valid values are
  141. // 'socorro' or 'google'. If you want to add
  142. // other types, see the function in
  143. // crash_report_sender.m that maps parameters to
  144. // URL parameters. Defaults to 'google'.
  145. //
  146. // BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static
  147. // parameters that are uploaded to the
  148. // server. The parameters are sent as
  149. // is to the crash server. Their
  150. // content isn't added to the minidump
  151. // but pass as URL parameters when
  152. // uploading theminidump to the crash
  153. // server.
  154. //=============================================================================
  155. // The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are
  156. // required to have non-NULL values. By default, the BREAKPAD_PRODUCT
  157. // will be the CFBundleName and the BREAKPAD_VERSION will be the
  158. // CFBundleVersion when these keys are present in the bundle's
  159. // Info.plist, which is usually passed in to BreakpadCreate() as an
  160. // NSDictionary (you could also pass in another dictionary that had
  161. // the same keys configured). If the BREAKPAD_PRODUCT or
  162. // BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will
  163. // fail. You have been warned.
  164. //
  165. // If you are running in a debugger, Breakpad will not install, unless the
  166. // BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero.
  167. //
  168. // The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default
  169. // values are NO and YES. However, they can be controlled by setting their
  170. // values in a user or global plist.
  171. //
  172. // It's easiest to use Breakpad via the Framework, but if you're compiling the
  173. // code in directly, BREAKPAD_INSPECTOR_LOCATION and
  174. // BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths
  175. // to the helper executables.
  176. //
  177. //=============================================================================
  178. // The following are NOT user-supplied but are documented here for
  179. // completeness. They are calculated by Breakpad during initialization &
  180. // crash-dump generation, or entered in by the user.
  181. //
  182. // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the
  183. // process started
  184. //
  185. // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the
  186. // process crashed.
  187. //
  188. // BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process
  189. // has been running. This parameter is not
  190. // set until the crash-dump-generation phase.
  191. //
  192. // BREAKPAD_LOGFILE_KEY_PREFIX Used to find out which parameters in the
  193. // parameter dictionary correspond to log
  194. // file paths.
  195. //
  196. // BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad
  197. // internally, because Breakpad uses
  198. // the same dictionary internally to
  199. // track both its internal
  200. // configuration parameters and
  201. // parameters meant to be uploaded
  202. // to the server. This string is
  203. // used internally by Breakpad to
  204. // prefix user-supplied parameter
  205. // names so those can be sent to the
  206. // server without leaking Breakpad's
  207. // internal values.
  208. //
  209. // BREAKPAD_ON_DEMAND Used internally to indicate to the
  210. // Reporter that we're sending on-demand,
  211. // not as result of a crash.
  212. //
  213. // BREAKPAD_COMMENTS The text the user provided as comments.
  214. // Only used in crash_report_sender.
  215. // Returns a new BreakpadRef object on success, NULL otherwise.
  216. BreakpadRef BreakpadCreate(NSDictionary *parameters);
  217. // Uninstall and release the data associated with |ref|.
  218. void BreakpadRelease(BreakpadRef ref);
  219. // Clients may set an optional callback which gets called when a crash
  220. // occurs. The callback function should return |true| if we should
  221. // handle the crash, generate a crash report, etc. or |false| if we
  222. // should ignore it and forward the crash (normally to CrashReporter).
  223. // Context is a pointer to arbitrary data to make the callback with.
  224. void BreakpadSetFilterCallback(BreakpadRef ref,
  225. BreakpadFilterCallback callback,
  226. void *context);
  227. // User defined key and value string storage. Generally this is used
  228. // to configure Breakpad's internal operation, such as whether the
  229. // crash_sender should prompt the user, or the filesystem location for
  230. // the minidump file. See Breakpad.h for some parameters that can be
  231. // set. Anything longer than 255 bytes will be truncated. Note that
  232. // the string is converted to UTF8 before truncation, so any multibyte
  233. // character that straddles the 255(256 - 1 for terminator) byte limit
  234. // will be mangled.
  235. //
  236. // A maximum number of 64 key/value pairs are supported. An assert()
  237. // will fire if more than this number are set. Unfortunately, right
  238. // now, the same dictionary is used for both Breakpad's parameters AND
  239. // the Upload parameters.
  240. //
  241. // TODO (nealsid): Investigate how necessary this is if we don't
  242. // automatically upload parameters to the server anymore.
  243. // TODO (nealsid): separate server parameter dictionary from the
  244. // dictionary used to configure Breakpad, and document limits for each
  245. // independently.
  246. void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value);
  247. NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key);
  248. void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key);
  249. // You can use this method to specify parameters that will be uploaded
  250. // to the crash server. They will be automatically encoded as
  251. // necessary. Note that as mentioned above there are limits on both
  252. // the number of keys and their length.
  253. void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key,
  254. NSString *value);
  255. // This method will remove a previously-added parameter from the
  256. // upload parameter set.
  257. void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key);
  258. // Add a log file for Breakpad to read and send upon crash dump
  259. void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname);
  260. // Generate a minidump and send
  261. void BreakpadGenerateAndSendReport(BreakpadRef ref);
  262. #ifdef __cplusplus
  263. }
  264. #endif