//
// LDASTools frameCPP - A library implementing the LIGO/Virgo frame
// specification
//
// Copyright (C) 2025 California Institute of Technology
//
// LDASTools frameCPP is free software; you may redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 (GPLv2) of the
// License or at your discretion, any later version.
//
// LDASTools frameCPP is distributed in the hope that it will be useful, but
// without any warranty or even the implied warranty of merchantability
// or fitness for a particular purpose. See the GNU General Public
// License (GPLv2) for more details.
//
// Neither the names of the California Institute of Technology (Caltech),
// The Massachusetts Institute of Technology (M.I.T), The Laser
// Interferometer Gravitational-Wave Observatory (LIGO), nor the names
// of its contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
// You should have received a copy of the licensing terms for this
// software included in the file LICENSE located in the top-level
// directory of this package. If you did not, you can view a copy at
// http://dcc.ligo.org/M1500244/LICENSE
//

#ifndef FrameCPP__OOInterface__FrameStreamPlan_HH
#define FrameCPP__OOInterface__FrameStreamPlan_HH

#include "framecpp/Common/FrameStreamPlanWrapper.hh"

// Public API types
#include "framecpp/FrAdcData.hh"
#include "framecpp/FrameH.hh"
#include "framecpp/FrProcData.hh"
#include "framecpp/FrSerData.hh"
#include "framecpp/FrSimData.hh"
#include "framecpp/FrRawData.hh"
#include "framecpp/FrEvent.hh"
#include "framecpp/FrSimEvent.hh"

namespace FrameCPP
{
    //-----------------------------------------------------------------------
    /// \brief Unified version-agnostic frame stream plan reader
    ///
    /// This is the recommended interface for reading frame files with TOC
    /// sharing optimization. It automatically detects the frame file version
    /// and handles all versions (v3-v9) transparently.
    ///
    /// Since the Universal namespace migration, all frame objects are
    /// version-agnostic and file version is auto-detected from the stream.
    /// Therefore, a single unified IFrameStreamPlan class can handle all
    /// frame file versions without requiring version-specific instantiations.
    ///
    /// \par TOC Sharing
    /// The primary benefit of IFrameStreamPlan is TOC (Table of Contents)
    /// sharing across multiple readers of identical frame files:
    /// \code
    /// IFrameStreamPlan reader1(buffer1);           // Parses TOC
    /// IFrameStreamPlan reader2(buffer2, &reader1); // Shares TOC (faster)
    /// IFrameStreamPlan reader3(buffer3, &reader2); // Also shares TOC
    /// \endcode
    ///
    /// \par Version Detection
    /// The frame file version is automatically detected when opening the
    /// stream. Reading operations work identically regardless of file version.
    /// Version-specific behavior (e.g., deprecated fields) is handled
    /// transparently by the Universal frame objects.
    ///
    /// \par Writing
    /// When writing frames, the default version (FRAME_SPEC_CURRENT) is used.
    /// This can be overridden using the IFrameStream version parameter if
    /// needed for backward compatibility.
    ///
    /// \see IFrameStreamPlanWrapper
    /// \see Universal::FrTOC
    //-----------------------------------------------------------------------
    typedef Common::IFrameStreamPlanWrapper< FRAME_SPEC_CURRENT,
                                             FrAdcData,
                                             FrameH,
                                             FrProcData,
                                             FrSerData,
                                             FrSimData,
                                             FrRawData,
                                             FrEvent,
                                             FrSimEvent >
        IFrameStreamPlan;

} // namespace FrameCPP

#endif /* FrameCPP__OOInterface__FrameStreamPlan_HH */
