1    :  // Copyright 2014 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  
  15    :  #ifndef SYZYGY_KASKO_API_REPORTER_H_
  16    :  #define SYZYGY_KASKO_API_REPORTER_H_
  17    :  
  18    :  #include "base/process/process_handle.h"
  19    :  #include "base/strings/string16.h"
  20    :  #include "base/threading/platform_thread.h"
  21    :  #include "syzygy/kasko/api/kasko_export.h"
  22    :  #include "syzygy/kasko/api/minidump_type.h"
  23    :  
  24  m :  namespace kasko {
  25  m :  namespace api {
  26    :  
  27    :  // The extension given to crash keys files in the permanent failure directory.
  28  m :  KASKO_EXPORT extern const base::char16* const
  29  m :      kPermanentFailureCrashKeysExtension;
  30    :  // The extension given to minidump files in the permanent failure directory.
  31  m :  KASKO_EXPORT extern const base::char16* const
  32  m :      kPermanentFailureMinidumpExtension;
  33    :  
  34    :  // Receives notification when a report has been uploaded.
  35    :  // @param context User-supplied context from InitializeReporter.
  36    :  // @param report_id The server-assigned report ID.
  37    :  // @param minidump_path The local path to the report file. This path is no
  38    :  //     longer valid after the OnUploadProc returns.
  39    :  // @param keys A null-terminated array of crash key names.
  40    :  // @param values A null-terminated array of crash key values of equal length to
  41    :  //     |keys|.
  42  m :  typedef void(OnUploadProc)(void* context,
  43  m :                             const base::char16* report_id,
  44  m :                             const base::char16* minidump_path,
  45  m :                             const base::char16* const* keys,
  46  m :                             const base::char16* const* values);
  47    :  
  48    :  // Initializes the Kasko reporter process, including the reporter RPC service
  49    :  // and background report uploading. Must be matched by a call to
  50    :  // ShutdownReporter.
  51    :  //
  52    :  // Reports that exceed upload retry limits will be moved to the configured
  53    :  // permanent failure directory. The reports consist of two files: a minidump
  54    :  // file (extension kPermanentFailureMinidumpExtension, which is '.dmp') and a
  55    :  // crash keys file (extension kPermanentFailureCrashKeysExtension, which is
  56    :  // '.kys'). The two file names will be identical apart from the extension. The
  57    :  // crash keys file will contain a JSON dictionary mapping crash key names to
  58    :  // string values.
  59    :  //
  60    :  // @param endpoint_name The endpoint name that will be used by the Kasko RPC
  61    :  //     service.
  62    :  // @param url The URL that will be used for uploading crash reports.
  63    :  // @param data_directory The directory where crash reports will be queued until
  64    :  //     uploaded.
  65    :  // @param permanent_failure_directory The location where reports will be stored
  66    :  //     once the maximum number of upload attempts has been exceeded.
  67    :  // @param on_upload_proc An optional procedure to be notified when an upload
  68    :  //     completes successfully.
  69    :  // @param on_upload_context A context parameter passed to |on_upload_proc|.
  70    :  // @returns true if successful.
  71  m :  KASKO_EXPORT bool InitializeReporter(
  72  m :      const base::char16* endpoint_name,
  73  m :      const base::char16* url,
  74  m :      const base::char16* data_directory,
  75  m :      const base::char16* permanent_failure_directory,
  76  m :      OnUploadProc* on_upload_proc,
  77  m :      void* on_upload_context);
  78    :  
  79    :  // Sends a diagnostic report for a specified process with the specified crash
  80    :  // keys. May only be invoked after a successful call to InitializeReporter.
  81    :  // @param process_handle A handle to the process to report on. It must be
  82    :  //     possible to reopen the process.
  83    :  // @param thread_id The crashing thread to report on. Ignored if
  84    :  //     exception_info_address is null.
  85    :  // @param exception_info_address Optional exception information.
  86    :  // @param minidump_type The type of minidump to be included in the report.
  87    :  // @param keys An optional null-terminated array of crash key names
  88    :  // @param values An optional null-terminated array of crash key values. Must be
  89    :  //     of equal length to |keys|.
  90  m :  KASKO_EXPORT void SendReportForProcess(
  91  m :      base::ProcessHandle process_handle,
  92  m :      base::PlatformThreadId thread_id,
  93  m :      const EXCEPTION_POINTERS* exception_pointers,
  94  m :      MinidumpType minidump_type,
  95  m :      const base::char16* const* keys,
  96  m :      const base::char16* const* values);
  97    :  
  98    :  // Shuts down the Kasko reporter process. Must only be called after a successful
  99    :  // invocation of InitializeReporter.
 100  m :  KASKO_EXPORT void ShutdownReporter();
 101    :  
 102  m :  }  // namespace api
 103  m :  }  // namespace kasko
 104    :  
 105    :  #endif  // SYZYGY_KASKO_API_REPORTER_H_