Add MinidumpFileWriter

minidump/minidump_file_writer.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_MINIDUMP_MINIDUMP_FILE_WRITER_H_
+#define CRASHPAD_MINIDUMP_MINIDUMP_FILE_WRITER_H_
+
+#include <dbghelp.h>
+#include <sys/types.h>
+
+#include <set>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "minidump/minidump_stream_writer.h"
+#include "minidump/minidump_writable.h"
+#include "util/file/file_writer.h"
+
+namespace crashpad {
+
+//! \brief The root-level object in a minidump file.
+//!
+//! This object writes a MINIDUMP_HEADER and list of MINIDUMP_DIRECTORY entries
+//! to a minidump file.
+class MinidumpFileWriter final : public internal::MinidumpWritable {
+ public:
+  MinidumpFileWriter();
+  ~MinidumpFileWriter();
+
+  //! \brief Sets MINIDUMP_HEADER::Timestamp.
+  //!
+  //! \note Valid in #kStateMutable.
+  void SetTimestamp(time_t timestamp);
+
+  //! \brief Adds a stream to the minidump file as a child of the object, and
+  //!     arranges for a MINIDUMP_DIRECTORY entry to point to it.
+  //!
+  //! At most one object of each stream type (as obtained from
+  //! internal::MinidumpStreamWriter::StreamType()) may be added to a
+  //! MinidumpFileWriter object. It is an error to attempt to add multiple
+  //! streams with the same stream type.
+  //!
+  //! \note Valid in #kStateMutable.
+  void AddStream(internal::MinidumpStreamWriter* stream);

[Robert Sesek, 2014/08/03 15:19:59]

It's a bit weird to have a public method in the non-internal:: namespace
accepting an internal:: param type.

[Robert Sesek, 2014/08/03 15:19:59]

What are the ownership semantics here?

[Mark Mentovai, 2014/08/03 20:14:10]

rsesek wrote:
The idea is that the internal namespace is shared by the Minidump*Writer family
of classes, so we’ll have MinidumpSystemInfoWriter and others that implement
internal::MinidumpStreamWriter. Users outside of this class family shouldn’t
touch anything in internal directly, but they’re allowed to make a
MinidumpSystemInfoWriter and pass it to this function.

Is this worth a comment? I don’t really know where to put it. On the
MinidumpStreamWriter class, maybe?

[Robert Sesek, 2014/08/03 21:20:55]

Got it, since MinidumpSystemInfoWriter won't be internal:: only its base class
will, that seems fine as-is.

+
+  // MinidumpWritable:
+
+  //! \copydoc internal::MinidumpWritable::WriteEverything()
+  //!
+  //! This method does not initially write the final value for
+  //! MINIDUMP_HEADER::Signature. After all child objects have been written, it
+  //! rewinds to the beginning of the file and writes the correct value for this
+  //! field. This prevents incompletely-written minidump files from being
+  //! mistaken for valid ones.
+  virtual bool WriteEverything(FileWriterInterface* file_writer) override;
+
+ protected:
+  // MinidumpWritable:
+  virtual bool Freeze() override;
+  virtual size_t SizeOfObject() override;
+  virtual std::vector<MinidumpWritable*> Children() override;

[Robert Sesek, 2014/08/03 15:19:59]

Should this be a type of internal::MinidumpWritable?

[Mark Mentovai, 2014/08/03 20:14:10]

rsesek wrote:
It is. Since MinidumpFileWriter inherits from internal::MinidumpWritable, it’s
able to use that type name without the internal:: qualification.

[Robert Sesek, 2014/08/03 21:20:55]

Right, it was just inconsistent with the .cc file (since you're required to
place the internal:: qualifier on the definition).

[Mark Mentovai, 2014/08/03 22:45:54]

rsesek wrote:
It’s not clear if you want me to change this, so I’m leaving it. It’s the same
situation as

class C {
 public:
  typedef int T;
  T F();
};

C::T F() {  // need to qualify with C here
  T t = …;  // but not here
  return t;
}

+  virtual bool WillWriteAtOffsetImpl(off_t offset) override;
+  virtual bool WriteObject(FileWriterInterface* file_writer) override;
+
+ private:
+  MINIDUMP_HEADER header_;
+  std::vector<internal::MinidumpStreamWriter*> streams_;

[Robert Sesek, 2014/08/03 15:19:59]

Ownership?

+
+  // Protects against multiple streams with the same ID being added.
+  std::set<MinidumpStreamType> stream_types_;
+
+  DISALLOW_COPY_AND_ASSIGN(MinidumpFileWriter);
+};
+
+}  // namespace crashpad
+
+#endif  // CRASHPAD_MINIDUMP_MINIDUMP_WRITER_H_