package nxm.sys.lib;

/** A file with frame-based data.

    @since   NeXtMidas 2.5.4
    @author  J. Czechowski IV
 */
interface FrameFile {
  /** Get the file name of the file.
      @return The file name as a URL.
   */
  String getURL (); // move?

  /** Get the file name for the file, with any qualifiers and trimmers.
      @return The file name, or null if not set yet.
   */
  FileName getName (); // move?

  /** Get the size of the file.
      @return The file size. Size will be in elements for DataFiles or Bytes for other files (e.g. images)
   */
  double getSize (); // move?

  /** Open a data connection with specified flags. If the file name is blank and the
      {@link nxm.sys.lib.BaseFile#OPTIONAL} flag is specified.
      @param flags The flags to use (see {@link nxm.sys.lib.BaseFile} for a list of available "I/O
                   open flags."
      @return true if the file is now open, false if unable to open the file (with
              {@link nxm.sys.lib.BaseFile#NOABORT} or  {@link nxm.sys.lib.BaseFile#OPTIONAL}).
      @throws RuntimeException If unable to open the file and NOT using
              {@link nxm.sys.lib.BaseFile#NOABORT} or  {@link nxm.sys.lib.BaseFile#OPTIONAL}.
   */
  boolean open (int flags); // move?

  /** Tells if the file is open.
      @return true if the file is open, false otherwise.
   */
  boolean isOpen (); // move?

  /** Close a data connection. This method should do nothing in cases where the file is not open
      (this permits a primitive to call <code>close()</code> on *any* file without checking to see if
      it is open).
   */
  void close (); // move?

  /** Get the data format for the data.
      @return The Midas identifier for the data's format (e.g. "SF", or "VD").
      @see DataTypes
   */
  String getFormat();

  /** Returns a data object of the given size appropriate for receiving the data. This method is
      preferred over simply creating a new {@link Data} object since it takes into account the
      element size and format.
      @param size The number of elements in the data buffer.
      @return An applicable data buffer.
   */
  Data getDataBuffer (int size);

  /** Read specified elements of data at the current address.
      @param data     The data buffer into which the elements read will be placed.
      @param elements The number of elements to attempt to read.
      @return The number of elements actually read or -N if at the end of the file. This will be
              a number less than <code>elements</code> if fewer elements are available to be read in.
   */
  int read (Data data, int elements);

  /** Move next read/write pointer to specified element offset.
      @param offset The offset to move to (in number of elements).
      @return Unspecified <i>(The meaning of this value was never properly specified, anyone
              implementing this interface should just return zero.)</i>
   */
  int seek (double offset);

  /** Get the location of the read/write pointer.
      @return Seek position in number of elements.
   */
  double seek ();

  /** Gets the number of elements currently available for read/write.
      @return Number of elements available.
   */
  double avail ();
}
