1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef BASE_DEBUG_CRASH_LOGGING_H_
6#define BASE_DEBUG_CRASH_LOGGING_H_
7
8#include <string>
9#include <vector>
10
11#include "base/base_export.h"
12#include "base/basictypes.h"
13#include "base/strings/string_piece.h"
14
15// These functions add metadata to the upload payload when sending crash reports
16// to the crash server.
17//
18// IMPORTANT: On OS X and Linux, the key/value pairs are only sent as part of
19// the upload and are not included in the minidump!
20
21namespace base {
22namespace debug {
23
24class StackTrace;
25
26// Set or clear a specific key-value pair from the crash metadata. Keys and
27// values are terminated at the null byte.
28BASE_EXPORT void SetCrashKeyValue(const base::StringPiece& key,
29                                  const base::StringPiece& value);
30BASE_EXPORT void ClearCrashKey(const base::StringPiece& key);
31
32// Records the given StackTrace into a crash key.
33BASE_EXPORT void SetCrashKeyToStackTrace(const base::StringPiece& key,
34                                         const StackTrace& trace);
35
36// Formats |count| instruction pointers from |addresses| using %p and
37// sets the resulting string as a value for crash key |key|. A maximum of 23
38// items will be encoded, since breakpad limits values to 255 bytes.
39BASE_EXPORT void SetCrashKeyFromAddresses(const base::StringPiece& key,
40                                          const void* const* addresses,
41                                          size_t count);
42
43// A scoper that sets the specified key to value for the lifetime of the
44// object, and clears it on destruction.
45class BASE_EXPORT ScopedCrashKey {
46 public:
47  ScopedCrashKey(const base::StringPiece& key, const base::StringPiece& value);
48  ~ScopedCrashKey();
49
50 private:
51  std::string key_;
52
53  DISALLOW_COPY_AND_ASSIGN(ScopedCrashKey);
54};
55
56// Before setting values for a key, all the keys must be registered.
57struct BASE_EXPORT CrashKey {
58  // The name of the crash key, used in the above functions.
59  const char* key_name;
60
61  // The maximum length for a value. If the value is longer than this, it will
62  // be truncated. If the value is larger than the |chunk_max_length| passed to
63  // InitCrashKeys() but less than this value, it will be split into multiple
64  // numbered chunks.
65  size_t max_length;
66};
67
68// Before the crash key logging mechanism can be used, all crash keys must be
69// registered with this function. The function returns the amount of space
70// the crash reporting implementation should allocate space for the registered
71// crash keys. |chunk_max_length| is the maximum size that a value in a single
72// chunk can be.
73BASE_EXPORT size_t InitCrashKeys(const CrashKey* const keys, size_t count,
74                                 size_t chunk_max_length);
75
76// Returns the correspnding crash key object or NULL for a given key.
77BASE_EXPORT const CrashKey* LookupCrashKey(const base::StringPiece& key);
78
79// In the platform crash reporting implementation, these functions set and
80// clear the NUL-termianted key-value pairs.
81typedef void (*SetCrashKeyValueFuncT)(const base::StringPiece&,
82                                      const base::StringPiece&);
83typedef void (*ClearCrashKeyValueFuncT)(const base::StringPiece&);
84
85// Sets the function pointers that are used to integrate with the platform-
86// specific crash reporting libraries.
87BASE_EXPORT void SetCrashKeyReportingFunctions(
88    SetCrashKeyValueFuncT set_key_func,
89    ClearCrashKeyValueFuncT clear_key_func);
90
91// Helper function that breaks up a value according to the parameters
92// specified by the crash key object.
93BASE_EXPORT std::vector<std::string> ChunkCrashKeyValue(
94    const CrashKey& crash_key,
95    const base::StringPiece& value,
96    size_t chunk_max_length);
97
98// Resets the crash key system so it can be reinitialized. For testing only.
99BASE_EXPORT void ResetCrashLoggingForTesting();
100
101}  // namespace debug
102}  // namespace base
103
104#endif  // BASE_DEBUG_CRASH_LOGGING_H_
105