/*
 * Copyright 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 androidx.camera.video;

import static androidx.camera.video.VideoRecordEvent.Finalize.ERROR_NONE;
import static androidx.camera.video.VideoRecordEvent.Finalize.VideoRecordError;

import androidx.annotation.IntDef;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RestrictTo;
import androidx.core.util.Consumer;
import androidx.core.util.Preconditions;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.concurrent.Executor;

/**
 * VideoRecordEvent is used to report video recording events and status.
 *
 * <p>Upon starting a recording by {@link PendingRecording#start(Executor, Consumer)}, recording
 * events will start to be sent to the listener passed to
 * {@link PendingRecording#start(Executor, Consumer)}.
 *
 * <p>There are {@link Start}, {@link Finalize}, {@link Status}, {@link Pause} and {@link Resume}
 * events.
 *
 * <p>Example: Below is the typical way to determine the event type and cast to the event class, if
 * needed.
 *
 * <pre>{@code
 *
 * Recording recording = recorder.prepareRecording(context, outputOptions)
 *     .start(ContextCompat.getMainExecutor(context), videoRecordEvent -> {
 *         if (videoRecordEvent instanceof VideoRecordEvent.Start) {
 *             // Handle the start of a new active recording
 *             ...
 *         } else if (videoRecordEvent instanceof VideoRecordEvent.Pause) {
 *             // Handle the case where the active recording is paused
 *             ...
 *         } else if (videoRecordEvent instanceof VideoRecordEvent.Resume) {
 *             // Handles the case where the active recording is resumed
 *             ...
 *         } else if (videoRecordEvent instanceof VideoRecordEvent.Finalize) {
 *             VideoRecordEvent.Finalize finalizeEvent =
 *                 (VideoRecordEvent.Finalize) videoRecordEvent;
 *             // Handles a finalize event for the active recording, checking Finalize.getError()
 *             int error = finalizeEvent.getError();
 *             if (error != Finalize.ERROR_NONE) {
 *                 ...
 *             }
 *         }
 *
 *         // All events, including VideoRecordEvent.Status, contain RecordingStats.
 *         // This can be used to update the UI or track the recording duration.
 *         RecordingStats recordingStats = videoRecordEvent.getRecordingStats();
 *         ...
 *     });
 *
 * }</pre>
 *
 * <p>If using Kotlin, the VideoRecordEvent class can be treated similar to a {@code sealed
 * class}. In Kotlin, it is recommended to use a {@code when} expression rather than an {@code
 * if}-{@code else if} chain as in the above example.
 *
 * <p>When a video recording is requested, {@link Start} event will be reported at first and
 * {@link Finalize} event will be reported when the recording is finished. The stop reason can be
 * obtained via {@link Finalize#getError()}. {@link Finalize#ERROR_NONE} means that the video was
 * recorded successfully, and other error code indicate the recording is failed or stopped due to
 * a certain reason. Please note that a failed result does not mean that the video file has not been
 * generated. In some cases, the file can still be successfully generated. For example, the
 * result {@link Finalize#ERROR_FILE_SIZE_LIMIT_REACHED} will still have video file.
 *
 * <p>The {@link Status} event will be triggered continuously during the recording process,
 * {@link #getRecordingStats} can be used to get the recording state such as total recorded bytes
 * and total duration when the event is triggered.
 */
public abstract class VideoRecordEvent {

    private final OutputOptions mOutputOptions;
    private final RecordingStats mRecordingStats;

    // Restrict access to emulate sealed class
    // Classes will be constructed with static factory methods
    VideoRecordEvent(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats) {
        mOutputOptions = Preconditions.checkNotNull(outputOptions);
        mRecordingStats = Preconditions.checkNotNull(recordingStats);
    }

    /**
     * Gets the recording statistics of current event.
     */
    @NonNull
    public RecordingStats getRecordingStats() {
        return mRecordingStats;
    }

    /**
     * Gets the {@link OutputOptions} associated with this event.
     */
    @NonNull
    public OutputOptions getOutputOptions() {
        return mOutputOptions;
    }

    @NonNull
    static Start start(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats) {
        return new Start(outputOptions, recordingStats);
    }

    /**
     * Indicates the start of recording.
     *
     * <p>When a video recording is successfully requested by
     * {@link PendingRecording#start(Executor, Consumer)}, a {@code Start} event will be the
     * first event.
     */
    public static final class Start extends VideoRecordEvent {

        @SuppressWarnings("WeakerAccess") /* synthetic accessor */
        Start(@NonNull OutputOptions outputOptions, @NonNull RecordingStats recordingStats) {
            super(outputOptions, recordingStats);
        }
    }

