/*
 * Copyright (c) 2022 Huawei Device Co., Ltd.
 * 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.
 */

/**
 * @addtogroup HdfUserAuth
 * @{
 *
 * @brief Provides APIs for the user auth driver.
 *
 * The user auth driver provides a unified interface for the user auth service to access the user auth driver.
 * After obtaining the user auth driver proxy, the service can call related APIs to register executor, 
 * manage credentials, and complete password and biometric authentication.
 * @since 3.2
 */

/**
 * @file IUserAuthInterface.idl
 *
 * @brief Declare the APIs of userauth driver. These APIs can be used to register executor, 
 * manage credentials, and complete password and biometric authentication.
 *
 * @since 3.2
 */

package ohos.hdi.user_auth.v1_0;

import ohos.hdi.user_auth.v1_0.UserAuthTypes;

/**
 * @brief Declare the APIs of userauth driver.
 *
 * @since 3.2
 * @version 1.0
 */
interface IUserAuthInterface {
    /**
     * @brief Initialize cache information of user auth driver.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    Init();
    /**
     * @brief Add an authentication executor to obtain this authentication capability.
     *
     * @param info Indicates executor registration information, see {@link ExecutorRegisterInfo}.
     * @param index Indicates executor index under the authentication frameworks.
     * @param publicKey Indicates public key of authentication frameworks.
     * @param templateIds Indicates templateIds enrolled by executor.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    AddExecutor([in] struct ExecutorRegisterInfo info, [out] unsigned long index,
        [out] unsigned char[] publicKey, [out] unsigned long[] templateIds);
    /**
     * @brief Delete executor.
     *
     * @param index Indicates executor index under the authentication frameworks.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    DeleteExecutor([in] unsigned long index);
    /**
     * @brief Open authentication credential management session.
     *
     * @param userId Indicates user id.
     * @param challenge Indicates random number, used to generate authentication token.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    OpenSession([in] int userId, [out] unsigned char[] challenge);
    /**
     * @brief Close authentication credential management session.
     *
     * @param userId Indicates user id.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    CloseSession([in] int userId);
    /**
     * @brief Begin the enrollment of authentication credential. 
     * When the authentication type is pin and the current user has enrolled PIN credential,
     * the pin credential will be updated.
     *
     * @param userId Indicates user id.
     * @param authToken Indicates user password authentication token.
     * @param param Indicates input parameters, see {@link EnrollParam}.
     * @param info Indicates scheduling information, see {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginEnrollment([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, 
        [out] struct ScheduleInfo info);
    /**
     * @brief Update the enrollment result and complete this enrollment.
     *
     * @param userId Indicates user id.
     * @param scheduleResult Indicates enrollment result issued by executor.
     * @param info Indicates enrollment result, see {@link EnrollResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info);
    /**
     * @brief Cancel enrollment.
     *
     * @param userId Indicates user id.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    CancelEnrollment([in] int userId);
    /**
     * @brief Delete credential information.
     *
     * @param userId Indicates user id.
     * @param credentialId Indicates credential id.
     * @param authToken Indicates user password authentication token.
     * @param info Indicates deleted credential information, see {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    DeleteCredential([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken, 
        [out] struct CredentialInfo info);
    /**
     * @brief Query credential information.
     *
     * @param userId Indicates user id.
     * @param authType Indicates authentication type, see {@link AuthType}.
     * @param infos Indicates credential information, see {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    GetCredential([in] int userId, [in] enum AuthType authType, [out] struct CredentialInfo[] infos);
    /**
     * @brief Query user information.
     *
     * @param userId Indicates user id.
     * @param secureUid Indicates secure user id.
     * @param pinSubType Indicates pin auth's subtype, see {@link PinSubType}.
     * @param infos Indicates enrolled Info, see {@link EnrolledInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType pinSubType,
        [out] struct EnrolledInfo[] infos);
    /**
     * @brief Delete pin, delete user in Iam subsystem.
     *
     * @param userId Indicates user id.
     * @param authToken Indicates user password authentication token.
     * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos);
    /**
     * @brief Forcibly delete user.
     *
     * @param userId Indicates user id.
     * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos);
    /**
     * @brief Begin authentication, and generate authentication scheme.
     *
     * @param contextId Indicates context id.
     * @param param Indicates input parameters, see {@link AuthSolution}.
     * @param scheduleInfos Indicates scheduling information, see {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginAuthentication([in] unsigned long contextId, [in] struct AuthSolution param,
        [out] struct ScheduleInfo[] scheduleInfos);
    /**
     * @brief Update authentication result, and evaluate the results of this authentication scheme.
     *
     * @param contextId Indicates context id.
     * @param scheduleResult Indicates authentication result issued by executor.
     * @param info Indicates authentication result information, see {@link AuthResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
        [out] struct AuthResultInfo info);
    /**
     * @brief Cancel authentication.
     *
     * @param contextId Indicates context id.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    CancelAuthentication([in] unsigned long contextId);
    /**
     * @brief Begin identification, and generate identification scheme.
     *
     * @param contextId Indicates context id.
     * @param authType Indicates identification type, see @{AuthType}.
     * @param executorSensorHint Indicates executor sensor hint, 0 indicates that no value is specified.
     * @param scheduleInfo Indicates scheduling information, see {@link ScheduleInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge,
        [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo);
    /**
     * @brief Update identification result, and evaluate the results of this identification scheme.
     *
     * @param contextId Indicates context id.
     * @param scheduleResult Indicates identification result issued by executor.
     * @param info Indicates identification result information, see {@link IdentifyResultInfo}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    UpdateIdentificationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
        [out] struct IdentifyResultInfo info);
    /**
     * @brief Cancel identification.
     *
     * @param contextId Indicates context id.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    CancelIdentification([in] unsigned long contextId);
    /**
     * @brief Get the authentication trust level of the current authentication type.
     *
     * @param userId Indicates user id.
     * @param authType Indicates authentication type, see {@link AuthType}.
     * @param authTrustLevel Indicates authentication trust level.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    GetAuthTrustLevel([in] int userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel);
    /**
     * @brief Get the valid authentication methods under the current authentication trust level.
     *
     * @param userId Indicates user id.
     * @param authTypes Indicates authentication type of the to be filtered, see {@link AuthType}.
     * @param authTrustLevel Indicates authentication trust level.
     * @param validTypes Indicates valid authentication type, see {@link AuthType}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a non-zero value if the operation fails.
     */
    GetValidSolution([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel,
        [out] enum AuthType[] validTypes);
}