/thirdparty/breakpad/client/windows/crash_generation/crash_generation_server.h

  1// Copyright (c) 2008, 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 CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__
 31#define CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__
 32
 33#include <list>
 34#include <string>
 35#include "client/windows/common/ipc_protocol.h"
 36#include "client/windows/crash_generation/minidump_generator.h"
 37#include "processor/scoped_ptr.h"
 38
 39namespace google_breakpad {
 40class ClientInfo;
 41
 42// Abstraction for server side implementation of out-of-process crash
 43// generation protocol for Windows platform only. It generates Windows
 44// minidump files for client processes that request dump generation. When
 45// the server is requested to start listening for clients (by calling the
 46// Start method), it creates a named pipe and waits for the clients to
 47// register. In response, it hands them event handles that the client can
 48// signal to request dump generation. When the clients request dump
 49// generation in this way, the server generates Windows minidump files.
 50class CrashGenerationServer {
 51 public:
 52  typedef void (*OnClientConnectedCallback)(void* context,
 53                                            const ClientInfo* client_info);
 54
 55  typedef void (*OnClientDumpRequestCallback)(void* context,
 56                                              const ClientInfo* client_info,
 57                                              const std::wstring* file_path);
 58
 59  typedef void (*OnClientExitedCallback)(void* context,
 60                                         const ClientInfo* client_info);
 61
 62  typedef void (*OnClientUploadRequestCallback)(void* context,
 63                                                const DWORD crash_id);
 64
 65  // Creates an instance with the given parameters.
 66  //
 67  // Parameter pipe_name: Name of the Windows named pipe
 68  // Parameter pipe_sec_attrs Security attributes to set on the pipe. Pass
 69  //     NULL to use default security on the pipe. By default, the pipe created
 70  //     allows Local System, Administrators and the Creator full control and
 71  //     the Everyone group read access on the pipe.
 72  // Parameter connect_callback: Callback for a new client connection.
 73  // Parameter connect_context: Context for client connection callback.
 74  // Parameter crash_callback: Callback for a client crash dump request.
 75  // Parameter crash_context: Context for client crash dump request callback.
 76  // Parameter exit_callback: Callback for client process exit.
 77  // Parameter exit_context: Context for client exit callback.
 78  // Parameter generate_dumps: Whether to automatically generate dumps.
 79  // Client code of this class might want to generate dumps explicitly in the
 80  // crash dump request callback. In that case, false can be passed for this
 81  // parameter.
 82  // Parameter dump_path: Path for generating dumps; required only if true is
 83  // passed for generateDumps parameter; NULL can be passed otherwise.
 84  CrashGenerationServer(const std::wstring& pipe_name,
 85                        SECURITY_ATTRIBUTES* pipe_sec_attrs,
 86                        OnClientConnectedCallback connect_callback,
 87                        void* connect_context,
 88                        OnClientDumpRequestCallback dump_callback,
 89                        void* dump_context,
 90                        OnClientExitedCallback exit_callback,
 91                        void* exit_context,
 92                        OnClientUploadRequestCallback upload_request_callback,
 93                        void* upload_context,
 94                        bool generate_dumps,
 95                        const std::wstring* dump_path);
 96
 97  ~CrashGenerationServer();
 98
 99  // Performs initialization steps needed to start listening to clients. Upon
100  // successful return clients may connect to this server's pipe.
101  //
102  // Returns true if initialization is successful; false otherwise.
103  bool Start();
104
105 private:
106  // Various states the client can be in during the handshake with
107  // the server.
108  enum IPCServerState {
109    // Server starts in this state.
110    IPC_SERVER_STATE_UNINITIALIZED,
111
112    // Server is in error state and it cannot serve any clients.
113    IPC_SERVER_STATE_ERROR,
114
115    // Server starts in this state.
116    IPC_SERVER_STATE_INITIAL,
117
118    // Server has issued an async connect to the pipe and it is waiting
119    // for the connection to be established.
120    IPC_SERVER_STATE_CONNECTING,
121
122    // Server is connected successfully.
123    IPC_SERVER_STATE_CONNECTED,
124
125    // Server has issued an async read from the pipe and it is waiting for
126    // the read to finish.
127    IPC_SERVER_STATE_READING,
128
129    // Server is done reading from the pipe.
130    IPC_SERVER_STATE_READ_DONE,
131
132    // Server has issued an async write to the pipe and it is waiting for
133    // the write to finish.
134    IPC_SERVER_STATE_WRITING,
135
136    // Server is done writing to the pipe.
137    IPC_SERVER_STATE_WRITE_DONE,
138
139    // Server has issued an async read from the pipe for an ack and it
140    // is waiting for the read to finish.
141    IPC_SERVER_STATE_READING_ACK,
142
143    // Server is done writing to the pipe and it is now ready to disconnect
144    // and reconnect.
145    IPC_SERVER_STATE_DISCONNECTING
146  };
147
148  //
149  // Helper methods to handle various server IPC states.
150  //
151  void HandleErrorState();
152  void HandleInitialState();
153  void HandleConnectingState();
154  void HandleConnectedState();
155  void HandleReadingState();
156  void HandleReadDoneState();
157  void HandleWritingState();
158  void HandleWriteDoneState();
159  void HandleReadingAckState();
160  void HandleDisconnectingState();
161
162  // Prepares reply for a client from the given parameters.
163  bool PrepareReply(const ClientInfo& client_info,
164                    ProtocolMessage* reply) const;
165
166  // Duplicates various handles in the ClientInfo object for the client
167  // process and stores them in the given ProtocolMessage instance. If
168  // creating any handle fails, ProtocolMessage will contain the handles
169  // already created successfully, which should be closed by the caller.
170  bool CreateClientHandles(const ClientInfo& client_info,
171                           ProtocolMessage* reply) const;
172
173  // Response to the given client. Return true if all steps of
174  // responding to the client succeed, false otherwise.
175  bool RespondToClient(ClientInfo* client_info);
176
177  // Handles a connection request from the client.
178  void HandleConnectionRequest();
179
180  // Handles a dump request from the client.
181  void HandleDumpRequest(const ClientInfo& client_info);
182
183  // Callback for pipe connected event.
184  static void CALLBACK OnPipeConnected(void* context, BOOLEAN timer_or_wait);
185
186  // Callback for a dump request.
187  static void CALLBACK OnDumpRequest(void* context, BOOLEAN timer_or_wait);
188
189  // Callback for client process exit event.
190  static void CALLBACK OnClientEnd(void* context, BOOLEAN timer_or_wait);
191
192  // Releases resources for a client.
193  static DWORD WINAPI CleanupClient(void* context);
194
195  // Cleans up for the given client.
196  void DoCleanup(ClientInfo* client_info);
197
198  // Adds the given client to the list of registered clients.
199  bool AddClient(ClientInfo* client_info);
200
201  // Generates dump for the given client.
202  bool GenerateDump(const ClientInfo& client, std::wstring* dump_path);
203
204  // Puts the server in a permanent error state and sets a signal such that
205  // the state will be immediately entered after the current state transition
206  // is complete.
207  void EnterErrorState();
208
209  // Puts the server in the specified state and sets a signal such that the
210  // state is immediately entered after the current state transition is
211  // complete.
212  void EnterStateImmediately(IPCServerState state);
213
214  // Puts the server in the specified state. No signal will be set, so the state
215  // transition will only occur when signaled manually or by completion of an
216  // asynchronous IO operation.
217  void EnterStateWhenSignaled(IPCServerState state);
218
219  // Sync object for thread-safe access to the shared list of clients and
220  // the server's state.
221  CRITICAL_SECTION sync_;
222
223  // List of clients.
224  std::list<ClientInfo*> clients_;
225
226  // Pipe name.
227  std::wstring pipe_name_;
228
229  // Pipe security attributes
230  SECURITY_ATTRIBUTES* pipe_sec_attrs_;
231
232  // Handle to the pipe used for handshake with clients.
233  HANDLE pipe_;
234
235  // Pipe wait handle.
236  HANDLE pipe_wait_handle_;
237
238  // Handle to server-alive mutex.
239  HANDLE server_alive_handle_;
240
241  // Callback for a successful client connection.
242  OnClientConnectedCallback connect_callback_;
243
244  // Context for client connected callback.
245  void* connect_context_;
246
247  // Callback for a client dump request.
248  OnClientDumpRequestCallback dump_callback_;
249
250  // Context for client dump request callback.
251  void* dump_context_;
252
253  // Callback for client process exit.
254  OnClientExitedCallback exit_callback_;
255
256  // Context for client process exit callback.
257  void* exit_context_;
258
259  // Callback for upload request.
260  OnClientUploadRequestCallback upload_request_callback_;
261
262  // Context for upload request callback.
263  void* upload_context_;
264
265  // Whether to generate dumps.
266  bool generate_dumps_;
267
268  // Instance of a mini dump generator.
269  scoped_ptr<MinidumpGenerator> dump_generator_;
270
271  // State of the server in performing the IPC with the client.
272  // Note that since we restrict the pipe to one instance, we
273  // only need to keep one state of the server. Otherwise, server
274  // would have one state per client it is talking to.
275  IPCServerState server_state_;
276
277  // Whether the server is shutting down.
278  bool shutting_down_;
279
280  // Overlapped instance for async I/O on the pipe.
281  OVERLAPPED overlapped_;
282
283  // Message object used in IPC with the client.
284  ProtocolMessage msg_;
285
286  // Client Info for the client that's connecting to the server.
287  ClientInfo* client_info_;
288
289  // Count of clean-up work items that are currently running or are
290  // already queued to run.
291  volatile LONG cleanup_item_count_;
292
293  // Disable copy ctor and operator=.
294  CrashGenerationServer(const CrashGenerationServer& crash_server);
295  CrashGenerationServer& operator=(const CrashGenerationServer& crash_server);
296};
297
298}  // namespace google_breakpad
299
300#endif  // CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__