    @NonNull
    static Finalize finalize(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats,
            @NonNull OutputResults outputResults) {
        return new Finalize(outputOptions, recordingStats, outputResults, ERROR_NONE, null);
    }

    @NonNull
    static Finalize finalizeWithError(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats,
            @NonNull OutputResults outputResults,
            @VideoRecordError int error,
            @Nullable Throwable cause) {
        Preconditions.checkArgument(error != ERROR_NONE, "An error type is required.");
        return new Finalize(outputOptions, recordingStats, outputResults, error, cause);
    }

    /**
     * Indicates the finalization of recording.
     *
     * <p>The finalize event will be triggered regardless of whether the recording succeeds or
     * fails. Use {@link Finalize#getError()} to obtain the error type and
     * {@link Finalize#getCause()} to get the error cause. If there is no error,
     * {@link #ERROR_NONE} will be returned. Other error types indicate the recording is failed or
     * stopped due to a certain reason. Please note that receiving a finalize event with error
     * does not necessarily mean that the video file has not been generated. In some cases, the
     * file can still be successfully generated depending on the error type. For example, a file
     * will still be generated when the recording is finalized with
     * {@link #ERROR_FILE_SIZE_LIMIT_REACHED}. A file may or may not be generated when the
     * recording is finalized with {@link #ERROR_INSUFFICIENT_STORAGE}. Example to detect if an
     * output file is generated:
     * <pre>{@code
     * if (videoRecordEvent instanceof VideoRecordEvent.Finalize) {
     *     VideoRecordEvent.Finalize finalizeEvent =
     *             (VideoRecordEvent.Finalize) videoRecordEvent;
     *     OutputOptions options = finalizeEvent.getOutputOptions();
     *     switch (finalizeEvent.getError()) {
     *     case ERROR_INSUFFICIENT_STORAGE:
     *         if (options instanceof FileOutputOptions) {
     *             if (((FileOutputOptions) options).getFile().exists()) {
     *                 // file exists
     *             }
     *         } else if (options instanceof MediaStoreOutputOptions) {
     *             Uri uri = finalizeEvent.getOutputResults().getOutputUri();
     *             if (uri != Uri.EMPTY) {
     *                 // file exists
     *             }
     *         } else if (options instanceof FileDescriptorOutputOptions) {
     *             // User has to check the referenced target of the file descriptor.
     *         }
     *         break;
     *     }
     * }
     * }</pre>
     *
     * <p>For certain types of errors, the output file will not be constructed correctly, and it
     * will be the user's responsibility to deal with the incomplete file, such as deleting it.
     * Example to delete the file:
     *
     * <pre>{@code
     * if (videoRecordEvent instanceof VideoRecordEvent.Finalize) {
     *     VideoRecordEvent.Finalize finalizeEvent =
     *             (VideoRecordEvent.Finalize) videoRecordEvent;
     *     OutputOptions options = finalizeEvent.getOutputOptions();
     *     switch (finalizeEvent.getError()) {
     *     case ERROR_UNKNOWN:
     *     case ERROR_RECORDER_ERROR:
     *     case ERROR_ENCODING_FAILED:
     *     case ERROR_NO_VALID_DATA:
     *         if (options instanceof FileOutputOptions) {
     *             ((FileOutputOptions) options).getFile().delete();
     *         } else if (options instanceof MediaStoreOutputOptions) {
     *             Uri uri = finalizeEvent.getOutputResults().getOutputUri();
     *             if (uri != Uri.EMPTY) {
     *                 context.getContentResolver().delete(uri, null, null);
     *             }
     *         } else if (options instanceof FileDescriptorOutputOptions) {
     *             // User has to clean up the referenced target of the file descriptor.
     *         }
     *         break;
     *     }
     * }
     * }</pre>
     *
     * <p>If there's no error that prevents the file to be generated, the file can be accessed
     * safely after receiving the finalize event.
     */
    public static final class Finalize extends VideoRecordEvent {
        /**
         * The recording succeeded with no error.
         */
        public static final int ERROR_NONE = 0;

        /**
         * An unknown error occurred.
         *
         * <p>The output file may or moy not be generated. Since the error is not determined,
         * application should clean up the output file, such as deleting it.
         */
        public static final int ERROR_UNKNOWN = 1;

        /**
         * The recording failed due to file size limitation.
         *
         * <p>The file size limit refers to {@link OutputOptions#getFileSizeLimit()}. The
         * recording will be finalized automatically with this error when the limit is reached and
         * the data produced before the limit is reached will be saved to the output file.
         */
        // TODO(b/167481981): add more descriptions about the restrictions after getting into more
        //  details.
        public static final int ERROR_FILE_SIZE_LIMIT_REACHED = 2;

