//
//  CaptureEventHandling.swift
//  SelfieCam
//
//  Protocol for handling hardware capture events (Camera Control button, Action button, volume buttons).
//

import Foundation

/// Protocol defining hardware capture event handling capabilities
///
/// Conforming types can respond to hardware button events for camera capture,
/// including the Camera Control button on iPhone 16+, Action button on iPhone 15 Pro+,
/// and volume buttons.
///
/// - Note: This protocol is designed to work with `AVCaptureEventInteraction` (iOS 17.2+)
protocol CaptureEventHandling: AnyObject {
    /// Called when a primary capture event occurs (full press on Camera Control, volume button press)
    /// - Parameter phase: The phase of the event (.began, .ended, .cancelled)
    func handlePrimaryCaptureEvent(phase: CaptureEventPhase)
    
    /// Called when a secondary capture event occurs (light press on Camera Control for focus/exposure)
    /// - Parameter phase: The phase of the event (.began, .ended, .cancelled)
    func handleSecondaryCaptureEvent(phase: CaptureEventPhase)
}

/// Represents the phase of a hardware capture event
enum CaptureEventPhase: Sendable {
    /// Event began (button pressed down or light press detected)
    case began
    /// Event ended (button released)
    case ended
    /// Event was cancelled
    case cancelled
}

// MARK: - Default Implementations

extension CaptureEventHandling {
    /// Default implementation for secondary events (focus/exposure lock)
    /// Override in conforming types if focus/exposure lock is needed
    func handleSecondaryCaptureEvent(phase: CaptureEventPhase) {
        // Default: no-op, override if focus/exposure lock support is needed
    }
}
