Crashpad

Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
crashpad::CrashReportDatabase Class Referenceabstract

An interface for managing a collection of crash report files and metadata associated with the crash reports. More...

`#include "client/crash_report_database.h"`

## Classes
class | CallErrorWritingCrashReport
| A scoper to cleanly handle the interface requirement imposed by PrepareNewCrashReport(). More...
struct | NewReport
| A crash report that is in the process of being written. More...
struct | Report
| A crash report record. More...

## Public Types
enum | OperationStatus
| The result code for operations performed on a database. More...

## Public Member Functions
virtual Settings * | GetSettings ()=0
| Returns the Settings object for this database. More...
virtual OperationStatus | PrepareNewCrashReport (NewReport **report)=0
| Creates a record of a new crash report. More...
virtual OperationStatus | FinishedWritingCrashReport (NewReport *report, UUID *uuid)=0
| Informs the database that a crash report has been written. More...
virtual OperationStatus | ErrorWritingCrashReport (NewReport *report)=0
| Informs the database that an error occurred while attempting to write a crash report, and that any resources associated with it should be cleaned up. More...
virtual OperationStatus | LookUpCrashReport (const UUID &uuid, Report *report)=0
| Returns the crash report record for the unique identifier. More...
virtual OperationStatus | GetPendingReports (std::vector< Report > *reports)=0
| Returns a list of crash report records that have not been uploaded. More...
virtual OperationStatus | GetCompletedReports (std::vector< Report > *reports)=0
| Returns a list of crash report records that have been completed, either by being uploaded or by skipping upload. More...
virtual OperationStatus | GetReportForUploading (const UUID &uuid, const Report **report)=0
| Obtains a report object for uploading to a collection server. More...
virtual OperationStatus | RecordUploadAttempt (const Report *report, bool successful, const std::string &id)=0
| Adjusts a crash report record’s metadata to account for an upload attempt, and updates the last upload attempt time as returned by Settings::GetLastUploadAttemptTime(). More...
virtual OperationStatus | SkipReportUpload (const UUID &uuid, Metrics::CrashSkippedReason reason)=0
| Moves a report from the pending state to the completed state, but without the report being uploaded. More...
virtual OperationStatus | DeleteReport (const UUID &uuid)=0
| Deletes a crash report file and its associated metadata. More...
virtual OperationStatus | RequestUpload (const UUID &uuid)=0
| Marks a crash report as explicitly requested to be uploaded by the user and moves it to 'pending' state. More...

## Static Public Member Functions
static std::unique_ptr< CrashReportDatabase > | Initialize (const base::FilePath &path)
| Opens a database of crash reports, possibly creating it. More...
static std::unique_ptr< CrashReportDatabase > | InitializeWithoutCreating (const base::FilePath &path)
| Opens an existing database of crash reports. More...

## Detailed Description

An interface for managing a collection of crash report files and metadata associated with the crash reports.

All Report objects that are returned by this class are logically const. They are snapshots of the database at the time the query was run, and the data returned is liable to change after the query is executed.

The lifecycle of a crash report has three stages:

1. New: A crash report is created with PrepareNewCrashReport(), the the client then writes the report, and then calls FinishedWritingCrashReport() to make the report Pending.
2. Pending: The report has been written but has not been locally processed, or it was has been brought back from 'Completed' state by user request.
3. Completed: The report has been locally processed, either by uploading it to a collection server and calling RecordUploadAttempt(), or by calling SkipReportUpload().

## Member Enumeration Documentation

## ◆ OperationStatus

enum crashpad::CrashReportDatabase::OperationStatus

The result code for operations performed on a database.

Enumerator
kNoError | No error occurred.
kReportNotFound | The report that was requested could not be located.
kFileSystemError | An error occured while performing a file operation on a crash report. A database is responsible for managing both the metadata about a report and the actual crash report itself. This error is returned when an error occurred when managing the report file. Additional information will be logged.
kDatabaseError | An error occured while recording metadata for a crash report or database-wide settings. A database is responsible for managing both the metadata about a report and the actual crash report itself. This error is returned when an error occurred when managing the metadata about a crash report or database-wide settings. Additional information will be logged.
kBusyError | The operation could not be completed because a concurrent operation affecting the report is occurring.
kCannotRequestUpload | The report cannot be uploaded by user request as it has already been uploaded.

## Member Function Documentation

## ◆ DeleteReport()

virtual OperationStatus crashpad::CrashReportDatabase::DeleteReport | ( | const UUID & | uuid | ) |
| pure virtual

Deletes a crash report file and its associated metadata.

Parameters

  [in] | uuid | The UUID of the report to delete.

Returns
  The operation status code.

## ◆ ErrorWritingCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::ErrorWritingCrashReport | ( | NewReport * | report | ) |
| pure virtual

Informs the database that an error occurred while attempting to write a crash report, and that any resources associated with it should be cleaned up.

After calling this method, the database is permitted to remove the file at NewReport::path.

Parameters

  [in] | report | A NewReport obtained with PrepareNewCrashReport(). The NewReport object and file handle within will be invalidated as part of this call.

Returns
  The operation status code.

## ◆ FinishedWritingCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::FinishedWritingCrashReport | ( | NewReport * | report,
|  | UUID * | uuid
| ) |  |
| pure virtual

Informs the database that a crash report has been written.

After calling this method, the database is permitted to move and rename the file at NewReport::path.

Parameters

  [in] | report | A NewReport obtained with PrepareNewCrashReport(). The NewReport object and file handle within will be invalidated as part of this call.
  [out] | uuid | The UUID of this crash report.

Returns
  The operation status code.

## ◆ GetCompletedReports()