        /**
         * The recording failed due to insufficient storage space.
         *
         * <p>There are two possible cases that will cause this error.
         * <ul>
         *     <li>The storage is already full before the recording starts, so no output file
         *     will be generated.</li>
         *     <li>The storage becomes full during recording, so the output file will be
         *     generated. </li>
         * </ul>
         */
        // TODO(b/167484136): add more descriptions about the restrictions after getting into more
        //  details.
        public static final int ERROR_INSUFFICIENT_STORAGE = 3;

        /**
         * The recording failed because the source becomes inactive and stops sending frames.
         *
         * <p>One case is that if camera is closed due to lifecycle stopped, the active recording
         * will be finalized with this error, and the output will be generated, containing the
         * frames produced before camera closing. Attempting to start a new recording will be
         * finalized immediately if the source remains inactive and no output will be generated.
         */
        public static final int ERROR_SOURCE_INACTIVE = 4;

        /**
         * The recording failed due to invalid output options.
         *
         * <p>This error is generated when invalid output options have been used while preparing a
         * recording, such as with the
         * {@link Recorder#prepareRecording(android.content.Context, MediaStoreOutputOptions)}
         * method. The error will depend on the subclass of {@link OutputOptions} used.
         *
         * <p>No output file will be generated with this error.
         */
        public static final int ERROR_INVALID_OUTPUT_OPTIONS = 5;

        /**
         * The recording failed while encoding.
         *
         * <p>This error may be generated when the video or audio codec encounters an error during
         * encoding. When this happens and the output file is generated, the output file is not
         * properly constructed. The application will need to clean up the output file, such as
         * deleting the file.
         */
        public static final int ERROR_ENCODING_FAILED = 6;

        /**
         * The recording failed because the {@link Recorder} is in an unrecoverable error state.
         *
         * <p>When this happens and the output file is generated, the output file is not properly
         * constructed. The application will need to clean up the output file, such as deleting
         * the file. Such an error will usually require creating a new {@link Recorder} object to
         * start a new recording.
         */
        public static final int ERROR_RECORDER_ERROR = 7;

        /**
         * The recording failed because no valid data was produced to be recorded.
         *
         * <p>This error is generated when the essential data for a recording to be played correctly
         * is missing, for example, a recording must contain at least one key frame. The
         * application will need to clean up the output file, such as deleting the file.
         */
        public static final int ERROR_NO_VALID_DATA = 8;

        /**
         * The recording failed due to duration limitation.
         *
         * <p>The duration limit refers to {@link OutputOptions#getDurationLimitMillis()}. The
         * recording will be finalized automatically with this error when the limit is reached and
         * the data produced before the limit is reached will be saved to the output file.
         */
        public static final int ERROR_DURATION_LIMIT_REACHED = 9;

        /**
         * The recording was stopped because the {@link Recording} object was garbage collected.
         *
         * <p>The {@link Recording} object returned by
         * {@link PendingRecording#start(Executor, Consumer)} must be referenced until the
         * recording is no longer needed. If it is not, the active recording will be stopped and
         * this error will be produced. Once {@link Recording#stop()} or
         * {@link Recording#close()} has been invoked, the recording object no longer needs to be
         * referenced.
         */
        public static final int ERROR_RECORDING_GARBAGE_COLLECTED = 10;

        /**
         * Describes the error that occurred during a video recording.
         *
         * <p>This is the error code returning from {@link Finalize#getError()}.
         *
         */
        @RestrictTo(RestrictTo.Scope.LIBRARY)
        @Retention(RetentionPolicy.SOURCE)
        @IntDef(value = {ERROR_NONE, ERROR_UNKNOWN, ERROR_FILE_SIZE_LIMIT_REACHED,
                ERROR_INSUFFICIENT_STORAGE, ERROR_INVALID_OUTPUT_OPTIONS, ERROR_ENCODING_FAILED,
                ERROR_RECORDER_ERROR, ERROR_NO_VALID_DATA, ERROR_SOURCE_INACTIVE,
                ERROR_DURATION_LIMIT_REACHED, ERROR_RECORDING_GARBAGE_COLLECTED})
        public @interface VideoRecordError {
        }

        private final OutputResults mOutputResults;
        @VideoRecordError
        private final int mError;
        private final Throwable mCause;

        @SuppressWarnings("WeakerAccess") /* synthetic accessor */
        Finalize(@NonNull OutputOptions outputOptions,
                @NonNull RecordingStats recordingStats,
                @NonNull OutputResults outputResults,
                @VideoRecordError int error,
                @Nullable Throwable cause) {
            super(outputOptions, recordingStats);
            mOutputResults = outputResults;
            mError = error;
            mCause = cause;
        }

