/*---------------------------------------------------------------------------
 * Copyright (C) 1999,2000 Dallas Semiconductor Corporation, All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * Except as contained in this notice, the name of Dallas Semiconductor
 * shall not be used except as stated in the Dallas Semiconductor
 * Branding Policy.
 *---------------------------------------------------------------------------
 */

package com.dalsemi.onewire.container;

// imports
import com.dalsemi.onewire.OneWireException;
import com.dalsemi.onewire.adapter.OneWireIOException;


/**
 * 1-Wire clock interface class for basic real-time-clock operations.
 * This class should be implemented for each clock type
 * 1-Wire device.
 *
 * @version    0.00, 28 Aug 2000
 * @author     DS
 */
public interface ClockContainer
   extends OneWireSensor
{

   //--------
   //-------- Clock Feature methods
   //--------

   /**
    * Query to see if the clock has an alarm feature.
    *
    * @return boolean, true if real-time-clock has an alarm
    */
   public boolean hasClockAlarm ();

   /**
    * Query to see if the clock can be disabled.  See
    * the methods 'isClockRunning()' and 'setClockRunEnable()'.
    *
    * @return boolean, true if the clock can be enabled and
    * disabled.
    */
   public boolean canDisableClock ();

   /**
    * Query to get the clock resolution in milliseconds
    *
    * @return long, get the clock resolution in milliseconds.
    */
   public long getClockResolution ();

   //--------
   //-------- Clock 'get' Methods
   //--------

   /**
    * This method extracts the Clock Value in milliseconds from the
    * state data retrieved from the 'readDevice()' method.
    *
    * @param state - byte array of device state
    *
    * @return <code>long<\code> time - in milliseconds that have
    * occured since 1970.
    */
   public long getClock (byte[] state);

   /**
    * This method extracts the Clock Alarm Value from the provided
    * state data retrieved from the 'readDevice()'
    * method.
    *
    * @param state - byte array of device state
    *
    * @return <code>long<\code> time - in milliseconds that have
    * the clock alarm is set to.
    */
   public long getClockAlarm (byte[] state)
      throws OneWireException;

   /**
    * This method checks if the Clock Alarm flag has been set
    * from the state data retrieved from the
    * 'readDevice()' method.
    *
    * @param state - byte array of device state
    *
    * @return <code>boolean<\code> true if clock is alarming
    */
   public boolean isClockAlarming (byte[] state);

   /**
    * This method checks if the Clock Alarm is enabled
    * from the provided state data retrieved from the
    * 'readDevice()' method.
    *
    * @param state - byte array of device state
    *
    * @return <code>boolean<\code> true if clock alarm is enabled
    */
   public boolean isClockAlarmEnabled (byte[] state);

   /**
    * This method checks if the device's oscilator is enabled.  The clock
    * will not increment if the clock is not enabled.
    * This value is read from the provided state data retrieved from the
    * 'readDevice()' method.
    *
    * @param state - byte array of device state
    *
    * @return <code>boolean<\code> true
    */
   public boolean isClockRunning (byte[] state);

   //--------
   //-------- Clock 'set' Methods
   //--------

   /**
    * This method sets the Clock time in the provided state data
    * Use the method 'writeDevice()' with
    * this data to finalize the change to the device.
    *
    * @param time - <code>long<\code> milliseconds the user
    * wants the Clock set to.
    * @param state - byte array of device state
    */
   public void setClock (long time, byte[] state);

   /**
    * This method sets the Clock Alarm in the provided state
    * data.  Use the method 'writeDevice()' with
    * this data to finalize the change to the device.
    *
    * @param time - <code>long<\code> milliseconds the user
    * wants the Clock alarm set to.
    * @param state - byte array of device state
    */
   public void setClockAlarm (long time, byte[] state)
      throws OneWireException;

   /**
    * This method sets the oscillator enable to the specified
    * value. Use the method 'writeDevice()' with this
    * data to finalize the change to the device.
    *
    * @param runEnable - boolean, true if want the clock oscillator to
    *                 be enabled.
    * @param state - byte array of device state
    */
   public void setClockRunEnable (boolean runEnable, byte[] state)
      throws OneWireException;

   /**
    * This method sets the Clock Alarm enable. Use the method
    * 'writeDevice()' with this data to finalize the
    * change to the device.
    *
    * @param  alarmEnable - boolean, true to enable the clock alarm
    * @param state - byte array of device state
    */
   public void setClockAlarmEnable (boolean alarmEnable, byte[] state)
      throws OneWireException;
}