/*
 * Copyright (C) 2017 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.confirmationui@1.0;

import android.hardware.keymaster@4.0::HardwareAuthToken;
import IConfirmationResultCallback;

interface IConfirmationUI {
    /**
     * Asynchronously initiates a confirmation UI dialog prompting the user to confirm a given text.
     * The TUI prompt must be implemented in such a way that a positive response indicates with
     * high confidence that a user has seen the given prompt text even if the Android framework
     * including the kernel was compromised.
     *
     * @param resultCB Implementation of IResultCallback. Used by the implementation to report
     *                 the result of the current pending user prompt.
     *
     * @param promptText UTF-8 encoded string which is to be presented to the user.
     *
     * @param extraData A binary blob that must be included in the formatted output message as is.
     *                  It is opaque to the implementation. Implementations must neither interpret
     *                  nor modify the content.
     *
     * @param locale String specifying the locale that must be used by the TUI dialog. The string
     *                      is an IETF BCP 47 tag.
     *
     * @param uiOptions A set of uiOptions manipulating how the confirmation prompt is displayed.
     *                  Refer to UIOption in types.hal for possible options.
     *
     * @return error  - OK: IFF the dialog was successfully started. In this case, and only in this
     *                      case, the implementation must, eventually, call the callback to
     *                      indicate completion.
     *                - OperationPending: Is returned when the confirmation provider is currently
     *                      in use.
     *                - SystemError: An error occurred trying to communicate with the confirmation
     *                      provider (e.g. trusted app).
     *                - UIError: The confirmation provider encountered an issue with displaying
     *                      the prompt text to the user.
     */
    promptUserConfirmation(IConfirmationResultCallback resultCB, string promptText,
                           vec<uint8_t> extraData, string locale, vec<UIOption> uiOptions)
        generates(ResponseCode error);

    /**
     * DeliverSecureInput is used by the framework to deliver a secure input event to the
     * confirmation provider.
     *
     * VTS test mode:
     * This function can be used to test certain code paths non-interactively. See TestModeCommands
     * in types.hal for details.
     *
     * @param secureInputToken An authentication token as generated by Android authentication
     *                         providers.
     *
     * @return error - Ignored: Unless used for testing (See TestModeCommands).
     */
    deliverSecureInputEvent(HardwareAuthToken secureInputToken)
        generates(ResponseCode error);

    /**
     * Aborts a pending user prompt. This allows the framework to gracefully end a TUI dialog.
     * If a TUI operation was pending the corresponding call back is informed with
     * ErrorCode::Aborted.
     */
    abort();
};