/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.dumpstate@1.1;

import @1.0::IDumpstateDevice;

interface IDumpstateDevice extends @1.0::IDumpstateDevice {
    /**
     * Extension of dumpstateBoard which also accepts a mode parameter to limit dumped data.
     *
     * For an example of when this is relevant, consider a bug report being generated with
     * DumpstateMode::CONNECTIVITY - there is no reason to include camera or USB logs in this type
     * of report.
     *
     * The 1.0 version of #dumpstateBoard(handle) should just delegate to this new method and pass
     * DumpstateMode::DEFAULT and a timeout of 30,000ms (30 seconds).
     *
     * This method may still be called by the dumpstate routine even if getVerboseLoggingEnabled
     * returns false. In this case, it may include essential information but must not include
     * information that identifies the user.
     *
     * @param h A native handle with one or two valid file descriptors. The first FD is for text
     *     output, the second (if present) is for binary output.
     * @param mode A mode value to restrict dumped content.
     * @param timeoutMillis An approximate "budget" for how much time this call has been allotted.
     *     If execution runs longer than this, the IDumpstateDevice service may be killed and only
     *     partial information will be included in the report.
     * @return status A DumpstateStatus value indicating the final result.
     */
    dumpstateBoard_1_1(handle h, DumpstateMode mode, uint64_t timeoutMillis)
        generates (DumpstateStatus status);

    /**
     * Turns verbose device vendor logging on or off.
     *
     * The setting should be persistent across reboots. Underlying implementations may need to start
     * vendor logging daemons, set system properties, or change logging masks, for example. Given
     * that many vendor logs contain significant amounts of private information and may come with
     * memory/storage/battery impacts, calling this method on a user build should only be done after
     * user consent has been obtained, e.g. from a toggle in developer settings.
     *
     * Even if verbose logging has been disabled, dumpstateBoard may still be called by the
     * dumpstate routine, and essential information that does not identify the user may be included.
     *
     * @param enable Whether to enable or disable verbose vendor logging.
     */
    setVerboseLoggingEnabled(bool enable);

    /**
     * Queries the current state of verbose device logging. Primarily for UI and informative
     * purposes.
     *
     * Even if verbose logging has been disabled, dumpstateBoard may still be called by the
     * dumpstate routine, and essential information that does not identify the user may be included.
     *
     * @return enabled Whether or not verbose vendor logging is currently enabled.
     */
    getVerboseLoggingEnabled() generates (bool enabled);
};