crashpad client for windows

client/crashpad_client.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,
@@ skipping 31 matching lines @@
   //! This method does not actually direct any crashes to the Crashpad handler,
   //! because there may be alternative ways to use an existing Crashpad handler
   //! without having to start one. To begin directing crashes to the handler,
   //! started by this method, call UseHandler() after this method returns
   //! successfully.
   //!
   //! On Mac OS X, this method starts a Crashpad handler and obtains a Mach
   //! send right corresponding to a receive right held by the handler process.
   //! The handler process runs an exception server on this port.
   //!
+  //! On Windows, SetHandler() is normally used instead since the handler is
+  //! started by other means.
+  //!
   //! \param[in] handler The path to a Crashpad handler executable.
   //! \param[in] database The path to a Crashpad database. The handler will be
   //!     started with this path as its `--database` argument.
   //! \param[in] url The URL of an upload server. The handler will be started
   //!     with this URL as its `--url` argument.
   //! \param[in] annotations Process annotations to set in each crash report.
   //!     The handler will be started with an `--annotation` argument for each
   //!     element in this map.
   //! \param[in] arguments Additional arguments to pass to the Crashpad handler.
   //!     Arguments passed in other parameters and arguments required to perform
   //!     the handshake are the responsibility of this method, and must not be
   //!     specified in this parameter.
   //!
   //! \return `true` on success, `false` on failure with a message logged.
   bool StartHandler(const base::FilePath& handler,
                     const base::FilePath& database,
                     const std::string& url,
                     const std::map<std::string, std::string>& annotations,
                     const std::vector<std::string>& arguments);
 
+  //! \brief Sets the IPC port of a presumably running Crashpad handler process

[Mark Mentovai, 2015/04/28 17:53:04]

presumably-running

+  //!     which was started with StartHandler() or by other compatible means
+  //!     and does an IPC message exchange to register this process with the
+  //!     handler. However, just like StartHandler() crashes are not serviced

[Mark Mentovai, 2015/04/28 17:53:05]

comma after StartHandler()

+  //!     until UseHandler() is called.
+  //!
+  //! The IPC port name (somehow) encodes enough information so that

[scottmg, 2015/04/24 04:55:06]

Maybe make the "enough information" explicit parameters here and then the body
of SetHandler can turn them into an pipe name + args?

... but then it's almost the same as StartHandler's paramaters. I guess the
semantics are slightly different since it's not going to ensure the handler is
running?

[cpu_(ooo_6.6-7.5), 2015/04/24 19:40:11]

The "encodes" is misleading, I think the pipe name could be simple like it is
today, (just encodes the user SID) or it can have other things like chrome
channel. I am not sure if this encoding can be done at this layer. I guess if
crashpad was the only one launching caps it could be just StartHandler() but if
caps can be started by the shell (as startup items) then it seems weird here.

+  //! registration is done with a crash handler using the appropiate database
+  //! and upload server.
+  //!
+  //! \param[in] the full name of the crash handler IPC port.

[scottmg, 2015/04/24 04:55:06]

I think this should be

  \param[in] ipc_port the full name of the crash handler IPC port.

[Mark Mentovai, 2015/04/28 17:53:05]

scottmg wrote:
Yeah, and with a capital 't' on “The”.

[cpu_(ooo_6.6-7.5), 2015/04/29 01:34:17]

Acknowledged.

+  //!
+  //! \return 'true' on success `false` on failure.

[scottmg, 2015/04/24 04:55:06]

`true` instead of 'true'

[Mark Mentovai, 2015/04/28 17:53:04]

and a comma or an “and” in between the true and false.

[cpu_(ooo_6.6-7.5), 2015/04/29 01:34:17]

Acknowledged.

+  bool SetHandler(const std::string& ipc_port);

[scottmg, 2015/04/24 04:55:06]

Probably just make this #if WIN and remove from the .mm file.

[Mark Mentovai, 2015/04/28 17:53:04]

scottmg wrote:
I agree with this for now, at least. There will be a SetHandler() for Mac, but
it’ll accept a mach_port_t, not a const std::string&.

[cpu_(ooo_6.6-7.5), 2015/04/29 01:34:17]

Acknowledged.

+
   //! \brief Configures the process to direct its crashes to a Crashpad handler.
   //!
-  //! The Crashpad handler must previously have been started by StartHandler().
+  //! The Crashpad handler must previously have been started by StartHandler()
+  //! or contacted by SetHandler().

[Mark Mentovai, 2015/04/28 17:53:05]

SetHandler() may not need to contact the handler, so this can get away with
being less specific and saying “configured” instead of “contacted”.

[cpu_(ooo_6.6-7.5), 2015/04/29 01:34:17]

Acknowledged.

   //!
   //! On Mac OS X, this method sets the task’s exception port for `EXC_CRASH`,
   //! `EXC_RESOURCE`, and `EXC_GUARD` exceptions to the Mach send right obtained
   //! by StartHandler(). The handler will be installed with behavior
   //! `EXCEPTION_STATE_IDENTITY | MACH_EXCEPTION_CODES` and thread state flavor
   //! `MACHINE_THREAD_STATE`. Exception ports are inherited, so a Crashpad
   //! handler chosen by UseHandler() will remain the handler for any child
   //! processes created after UseHandler() is called. Child processes do not
   //! need to call StartHandler() or UseHandler() or be aware of Crashpad in any
   //! way. The Crashpad handler will receive crashes from child processes that
   //! have inherited it as their exception handler even after the process that
   //! called StartHandler() exits.
   //!
+  //! On Windows, this method sets the unhandled exception handler to a local
+  //! function that when reached it will "signal and wait" for the crash
+  //! handler process to create the dump.
+  //!
   //! \return `true` on success, `false` on failure with a message logged.
   bool UseHandler();
 
  private:
 #if defined(OS_MACOSX)
   base::mac::ScopedMachSendRight exception_port_;
 #endif
 
   DISALLOW_COPY_AND_ASSIGN(CrashpadClient);
 };
 
 }  // namespace crashpad
 
 #endif  // CRASHPAD_CLIENT_CRASHPAD_CLIENT_H_