/* Copyright  (c) 2002 Graz University of Technology. All rights reserved.
 *
 * Redistribution and use in  source and binary forms, with or without 
 * modification, are permitted  provided that the following conditions are met:
 *
 * 1. Redistributions of  source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in  binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *  
 * 3. The end-user documentation included with the redistribution, if any, must
 *    include the following acknowledgment:
 * 
 *    "This product includes software developed by IAIK of Graz University of
 *     Technology."
 * 
 *    Alternately, this acknowledgment may appear in the software itself, if 
 *    and wherever such third-party acknowledgments normally appear.
 *  
 * 4. The names "Graz University of Technology" and "IAIK of Graz University of
 *    Technology" must not be used to endorse or promote products derived from 
 *    this software without prior written permission.
 *  
 * 5. Products derived from this software may not be called 
 *    "IAIK PKCS Wrapper", nor may "IAIK" appear in their name, without prior 
 *    written permission of Graz University of Technology.
 *  
 *  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
 *  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE LICENSOR BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 *  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 *  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 *  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 *  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY  OF SUCH DAMAGE.
 */

package iaik.pkcs.pkcs11;

import iaik.pkcs.pkcs11.wrapper.CK_SLOT_INFO;
import iaik.pkcs.pkcs11.wrapper.Constants;
import iaik.pkcs.pkcs11.wrapper.PKCS11Constants;



/**
 * Objects of this call provide information about a slot. A slot can be a
 * smart card reader, for instancce. Notice that this object is immutable; i.e.
 * it gets its state at object creation and does not alter afterwards. Thus,
 * all information this object provides, is a snapshot at the object creation.
 * This is especially important when calling isTokenPresent().
 *
 * @author <a href="mailto:Karl.Scheibelhofer@iaik.at"> Karl Scheibelhofer </a>
 * @version 1.0
 * @invariants (slotDescription_ <> null)
 *             and (manufacturerID_ <> null)
 *             and (hardwareVersion_ <> null)
 *             and (firmwareVersion_ <> null)
 */
public class SlotInfo {

  /**
   * A short descrption of this slot.
   */
  protected String slotDescription_;

  /**
   * A string identifying the manufacturer of this slot.
   */
  protected String manufacturerID_;

  /**
   * The version of the slot's hardware.
   */
  protected Version hardwareVersion_;

  /**
   * The version of the slot's firmware.
   */
  protected Version firmwareVersion_;

  /**
   * Indicates, if a token is present.
   */
  protected boolean tokenPresent_;

  /**
   * Indicates, if the token's in this slot are removable or not.
   */
  protected boolean removableDevice_;

  /**
   * Indicate, if this slot is a hardware device or if it is just pure
   * software; i.e. no hardware involved, e.g. a softtoken.
   */
  protected boolean hwSlot_;

  /**
   * Constructor that takes the CK_SLOT_INFO object as given by
   * PKCS11.C_GetSlotInfo().
   *
   * @param ckSlotInfo The CK_SLOT_INFO object as given by
   *                   PKCS11.C_GetSlotInfo().
   * @preconditions (ckSlotInfo <> null)
   * @postconditions
   */
  protected SlotInfo(CK_SLOT_INFO ckSlotInfo) {
    if (ckSlotInfo == null) {
      throw new NullPointerException("Argument \"ckSlotInfo\" must not be null.");
    }
    slotDescription_ = new String(ckSlotInfo.slotDescription);
    manufacturerID_ = new String(ckSlotInfo.manufacturerID);
    hardwareVersion_ = new Version(ckSlotInfo.hardwareVersion);
    firmwareVersion_ = new Version(ckSlotInfo.firmwareVersion);
    tokenPresent_ = (ckSlotInfo.flags & PKCS11Constants.CKF_TOKEN_PRESENT) != 0L;
    removableDevice_ = (ckSlotInfo.flags & PKCS11Constants.CKF_REMOVABLE_DEVICE) != 0L;
    hwSlot_ = (ckSlotInfo.flags & PKCS11Constants.CKF_HW_SLOT) != 0L;
  }

