1// Copyright (c) 2010 Google Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10//     * Redistributions in binary form must reproduce the above
11// copyright notice, this list of conditions and the following disclaimer
12// in the documentation and/or other materials provided with the
13// distribution.
14//     * Neither the name of Google Inc. nor the names of its
15// contributors may be used to endorse or promote products derived from
16// this software without specific prior written permission.
17//
18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30#ifndef GOOGLE_BREAKPAD_CLIENT_MAC_CRASH_GENERATION_CRASH_GENERATION_SERVER_H_
31#define GOOGLE_BREAKPAD_CLIENT_MAC_CRASH_GENERATION_CRASH_GENERATION_SERVER_H_
32
33#include <stdint.h>
34
35#include <string>
36
37#include "common/mac/MachIPC.h"
38
39namespace google_breakpad {
40
41class ClientInfo;
42
43// Messages the server can read via its mach port
44enum {
45  kDumpRequestMessage     = 1,
46  kAcknowledgementMessage = 2,
47  kQuitMessage            = 3
48};
49
50// Exception details sent by the client when requesting a dump.
51struct ExceptionInfo {
52  int32_t exception_type;
53  int32_t exception_code;
54  int32_t exception_subcode;
55};
56
57class CrashGenerationServer {
58 public:
59  // WARNING: callbacks may be invoked on a different thread
60  // than that which creates the CrashGenerationServer.  They must
61  // be thread safe.
62  typedef void (*OnClientDumpRequestCallback)(void *context,
63                                              const ClientInfo &client_info,
64                                              const std::string &file_path);
65
66  typedef void (*OnClientExitingCallback)(void *context,
67                                          const ClientInfo &client_info);
68  // If a FilterCallback returns false, the dump will not be written.
69  typedef bool (*FilterCallback)(void *context);
70
71  // Create an instance with the given parameters.
72  //
73  // mach_port_name: Named server port to listen on.
74  // filter: Callback for a client to cancel writing a dump.
75  // filter_context: Context for the filter callback.
76  // dump_callback: Callback for a client crash dump request.
77  // dump_context: Context for client crash dump request callback.
78  // exit_callback: Callback for client process exit.
79  // exit_context: Context for client exit callback.
80  // generate_dumps: Whether to automatically generate dumps.
81  //     Client code of this class might want to generate dumps explicitly
82  //     in the crash dump request callback. In that case, false can be
83  //     passed for this parameter.
84  // dump_path: Path for generating dumps; required only if true is
85  //     passed for generateDumps parameter; NULL can be passed otherwise.
86  CrashGenerationServer(const char *mach_port_name,
87                        FilterCallback filter,
88                        void *filter_context,
89                        OnClientDumpRequestCallback dump_callback,
90                        void *dump_context,
91                        OnClientExitingCallback exit_callback,
92                        void *exit_context,
93                        bool generate_dumps,
94                        const std::string &dump_path);
95
96  ~CrashGenerationServer();
97
98  // Perform initialization steps needed to start listening to clients.
99  //
100  // Return true if initialization is successful; false otherwise.
101  bool Start();
102
103  // Stop the server.
104  bool Stop();
105
106 private:
107  // Return a unique filename at which a minidump can be written.
108  bool MakeMinidumpFilename(std::string &outFilename);
109
110  // Loop reading client messages and responding to them until
111  // a quit message is received.
112  static void *WaitForMessages(void *server);
113
114  // Wait for a single client message and respond to it. Returns false
115  // if a quit message was received or if an error occurred.
116  bool WaitForOneMessage();
117
118  FilterCallback filter_;
119  void *filter_context_;
120
121  OnClientDumpRequestCallback dump_callback_;
122  void *dump_context_;
123
124  OnClientExitingCallback exit_callback_;
125  void *exit_context_;
126
127  bool generate_dumps_;
128
129  std::string dump_dir_;
130
131  bool started_;
132
133  // The mach port that receives requests to dump from child processes.
134  ReceivePort receive_port_;
135
136  // The name of the mach port. Stored so the Stop method can message
137  // the background thread to shut it down.
138  std::string mach_port_name_;
139
140  // The thread that waits on the receive port.
141  pthread_t server_thread_;
142
143  // Disable copy constructor and operator=.
144  CrashGenerationServer(const CrashGenerationServer&);
145  CrashGenerationServer& operator=(const CrashGenerationServer&);
146};
147
148}  // namespace google_breakpad
149
150#endif  // GOOGLE_BREAKPAD_CLIENT_MAC_CRASH_GENERATION_CRASH_GENERATION_SERVER_H_
151