Add the AnnotationSnapshot object and attach it to ModuleSnapshot.

The AnnotationSnapshot is the handler-side of the Annotation object,
which will store the annotation data when read by a ProcessReader.

Bug: crashpad:192
Change-Id: Ic65c95022c452522678c1070c27c429dd631fb64
Reviewed-on: https://chromium-review.googlesource.com/717197
Commit-Queue: Robert Sesek <rsesek@chromium.org>
Reviewed-by: Mark Mentovai <mark@chromium.org>

snapshot/annotation_snapshot.cc

@@ -0,0 +1,32 @@
+// Copyright 2017 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "snapshot/annotation_snapshot.h"
+
+namespace crashpad {
+
+AnnotationSnapshot::AnnotationSnapshot() : name(), type(0), value() {}
+
+AnnotationSnapshot::AnnotationSnapshot(const std::string& name,
+                                       uint16_t type,
+                                       const std::vector<uint8_t>& value)
+    : name(name), type(type), value(value) {}
+
+AnnotationSnapshot::~AnnotationSnapshot() = default;
+
+bool AnnotationSnapshot::operator==(const AnnotationSnapshot& other) const {
+  return name == other.name && type == other.type && value == other.value;
+}
+
+}  // namespace crashpad

snapshot/annotation_snapshot.h

@@ -0,0 +1,54 @@
+// Copyright 2017 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef CRASHPAD_SNAPSHOT_ANNOTATION_SNAPSHOT_H_
+#define CRASHPAD_SNAPSHOT_ANNOTATION_SNAPSHOT_H_
+
+#include <stdint.h>
+
+#include <string>
+#include <vector>
+
+namespace crashpad {
+
+// \!brief The snapshot representation of a client's Annotation.
+struct AnnotationSnapshot {
+  AnnotationSnapshot();
+  AnnotationSnapshot(const std::string& name,
+                     uint16_t type,
+                     const std::vector<uint8_t>& value);
+  ~AnnotationSnapshot();
+
+  bool operator==(const AnnotationSnapshot& other) const;
+  bool operator!=(const AnnotationSnapshot& other) const {
+    return !(*this == other);
+  }
+
+  //! \brief A non-unique name by which this annotation can be identified.
+  std::string name;
+
+  //! \brief The Annotation::Type of data stored in the annotation. This value
+  //!     may be client-supplied and need not correspond to a Crashpad-defined
+  //!     type.
+  uint16_t type;
+
+  //! \brief The data for the annotation. Guranteed to be non-empty, since
+  //!     empty annotations are skipped. The representation of the data should
+  //!     be interpreted as \a #type.
+  std::vector<uint8_t> value;
+};
+
+}  // namespace crashpad
+
+#endif  // CRASHPAD_SNAPSHOT_ANNOTATION_SNAPSHOT_H_

snapshot/mac/module_snapshot_mac.cc

@@ -185,6 +185,12 @@ std::map<std::string, std::string> ModuleSnapshotMac::AnnotationsSimpleMap()
   return annotations_reader.SimpleMap();
 }
 