  /**
   * Get a short description of this slot.
   *
   * @return A string describing this slot.
   * @preconditions
   * @postconditions (result <> null)
   */
  public String getSlotDescription() {
    return slotDescription_ ;
  }

  /**
   * Get an identifier for the manufacturer of this slot.
   *
   * @return A string identifying the manufacturer of this slot.
   * @preconditions
   * @postconditions (result <> null)
   */
  public String getManufacturerID() {
    return manufacturerID_ ;
  }

  /**
   * Get the verion of the slot's hardware.
   *
   * @return The version of the hardware of this slot.
   * @preconditions
   * @postconditions (result <> null)
   */
  public Version getHardwareVersion() {
    return hardwareVersion_ ;
  }

  /**
   * Get the version of the slot's firmware.
   *
   * @return The version of the firmware of this slot.
   * @preconditions
   * @postconditions (result <> null)
   */
  public Version getFirmwareVersion() {
    return firmwareVersion_ ;
  }

  /**
   * Indicates, if there is a token present in this slot. Notice, that this
   * refers to the time this object was created and not when this method is
   * invoked.
   *
   * @return True, if there is a (compatible) token in the slot. False,
   *         otherwise.
   * @preconditions
   * @postconditions
   */
  public boolean isTokenPresent() {
    return tokenPresent_ ;
  }

  /**
   * Indicate, if the token is removalbe from this slot or not. In some
   * cases slot and token will be one device.
   *
   * @return True, if the tokens are removable. False, otherwise.
   * @preconditions
   * @postconditions
   */
  public boolean isRemovableDevice() {
    return removableDevice_ ;
  }

  /**
   * Indicate, if the token is a hardware device or if it is just a pure
   * software implementation; e.g. in case of a pure softwaretoken.
   *
   * @return True, if it is a hardware slot. False, otherwise.
   * @preconditions
   * @postconditions
   */
  public boolean isHwSlot() {
    return hwSlot_ ;
  }

  /**
   * Returns the string representation of this object.
   *
   * @return the string representation of object
   */
  public String toString() {
    StringBuffer buffer = new StringBuffer();

    buffer.append("Slot Description: ");
    buffer.append(slotDescription_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Manufacturer ID: ");
    buffer.append(manufacturerID_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Hardware Version: ");
    buffer.append(hardwareVersion_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Firmware Version: ");
    buffer.append(firmwareVersion_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Token present: ");
    buffer.append(tokenPresent_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Removable Device: ");
    buffer.append(removableDevice_);
    buffer.append(Constants.NEWLINE);

    buffer.append("Hardware Slot: ");
    buffer.append(hwSlot_);

    return buffer.toString() ;
  }

  /**
   * Compares all member variables of this object with the other object.
   * Returns only true, if all are equal in both objects.
   *
   * @param otherObject The other SlotInfo object.
   * @return True, if other is an instance of Info and all member variables of
   *         both objects are equal. False, otherwise.
   * @preconditions
   * @postconditions
   */
  public boolean equals(java.lang.Object otherObject) {
    boolean equal = false;

    if (otherObject instanceof SlotInfo) {
      SlotInfo other = (SlotInfo) otherObject;
      equal = (this == other)
              || (this.slotDescription_.equals(other.slotDescription_)
                  && this.manufacturerID_.equals(other.manufacturerID_)
                  && this.hardwareVersion_.equals(other.hardwareVersion_)
                  && this.firmwareVersion_.equals(other.firmwareVersion_)
                  && (this.tokenPresent_ == other.tokenPresent_)
                  && (this.removableDevice_ == other.removableDevice_)
                  && (this.hwSlot_ == other.hwSlot_));
    }

    return equal ;
  }

  /**
   * The overriding of this method should ensure that the objects of this class
   * work correctly in a hashtable.
   *
   * @return The hash code of this object. Gained from the slotDescription_,
   *         manufacturerID_, hardwareVersion_ and firmwareVersion_.
   * @preconditions
   * @postconditions
   */
  public int hashCode() {
    return slotDescription_.hashCode()
           ^ manufacturerID_.hashCode()
           ^ hardwareVersion_.hashCode()
           ^ firmwareVersion_.hashCode() ;
  }

}
