| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.feedback; |
| |
| using fuchsia.math; |
| using fuchsia.mem; |
| using zx; |
| |
| /// Provides data useful to attach in feedback reports (crash, user feedback or bug reports). |
| [Discoverable] |
| protocol DataProvider { |
| /// Returns all the feedback data except the screenshot, which is provided separately. |
| [Transitional = "deprecated in favor of GetBugreport() "] |
| GetData() -> (Data data) error zx.status; |
| |
| /// Returns a bugreport containing all the feedback data except the screenshot, which is |
| /// provided separately. |
| /// |
| /// `bugreport` may be empty if there was an issue generating the bugreport. |
| [Transitional = "replacement for GetData() "] |
| GetBugreport(GetBugreportParameters params) -> (Bugreport bugreport); |
| |
| /// Returns an image of the current view encoded in the provided `encoding`. |
| /// |
| /// `screenshot` may be null if the encoding is not supported, the device does not have a |
| /// display, or there is not enough memory to allocate the screenshot image. |
| /// |
| /// The screenshot is provided separately from the bugreport as callers might want to block on |
| /// this call before changing the view while collecting a bugreport in the background is fine. |
| /// There are also a lot of clients that are not interested in the screenshot. |
| GetScreenshot(ImageEncoding encoding) -> (Screenshot? screenshot); |
| }; |
| |
| const uint32 MAX_NUM_ANNOTATIONS_PROVIDED = 64; |
| |
| /// Data to attach to feedback reports. |
| /// |
| /// Clients typically upload the data straight to servers without expecting some |
| /// particular fields. So the data comes in the form of arbitrary key-value pairs |
| /// that clients can directly forward to the servers. |
| table Data { |
| /// A vector of key-value string pairs. Keys are guaranteed to be unique. |
| 1: vector<Annotation>:MAX_NUM_ANNOTATIONS_PROVIDED annotations; |
| |
| /// A bundle of Attachments objects stored as an Attachment itself, e.g., it |
| /// could be a ZIP archive bundling a vector of Attachment objects. |
| 3: Attachment attachment_bundle; |
| |
| // Deprecated. |
| 2: reserved; |
| }; |
| |
| /// Parameters for the DataProvider::GetBugreport() method. |
| table GetBugreportParameters { |
| /// A bugreport aggregates various data from the platform (device uptime, logs, Inspect data, |
| /// etc.) that are collected in parallel. Internally, each data collection is done within a |
| /// timeout. |
| /// |
| /// `collection_timeout_per_data` allows clients to control how much time is given to each data |
| /// collection. It enables clients to get a partial yet valid bugreport under a certain time. |
| /// |
| /// Note that this does not control how much total time the bugreport generation may take, |
| /// which is by construction higher than `collection_timeout_per_data`, as clients can control |
| /// the total time by using a timeout on the call to GetBugreport() on their side. |
| 1: zx.duration collection_timeout_per_data; |
| }; |
| |
| /// Represents a bugreport. |
| /// |
| /// Clients typically upload the data straight to servers. So the data comes in the form of |
| /// arbitrary key-value pairs that clients can directly forward to the servers. |
| table Bugreport { |
| /// A <filename, ZIP archive> pair. |
| /// |
| /// The ZIP archive contains several files corresponding to the various data it collected from |
| /// the platform. There is typically one file for all the annotations (device uptime, build |
| /// version, etc.) and one file per attachment (logs, Inspect data, etc.). |
| 1: Attachment bugreport; |
| |
| /// A vector of key-value string pairs. Keys are guaranteed to be unique. |
| /// |
| /// While the annotations are included in the ZIP archive itself, some clients also want them |
| /// separately to index or augment them so we provide them separately as well. |
| 2: vector<Annotation>:MAX_NUM_ANNOTATIONS_PROVIDED annotations; |
| }; |
| |
| /// The encoding used for the image. |
| /// |
| /// Today, only PNG is supported, but in the future the screenshot could be |
| /// returned in other encodings if need arises. |
| enum ImageEncoding { |
| PNG = 0; |
| }; |
| |
| /// An encoded image of the screen. |
| struct Screenshot { |
| fuchsia.mem.Buffer image; |
| |
| // While all encoded images contain their dimensions in their headers, some |
| // clients still expect to receive the width and height separately, so we |
| // also provide it separately so clients don't need to decode `image`. |
| fuchsia.math.Size dimensions_in_px; |
| }; |