/*
 * Copyright (C) 2019 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.gsi;

import android.gsi.MappedImage;

/** {@hide} */
interface IImageService {
    /* These flags match fiemap::ImageManager::CreateBackingImage. */
    const int CREATE_IMAGE_DEFAULT = 0x0;
    const int CREATE_IMAGE_READONLY = 0x1;
    const int CREATE_IMAGE_ZERO_FILL = 0x2;

    /**
     * Create an image that can be mapped as a block device.
     *
     * This call will fail if running a GSI.
     *
     * @param name          Image name. If the image already exists, the call will fail.
     * @param size          Image size, in bytes. If too large, or not enough space is
     *                      free, the call will fail.
     * @param readonly      If readonly, MapBackingImage() will configure the device as
     *                      readonly.
     * @return              True on success, false otherwise.
     */
    void createBackingImage(@utf8InCpp String name, long size, int flags);

    /**
     * Delete an image created with createBackingImage.
     *
     * @param name          Image name as passed to createBackingImage().
     * @return              True on success, false otherwise.
     */
    void deleteBackingImage(@utf8InCpp String name);

    /**
     * Map an image, created with createBackingImage, such that it is accessible as a
     * block device.
     *
     * @param name          Image name as passed to createBackingImage().
     * @param timeout_ms    Time to wait for a valid mapping, in milliseconds. This must be more
     *                      than zero; 10 seconds is recommended.
     * @param mapping       Information about the newly mapped block device.
     */
    void mapImageDevice(@utf8InCpp String name, int timeout_ms, out MappedImage mapping);

    /**
     * Unmap a block device previously mapped with mapBackingImage. This step is necessary before
     * calling deleteBackingImage.
     *
     * @param name          Image name as passed to createBackingImage().
     */
    void unmapImageDevice(@utf8InCpp String name);

    /**
     * Returns whether or not a backing image exists.
     *
     * @param name          Image name as passed to createBackingImage().
     */
    boolean backingImageExists(@utf8InCpp String name);

    /**
     * Returns whether or not the named image is mapped.
     *
     * @param name          Image name as passed to createBackingImage().
     */
    boolean isImageMapped(@utf8InCpp String name);

    /**
     * Get all installed backing image names
     *
     * @return list of installed backing image names
     */
    @utf8InCpp List<String> getAllBackingImages();

    /**
     * Writes a given amount of zeros in image file.
     *
     * @param name          Image name. If the image does not exist, the call
     *                      will fail.
     * @param bytes         Number of zeros to be written, starting from the
     *                      beginning. If bytes is equal to 0, then the whole
     *                      image file is filled with zeros.
     * @return              True on success, false otherwise.
     */
    void zeroFillNewImage(@utf8InCpp String name, long bytes);

    /**
     * Find and remove all images in the containing folder of this instance.
     */
    void removeAllImages();
}