Add the Snapshot interface

snapshot/module_snapshot.h

+// Copyright 2014 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_MODULE_SNAPSHOT_H_
+#define CRASHPAD_SNAPSHOT_MODULE_SNAPSHOT_H_
+
+#include <stdint.h>
+#include <sys/types.h>
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "util/misc/uuid.h"
+
+namespace crashpad {
+
+//! \brief An abstract interface to a snapshot representing a code module
+//!     (binary image) loaded into a snapshot process.
+class ModuleSnapshot {
+ public:
+  //! \brief A module’s type.
+  enum ModuleType {
+    //! \brief The module’s type is unknown.
+    kModuleTypeUnknown = 0,
+
+    //! \brief The module is a main executable.
+    kModuleTypeExecutable,
+
+    //! \brief The module is a shared library.
+    //!
+    //! \sa kModuleTypeLoadableModule
+    kModuleTypeSharedLibrary,
+
+    //! \brief The module is a loadable module.
+    //!
+    //! On some platforms, loadable modules are distinguished from shared
+    //! libraries. On these platforms, a shared library is a module that another
+    //! module links against directly, and a loadable module is not. Loadable
+    //! modules tend to be binary plug-ins.
+    kModuleTypeLoadableModule,
+
+    //! \brief The module is a dynamic loader.
+    //!
+    //! This is the module responsible for loading other modules. This is
+    //! normally `dyld` for Mac OS X and `ld.so` for Linux and other systems
+    //! using ELF.
+    kModuleTypeDynamicLoader,
+  };
+
+  //! \brief Returns the module’s pathname.
+  virtual std::string Name() = 0;
+
+  //! \brief Returns the base address that the module is loaded at in the
+  //!     snapshot process.
+  virtual uint64_t Address() = 0;
+
+  //! \brief Returns the size that the module occupies in the snapshot process’
+  //!     address space, starting at its base address.
+  //!
+  //! For Mac OS X snapshots, this method only reports the size of the `__TEXT`
+  //! segment, because segments may not be loaded contiguously.
+  virtual uint64_t Size() = 0;
+
+  //! \brief Returns the module’s timestamp, if known.
+  //!
+  //! The timestamp is typically the modification time of the file that provided
+  //! the module in `time_t` format, seconds since the POSIX epoch. If the
+  //! module’s timestamp is unknown, this method returns `0`.
+  virtual time_t Timestamp() = 0;
+
+  //! \brief Returns the module’s file version in the \a version_* parameters.
+  //!
+  //! If no file version can be determined, the \a version_* parameters are set
+  //! to `0`.
+  //!
+  //! For Mac OS X snapshots, this is taken from the module’s `LC_ID_DYLIB` load
+  //! command for shared libraries, and is `0` for other module types.
+  virtual void FileVersion(uint16_t* version_0,

[Robert Sesek, 2014/09/25 15:44:08]

Could this take a uint16_t version[4] instead?

[Mark Mentovai, 2014/10/02 20:27:00]

Robert Sesek wrote:
It could, but that just gets downgraded to a uint16_t*, without any assurance
that the caller’s allocated the right storage size. Four separate arguments
sucks, but it lets the compiler do reasonable checking.

Other options are a struct parameter, or even a struct return value.

+                           uint16_t* version_1,
+                           uint16_t* version_2,
+                           uint16_t* version_3) = 0;
+
+  //! \brief Returns the module’s source version in the \a version_* parameters.
+  //!
+  //! If no source version can be determined, the \a version_* parameters are
+  //! set to `0`.
+  //!
+  //! For Mac OS X snapshots, this is taken from the module’s
+  //! `LC_SOURCE_VERSION` load command.
+  virtual void SourceVersion(uint16_t* version_0,
+                             uint16_t* version_1,
+                             uint16_t* version_2,
+                             uint16_t* version_3) = 0;
+
+  //! \brief Returns the module’s type.
+  virtual ModuleType GetModuleType() = 0;
+
+  //! \brief Returns the module’s UUID in the \a uuid parameter.
+  //!
+  //! A snapshot module’s UUID is taken directly from the module itself. If the
+  //! module does not have a UUID, the \a uuid parameter will be zeroed out.
+  virtual void UUID(struct UUID* uuid) = 0;

[Robert Sesek, 2014/09/25 15:44:08]

crashpad::UUID for consistency with other places?

+
+  //! \brief Returns diagnostic messages recorded in the module.
+  //!
+  //! This method retrieves diagnostic messages recorded in a module. These
+  //! messages are intended for diagnostic use, including crash analysis. A
+  //! module may contain multiple diagnostic messages.
+  //!
+  //! For Mac OS X snapshots, the diagnostic messages are found by interpreting
+  //! the module’s `__DATA, __crash_info` section as
+  //! `crashreporter_annotations_t`. System libraries using the crash reporter
+  //! client interface may reference diagnostic messages in this structure.
+  //! Additional diagnostic messages may be found in other locations, which may
+  //! be module-specific. The dynamic linker (`dyld`) can provide a diagnostic
+  //! message at its `_error_string` symbol.
+  virtual std::vector<std::string> DiagnosticMessages() = 0;
+
+  //! \brief Returns simple annotations recorded in the module.
+  //!
+  //! This method retrieves simple annotations recorded in a module. These
+  //! annotations are intended for diagnostic use, including crash analysis.
+  //! Simple annotations are structured as a sequence of key-value pairs. These
+  //! are referred to in Chrome as “crash keys.”
+  //!
+  //! For Mac OS X snapshots, simple 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.
+  virtual std::map<std::string, std::string> SimpleAnnotations() = 0;
+
+ protected:
+  ~ModuleSnapshot() {}
+};
+
+}  // namespace crashpad
+
+#endif  // CRASHPAD_SNAPSHOT_MODULE_SNAPSHOT_H_