/*
 * Copyright (c) 2025 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 HdiScsiDdk
 * @{
 *
 * @brief Provides SCSI DDK APIs to open and close SCSI interfaces.
 * @since 5.1
 * @version 1.0
 */

/* *
 * @file IScsiPeripheralDdk.idl
 *
 * @brief Declares the SCSI DDK APIs used by the SCSI host to access SCSI devices.
 *
 * @since 5.1
 * @version 1.0
 */

package ohos.hdi.usb.scsi_ddk.v1_0;

import ohos.hdi.usb.scsi_ddk.v1_0.ScsiPeripheralDdkTypes;

/* *
 * @brief Declares the SCSI DDK APIs used by the SCSI host to access SCSI devices.
 */
interface IScsiPeripheralDdk
{
    /* *
     * @brief Initializes the DDK.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Init();

    /* *
     * @brief Releases the DDK.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Release();

    /* *
     * @brief Open SCSI device by deviceId.
     *
     * @param deviceId ID of the device to be operated.
     * @param interfaceIndex Interface index, which corresponds to interface which supports USB Protocol UAS.
     * @param dev Device handle.
     * @param fd The file descriptor obtained for memory mapping.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Open([in] unsigned long deviceId, [in] unsigned char interfaceIndex, [out] struct ScsiPeripheralDevice dev, [out] FileDescriptor fd);

    /* *
     * @brief Close SCSI device.
     *
     * @param dev Device handle.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Close([in] struct ScsiPeripheralDevice dev);

    /* *
     * @brief Get the device capacity.
     *
     * @param dev Device handle.
     * @param request ReadCapacity request information.
     * @param capacityInfo The data of read capacity command.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    ReadCapacity10([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralReadCapacityRequest request, [out] struct ScsiPeripheralCapacityInfo capacityInfo, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Check if the logical unit is ready.
     *
     * @param dev Device handle.
     * @param request Test unit ready request information.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    TestUnitReady([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralTestUnitReadyRequest request, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Get the information regarding the logical unit and SCSI target device.
     *
     * @param dev Device handle.
     * @param request Inquiry request information.
     * @param inquiryInfo The data of inquiry command.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Inquiry([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralInquiryRequest request, [out] struct ScsiPeripheralInquiryInfo inquiryInfo, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Get the sense data.
     *
     * @param dev Device handle.
     * @param request RequestSense request information.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    RequestSense([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralRequestSenseRequest request, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Read from the specified logical block(s).
     *
     * @param dev Device handle.
     * @param request The request parameters.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Read10([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralIORequest request, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Write data to the specified logical block(s).
     *
     * @param dev Device handle.
     * @param request The request parameters.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Write10([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralIORequest request, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Verify the specified logical block(s) on the medium.
     *
     * @param dev Device handle.
     * @param request The request parameters.
     * @param request Verify request information.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    Verify10([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralVerifyRequest request, [out] struct ScsiPeripheralResponse response);

    /* *
     * @brief Send SCSI command that specified by CDB.
     *
     * @param dev Device handle.
     * @param request The request parameters.
     * @param response The response parameters.
     *
     * @return <b>0</b> if the operation is successful; a negative value otherwise.
     * @since 5.1
     * @version 1.0
     */
    SendRequestByCDB([in] struct ScsiPeripheralDevice dev, [in] struct ScsiPeripheralRequest request, [out] struct ScsiPeripheralResponse response);
}