it.dtt.ca
Class Pin

java.lang.Object
  extended by it.dtt.ca.CAObject
      extended by it.dtt.ca.Pin

public abstract class Pin
extends CAObject

This class represents a Personal Identification Number (PIN). It allows to use and change the PIN codes stored either on the STB or on the smart card.


Field Summary
static java.lang.String HISTORY_PIN
          Indicates the PIN proteting access to history data.
static java.lang.String PARENTAL_CONTROL_PIN
          Indicates the PIN providing parental control.
static java.lang.String SMART_CARD_PIN
          Indicates the PIN protecting the CA System functionalities of the smart card.
 
Constructor Summary
protected Pin(CAObject owner, java.lang.String name)
          Create an instance of a PIN.
 
Method Summary
abstract  void change(byte[] pin)
          Deprecated.  
abstract  void change(byte[] oldPin, byte[] newPin)
          This method sets a new value for the PIN, resets the PIN try counter to the value of the PIN try limit, and resets the validated flag.
abstract  boolean check(byte[] pin)
          Check if the Pin is correct.
 java.lang.String getPinName()
          Get the name that identifies this PIN.
abstract  byte getTriesRemaining()
          Retrieves remaining tries of the pin before smart card is blocked.
abstract  boolean isRequired()
          This method is used to determine if the specific PIN is required.
abstract  boolean isValidated()
          Retrieves if the current pin is validated since the smart card has been reset last time
abstract  void reset()
          Resets the validate flag.
abstract  void setRequired(boolean required)
          Enable or disable the PIN code usage.
 
Methods inherited from class it.dtt.ca.CAObject
checkSession, closeSession, getParent, getSession, sessionClosed, sessionClosing
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SMART_CARD_PIN

public static final java.lang.String SMART_CARD_PIN
Indicates the PIN protecting the CA System functionalities of the smart card.

See Also:
Constant Field Values

HISTORY_PIN

public static final java.lang.String HISTORY_PIN
Indicates the PIN proteting access to history data. This functionality allows the user to read the history of previous purchases, recharges, messages from the CAS, etc.

See Also:
Constant Field Values

PARENTAL_CONTROL_PIN

public static final java.lang.String PARENTAL_CONTROL_PIN
Indicates the PIN providing parental control. This functionality allows the user to block content which is not suitable for children.

See Also:
Constant Field Values
Constructor Detail

Pin

protected Pin(CAObject owner,
              java.lang.String name)
Create an instance of a PIN.

Parameters:
owner - the owner of this PIN, either a SmartCard or a CAManager.
name - the name of this PIN.
Method Detail

getPinName

public java.lang.String getPinName()
Get the name that identifies this PIN.

Returns:
the name of this PIN.

setRequired

public abstract void setRequired(boolean required)
                          throws CardNotFoundException,
                                 SessionClosedException,
                                 AccessDeniedException
Enable or disable the PIN code usage.

Parameters:
required - pin mode, when true the PIN is required.
Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.
AccessDeniedException - if enabling or disabling the PIN code is not allowed.

isRequired

public abstract boolean isRequired()
                            throws CardNotFoundException,
                                   SessionClosedException
This method is used to determine if the specific PIN is required. If this is the case, the PIN must be inserted before performing any operation under control of this PIN.

Returns:
true if the pin is required, false otherwise.
Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.

check

public abstract boolean check(byte[] pin)
                       throws CardNotFoundException,
                              SessionClosedException
Check if the Pin is correct. The Pin must be provided in BCD format. e.g.: A Pin of 1234 will be provided as codebyte[0] = 0x12 and codebyte[1] = 0x34.

Parameters:
pin - the pin entered.
Returns:
true if pin is correct.
Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.

getTriesRemaining

public abstract byte getTriesRemaining()
                                throws CardNotFoundException,
                                       SessionClosedException
Retrieves remaining tries of the pin before smart card is blocked.

Returns:
number of tries remaining.
Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.

isValidated

public abstract boolean isValidated()
                             throws CardNotFoundException,
                                    SessionClosedException
Retrieves if the current pin is validated since the smart card has been reset last time

Returns:
true if pin is validated
Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.

reset

public abstract void reset()
                    throws CardNotFoundException,
                           SessionClosedException
Resets the validate flag. This means that the pin will be required again next time.

Throws:
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.

change

public abstract void change(byte[] oldPin,
                            byte[] newPin)
                     throws InvalidPinException,
                            CardNotFoundException,
                            SessionClosedException,
                            AccessDeniedException
This method sets a new value for the PIN, resets the PIN try counter to the value of the PIN try limit, and resets the validated flag. The Pin must be provided in BCD format. e.g.: A Pin of 1234 will be provided as codebyte[0] = 0x12 and codebyte[1] = 0x34.

Parameters:
oldPin - the byte array containing the old PIN value.
newPin - the byte array containing the new PIN value.
Throws:
InvalidPinException - if the oldPin is not correct, or if newPin length is greater than the maximum PIN size.
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.
AccessDeniedException - if changing the PIN code is not allowed.

change

public abstract void change(byte[] pin)
                     throws InvalidPinException,
                            CardNotFoundException,
                            SessionClosedException,
                            AccessDeniedException
Deprecated. 

This method sets a new value for the PIN, resets the PIN try counter to the value of the PIN try limit, and resets the validated flag. The Pin must be provided in BCD format. e.g.: A Pin of 1234 will be provided as codebyte[0] = 0x12 and codebyte[1] = 0x34.

Parameters:
pin - the byte array containing the new PIN value.
Throws:
InvalidPinException - if the oldPin is not correct, or if newPin length is greater than the maximum PIN size.
CardNotFoundException - if the PIN was stored on a smart card that is not present anymore in the slot.
SessionClosedException - if the session is closed.
AccessDeniedException - if changing the PIN code is not allowed.