        /**
         * Gets the {@link OutputResults}.
         */
        @NonNull
        public OutputResults getOutputResults() {
            return mOutputResults;
        }

        /**
         * Indicates whether an error occurred.
         *
         * <p>Returns {@code true} if {@link #getError()} returns {@link #ERROR_NONE}, otherwise
         * {@code false}.
         */
        public boolean hasError() {
            return mError != ERROR_NONE;
        }

        /**
         * Gets the error type for a video recording.
         *
         * <p>Possible values are {@link #ERROR_NONE}, {@link #ERROR_UNKNOWN},
         * {@link #ERROR_FILE_SIZE_LIMIT_REACHED}, {@link #ERROR_INSUFFICIENT_STORAGE},
         * {@link #ERROR_INVALID_OUTPUT_OPTIONS}, {@link #ERROR_ENCODING_FAILED},
         * {@link #ERROR_RECORDER_ERROR}, {@link #ERROR_NO_VALID_DATA} and
         * {@link #ERROR_SOURCE_INACTIVE}.
         */
        @VideoRecordError
        public int getError() {
            return mError;
        }

        /**
         * Gets the error cause.
         *
         * <p>Returns the error cause if any, otherwise returns {@code null}.
         * <p>Note that not all error types include an error cause. For some error types, the
         * file may still be generated successfully with no error cause. For example,
         * {@link #ERROR_FILE_SIZE_LIMIT_REACHED}, {@link #ERROR_DURATION_LIMIT_REACHED} and
         * {@link #ERROR_SOURCE_INACTIVE}.
         */
        @Nullable
        public Throwable getCause() {
            return mCause;
        }

        @NonNull
        static String errorToString(@VideoRecordError int error) {
            switch (error) {
                case ERROR_NONE: return "ERROR_NONE";
                case ERROR_UNKNOWN: return "ERROR_UNKNOWN";
                case ERROR_FILE_SIZE_LIMIT_REACHED: return "ERROR_FILE_SIZE_LIMIT_REACHED";
                case ERROR_INSUFFICIENT_STORAGE: return "ERROR_INSUFFICIENT_STORAGE";
                case ERROR_INVALID_OUTPUT_OPTIONS: return "ERROR_INVALID_OUTPUT_OPTIONS";
                case ERROR_ENCODING_FAILED: return "ERROR_ENCODING_FAILED";
                case ERROR_RECORDER_ERROR: return "ERROR_RECORDER_ERROR";
                case ERROR_NO_VALID_DATA: return "ERROR_NO_VALID_DATA";
                case ERROR_SOURCE_INACTIVE: return "ERROR_SOURCE_INACTIVE";
                case ERROR_DURATION_LIMIT_REACHED: return "ERROR_DURATION_LIMIT_REACHED";
                case ERROR_RECORDING_GARBAGE_COLLECTED: return "ERROR_RECORDING_GARBAGE_COLLECTED";
            }

            // Should never reach here, but just in case...
            return "Unknown(" + error + ")";
        }
    }

    @NonNull
    static Status status(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats) {
        return new Status(outputOptions, recordingStats);
    }

    /**
     * The status report of the recording in progress.
     */
    public static final class Status extends VideoRecordEvent {

        @SuppressWarnings("WeakerAccess") /* synthetic accessor */
        Status(@NonNull OutputOptions outputOptions, @NonNull RecordingStats recordingStats) {
            super(outputOptions, recordingStats);
        }
    }

    @NonNull
    static Pause pause(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats) {
        return new Pause(outputOptions, recordingStats);
    }

    /**
     * Indicates the pause event of recording.
     *
     * <p>A {@code Pause} event will be triggered after calling {@link Recording#pause()}.
     */
    public static final class Pause extends VideoRecordEvent {

        @SuppressWarnings("WeakerAccess") /* synthetic accessor */
        Pause(@NonNull OutputOptions outputOptions, @NonNull RecordingStats recordingStats) {
            super(outputOptions, recordingStats);
        }
    }

    @NonNull
    static Resume resume(@NonNull OutputOptions outputOptions,
            @NonNull RecordingStats recordingStats) {
        return new Resume(outputOptions, recordingStats);
    }

    /**
     * Indicates the resume event of recording.
     *
     * <p>A {@code Resume} event will be triggered after calling {@link Recording#resume()}.
     */
    public static final class Resume extends VideoRecordEvent {

        @SuppressWarnings("WeakerAccess") /* synthetic accessor */
        Resume(@NonNull OutputOptions outputOptions, @NonNull RecordingStats recordingStats) {
            super(outputOptions, recordingStats);
        }
    }
}