virtual OperationStatus crashpad::CrashReportDatabase::GetCompletedReports | ( | std::vector< Report > * | reports | ) |
| pure virtual

Returns a list of crash report records that have been completed, either by being uploaded or by skipping upload.

Parameters

  [out] | reports | A list of crash report record objects. This must be empty on entry. Only valid if this returns kNoError.

Returns
  The operation status code.

## ◆ GetPendingReports()

virtual OperationStatus crashpad::CrashReportDatabase::GetPendingReports | ( | std::vector< Report > * | reports | ) |
| pure virtual

Returns a list of crash report records that have not been uploaded.

Parameters

  [out] | reports | A list of crash report record objects. This must be empty on entry. Only valid if this returns kNoError.

Returns
  The operation status code.

## ◆ GetReportForUploading()

virtual OperationStatus crashpad::CrashReportDatabase::GetReportForUploading | ( | const UUID & | uuid,
|  | const Report ** | report
| ) |  |
| pure virtual

Obtains a report object for uploading to a collection server.

The file at Report::file_path should be uploaded by the caller, and then the returned Report object must be disposed of via a call to RecordUploadAttempt().

A subsequent call to this method with the same uuid is illegal until RecordUploadAttempt() has been called.

Parameters

  [in] | uuid | The unique identifier for the crash report record.
  [out] | report | A crash report record for the report to be uploaded. The caller does not own this object. Only valid if this returns kNoError.

Returns
  The operation status code.

## ◆ GetSettings()

virtual Settings* crashpad::CrashReportDatabase::GetSettings | ( |  | ) |
| pure virtual

Returns the Settings object for this database.

Returns
  A weak pointer to the Settings object, which is owned by the database.

## ◆ Initialize()

std::unique_ptr< CrashReportDatabase > crashpad::CrashReportDatabase::Initialize | ( | const base::FilePath & | path | ) |
| static

Opens a database of crash reports, possibly creating it.

Parameters

  [in] | path | A path to the database to be created or opened. If the database does not yet exist, it will be created if possible. Note that for databases implemented as directory structures, existence refers solely to the outermost directory.

Returns
  A database object on success, `nullptr` on failure with an error logged.

See also
  InitializeWithoutCreating

## ◆ InitializeWithoutCreating()

std::unique_ptr< CrashReportDatabase > crashpad::CrashReportDatabase::InitializeWithoutCreating | ( | const base::FilePath & | path | ) |
| static

Opens an existing database of crash reports.

Parameters

  [in] | path | A path to the database to be opened. If the database does not yet exist, it will not be created. Note that for databases implemented as directory structures, existence refers solely to the outermost directory. On such databases, as long as the outermost directory is present, this method will create the inner structure.

Returns
  A database object on success, `nullptr` on failure with an error logged.

See also
  Initialize

## ◆ LookUpCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::LookUpCrashReport | ( | const UUID & | uuid,
|  | Report * | report
| ) |  |
| pure virtual

Returns the crash report record for the unique identifier.

Parameters

  [in] | uuid | The crash report record unique identifier.
  [out] | report | A crash report record. Only valid if this returns kNoError.

Returns
  The operation status code.

## ◆ PrepareNewCrashReport()

virtual OperationStatus crashpad::CrashReportDatabase::PrepareNewCrashReport | ( | NewReport ** | report | ) |
| pure virtual

Creates a record of a new crash report.

Callers can then write the crash report using the file handle provided. The caller does not own the new crash report record or its file handle, both of which must be explicitly disposed of by calling FinishedWritingCrashReport() or ErrorWritingCrashReport().

To arrange to call ErrorWritingCrashReport() during any early return, use CallErrorWritingCrashReport.

Parameters

  [out] | report | A NewReport object containing a file handle to which the crash report data should be written. Only valid if this returns kNoError. The caller must not delete the NewReport object or close the file handle within.

Returns
  The operation status code.

## ◆ RecordUploadAttempt()

virtual OperationStatus crashpad::CrashReportDatabase::RecordUploadAttempt | ( | const Report * | report,
|  | bool | successful,
|  | const std::string & | id
| ) |  |
| pure virtual

Adjusts a crash report record’s metadata to account for an upload attempt, and updates the last upload attempt time as returned by Settings::GetLastUploadAttemptTime().

After calling this method, the database is permitted to move and rename the file at Report::file_path.

Parameters

  [in] | report | The report object obtained from GetReportForUploading(). This object is invalidated after this call.
  [in] | successful | Whether the upload attempt was successful.
  [in] | id | The identifier assigned to this crash report by the collection server. Must be empty if successful is `false`; may be empty if it is `true`.

Returns
  The operation status code.

## ◆ RequestUpload()

virtual OperationStatus crashpad::CrashReportDatabase::RequestUpload | ( | const UUID & | uuid | ) |
| pure virtual

Marks a crash report as explicitly requested to be uploaded by the user and moves it to 'pending' state.

Parameters

  [in] | uuid | The unique identifier for the crash report record.

Returns
  The operation status code.

## ◆ SkipReportUpload()

virtual OperationStatus crashpad::CrashReportDatabase::SkipReportUpload | ( | const UUID & | uuid,
|  | Metrics::CrashSkippedReason | reason
| ) |  |
| pure virtual

Moves a report from the pending state to the completed state, but without the report being uploaded.

This can be used if the user has disabled crash report collection, but crash generation is still enabled in the product.

Parameters

  [in] | uuid | The unique identifier for the crash report record.
  [in] | reason | The reason the report upload is being skipped for metrics tracking purposes.

Returns
  The operation status code.

The documentation for this class was generated from the following files:

- client/crash_report_database.h
- client/crash_report_database_mac.mm
- client/crash_report_database_win.cc