+std::vector<AnnotationSnapshot> ModuleSnapshotMac::AnnotationObjects() const {
+  INITIALIZATION_STATE_DCHECK_VALID(initialized_);
+  NOTREACHED();
+  return {};
+}
+
 std::set<CheckedRange<uint64_t>> ModuleSnapshotMac::ExtraMemoryRanges() const {
   INITIALIZATION_STATE_DCHECK_VALID(initialized_);
   return std::set<CheckedRange<uint64_t>>();

snapshot/mac/module_snapshot_mac.h

@@ -79,6 +79,7 @@ class ModuleSnapshotMac final : public ModuleSnapshot {
   std::string DebugFileName() const override;
   std::vector<std::string> AnnotationsVector() const override;
   std::map<std::string, std::string> AnnotationsSimpleMap() const override;
+  std::vector<AnnotationSnapshot> AnnotationObjects() const override;
   std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const override;
   std::vector<const UserMinidumpStream*> CustomMinidumpStreams() const override;
 

snapshot/minidump/module_snapshot_minidump.cc

@@ -135,6 +135,13 @@ ModuleSnapshotMinidump::AnnotationsSimpleMap() const {
   return annotations_simple_map_;
 }
 
+std::vector<AnnotationSnapshot> ModuleSnapshotMinidump::AnnotationObjects()
+    const {
+  INITIALIZATION_STATE_DCHECK_VALID(initialized_);
+  NOTREACHED();
+  return {};
+}
+
 std::set<CheckedRange<uint64_t>> ModuleSnapshotMinidump::ExtraMemoryRanges()
     const {
   INITIALIZATION_STATE_DCHECK_VALID(initialized_);

snapshot/minidump/module_snapshot_minidump.h

@@ -76,6 +76,7 @@ class ModuleSnapshotMinidump final : public ModuleSnapshot {
   std::string DebugFileName() const override;
   std::vector<std::string> AnnotationsVector() const override;
   std::map<std::string, std::string> AnnotationsSimpleMap() const override;
+  std::vector<AnnotationSnapshot> AnnotationObjects() const override;
   std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const override;
   std::vector<const UserMinidumpStream*> CustomMinidumpStreams() const override;
 

snapshot/module_snapshot.h

@@ -24,6 +24,7 @@
 #include <string>
 #include <vector>
 
+#include "snapshot/annotation_snapshot.h"
 #include "snapshot/memory_snapshot.h"
 #include "util/misc/uuid.h"
 #include "util/numeric/checked_range.h"
@@ -172,7 +173,7 @@ class ModuleSnapshot {
   //! (`dyld`) can provide an annotation at its `_error_string` symbol.
   //!
   //! The annotations returned by this method do not duplicate those returned by
-  //! AnnotationsSimpleMap().
+  //! AnnotationsSimpleMap() or AnnotationObjects().
   virtual std::vector<std::string> AnnotationsVector() const = 0;
 
   //! \brief Returns key-value string annotations recorded in the module.
@@ -190,11 +191,27 @@ class ModuleSnapshot {
   //! method. For clients such as Chrome, this includes the process type.
   //!
   //! The annotations returned by this method do not duplicate those returned by
-  //! AnnotationsVector(). Additional annotations related to the process,
+  //! AnnotationsVector() or AnnotationObjects(). Additional annotations related
-  //! system, or snapshot producer may be obtained by calling
+  //! to the process, system, or snapshot producer may be obtained by calling
   //! ProcessSnapshot::AnnotationsSimpleMap().
   virtual std::map<std::string, std::string> AnnotationsSimpleMap() const = 0;
 
+  //! \brief Returns the typed annotation objects recorded in the module.
+  //!
+  //! This method retrieves annotations recorded in a module. These annotations
+  //! are intended for diagnostic use, including crash analysis. Annotation
+  //! objects are strongly-typed name-value pairs. The names are not unique.
+  //!
+  //! For macOS snapshots, these annotations are found by interpreting the
+  //! `__DATA,crashpad_info` section as `CrashpadInfo`. Clients can use the
+  //! Crashpad client interface to store annotations in this structure. Most
+  //! annotations under the client’s direct control will be retrievable by this
+  //! method. For clients such as Chrome, this includes the process type.
+  //!
+  //! The annotations returned by this method do not duplicate those returned by
+  //! AnnotationsVector() or AnnotationsSimpleMap().
+  virtual std::vector<AnnotationSnapshot> AnnotationObjects() const = 0;
+
   //! \brief Returns a set of extra memory ranges specified in the module as
   //!     being desirable to include in the crash dump.
   virtual std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const = 0;

snapshot/snapshot.gyp

@@ -30,6 +30,8 @@
         '..',
       ],
       'sources': [
+        'annotation_snapshot.cc',
+        'annotation_snapshot.h',
         'capture_memory.cc',
         'capture_memory.h',
         'cpu_architecture.h',

snapshot/test/test_module_snapshot.cc

@@ -94,6 +94,10 @@ std::map<std::string, std::string> TestModuleSnapshot::AnnotationsSimpleMap()
   return annotations_simple_map_;
 }
 
+std::vector<AnnotationSnapshot> TestModuleSnapshot::AnnotationObjects() const {
+  return annotation_objects_;
+}
+
 std::set<CheckedRange<uint64_t>> TestModuleSnapshot::ExtraMemoryRanges() const {
   return extra_memory_ranges_;
 }

snapshot/test/test_module_snapshot.h

@@ -75,6 +75,10 @@ class TestModuleSnapshot final : public ModuleSnapshot {
       const std::map<std::string, std::string>& annotations_simple_map) {
     annotations_simple_map_ = annotations_simple_map;
   }
+  void SetAnnotationObjects(
+      const std::vector<AnnotationSnapshot>& annotations) {
+    annotation_objects_ = annotations;
+  }
   void SetExtraMemoryRanges(
       const std::set<CheckedRange<uint64_t>>& extra_memory_ranges) {
     extra_memory_ranges_ = extra_memory_ranges;
@@ -99,6 +103,7 @@ class TestModuleSnapshot final : public ModuleSnapshot {
   std::string DebugFileName() const override;
   std::vector<std::string> AnnotationsVector() const override;
   std::map<std::string, std::string> AnnotationsSimpleMap() const override;
+  std::vector<AnnotationSnapshot> AnnotationObjects() const override;
   std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const override;
   std::vector<const UserMinidumpStream*> CustomMinidumpStreams() const override;
 
@@ -115,6 +120,7 @@ class TestModuleSnapshot final : public ModuleSnapshot {
   std::string debug_file_name_;
   std::vector<std::string> annotations_vector_;
   std::map<std::string, std::string> annotations_simple_map_;
+  std::vector<AnnotationSnapshot> annotation_objects_;
   std::set<CheckedRange<uint64_t>> extra_memory_ranges_;
 
   DISALLOW_COPY_AND_ASSIGN(TestModuleSnapshot);

snapshot/win/module_snapshot_win.cc

@@ -190,6 +190,12 @@ std::map<std::string, std::string> ModuleSnapshotWin::AnnotationsSimpleMap()
   return annotations_reader.SimpleMap();
 }
 
+std::vector<AnnotationSnapshot> ModuleSnapshotWin::AnnotationObjects() const {
+  INITIALIZATION_STATE_DCHECK_VALID(initialized_);
+  NOTREACHED();
+  return {};
+}
+
 std::set<CheckedRange<uint64_t>> ModuleSnapshotWin::ExtraMemoryRanges() const {
   INITIALIZATION_STATE_DCHECK_VALID(initialized_);
   std::set<CheckedRange<uint64_t>> ranges;

snapshot/win/module_snapshot_win.h

@@ -85,6 +85,7 @@ class ModuleSnapshotWin final : public ModuleSnapshot {
   std::string DebugFileName() const override;
   std::vector<std::string> AnnotationsVector() const override;
   std::map<std::string, std::string> AnnotationsSimpleMap() const override;
+  std::vector<AnnotationSnapshot> AnnotationObjects() const override;
   std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const override;
   std::vector<const UserMinidumpStream*> CustomMinidumpStreams() const override;