package nxm.sys.inc;

import nxm.sys.lib.DataFile;
import nxm.sys.lib.FileName;

/**
  Interface for handling Packetized data streams.

  This class defines the methods needed by the I/O libraries to handle
  reading and writing streams with embedded packet headers.

  @author Jeff Schoen
  @version $Id: PacketHandler.java,v 1.14 2014/10/21 18:37:25 ntn Exp $
*/

public interface PacketHandler {

  /** Get the configuration string needed to initialize this handler.
      @param df The data file to get the configuration for.
      @return The configuration string.
   */
  String getConfiguration (DataFile df);

  /** Set the file name for a packets only file.
      @param df The data file to set the name of.
      @param fn The file new name.
   */
  void setFileName (DataFile df, FileName fn);

  /** Translate the data byte offset to byte offset at start of packet.
      @param df      The data file the data-byte-offset is in relation to.
      @param boffset The data-byte-offset.
      @return The (natural) byte-offset into the file.
   */
  double naturalDataOffset (DataFile df, double boffset);

  /** Translate the data byte offset to packetized byte offset.
      @param df      The data file the data-byte-offset is in relation to.
      @param boffset The data-byte-offset.
      @return The packetized-byte-offset.
      @see #packetToDataOffset(DataFile,double)
   */
  double dataToPacketOffset (DataFile df, double boffset);

  /** Translate the packetized byte offset to data byte offset.
      @param df      The data file the data-byte-offset is in relation to.
      @param boffset The packetized-byte-offset.
      @return The data-byte-offset.
      @see #dataToPacketOffset(DataFile,double)
   */
  double packetToDataOffset (DataFile df, double boffset);

  /** Initialize this instance.
      @param df The data file to open.
   */
  void open (DataFile df);

  /** Seek to the closest given data byte offset.
      @param df      The data file to seek to the byte offset in.
      @param boffset The byte offset into the file.
   */
  void seek (DataFile df, double boffset);

  /** Read data including packet header.
      @param df    The data file to read from.
      @param buf   The buffer to read the data in to.
      @param boff  The byte-offset into the buffer to start writing at.
      @param bytes The number of bytes to attempt to read.
      @param lbuf  Native buffer location (0=Disable).
      @return The number of bytes actually read in.
   */
  int read (DataFile df, byte[] buf, int boff, int bytes, long lbuf);

  /** Write data including packet header.

      @param df    The data file to write to.
      @param buf   The buffer to write the data in from.
      @param boff  The byte-offset into the buffer to start writing at.
      @param bytes The number of bytes to attempt to write.
      @param lbuf  Native buffer location (0=Disable).
      @return The number of bytes actually written out.
   */
  int write (DataFile df, byte[] buf, int boff, int bytes, long lbuf);

  /** Finalize this instance.
      @param df The data file to close.
   */
  void close(DataFile df);

  /** Determine if the last read included a new packet header.
      @return <code>true</code> if the last read included a new packet header
              and <code>false</code> if it did not.
   */
  boolean hasHeader();

  /** Lists the current packet header.
      @return The current packet header.
   */
  String listHeader();

  /** Create a clone of this instance for propagation.
      @return A clone of this instance.
   */
  PacketHandler cloneOf();

}
