it.dtt.ca
Class CAManager

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

public abstract class CAManager
extends CAObject

This class provides access to the Conditional Access (CA) functionalities of the STB. It allows to perform five kinds of operations:


Constructor Summary
protected CAManager(org.davic.resources.ResourceClient resourceClient)
          Creates the CAManager object and the associated new CASession.
 
Method Summary
 void addCAListener(CAListener listener)
          Register a listener to the Conditional Access related events.
abstract  java.lang.String getCAProvider()
          Get the name of the CA provider ("Nagra", "Irdeto", etc).
abstract  java.lang.String getCARevision()
          Get the revision of the CA kernel.
abstract  java.lang.String getCAVersion()
          Get the version of the CA kernel.
 org.davic.resources.ResourceClient getClient()
          Get the client that requested this object.
 Product getCurrentEvent()
          Deprecated. replaced by getCurrentProduct Retrieve a Product object describing the event currently on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.) A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted. Note: this method has been replaced by the getCurrentProducts method but is retained here for backward compatability.
 Product[] getCurrentProducts()
          Retrieve Product objects describing the event currently on air(in the default Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.)
 Product[] getCurrentProducts(javax.tv.service.selection.ServiceContext serviceContext)
          Retrieve Product objects describing the event currently on air(in the specified Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.).
 java.lang.String getIrdSerialNumber()
          Retrieves serial number of the set top box.
 Product getNextEvent()
          Deprecated. replaced by getNextProduct Retrieve a Product object describing the event that will be next on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.). A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted. Note: this method has been replaced by the getNextProducts method but is retained here for backward compatability.
 Product[] getNextProducts()
          Retrieve Product objects describing the service that will be next on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.)
 Product[] getNextProducts(javax.tv.service.selection.ServiceContext serviceContext)
          Retrieve Product objects describing the service that will be next on air(in the specified Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.)
 ParentalControlLevel getParentalControlLevel()
          Get the current parental control level.
abstract  Pin[] getPins()
          Get all Personal Identification Numbers that are stored on the STB.
abstract  Slot[] getSlots()
          This method returns an array containing references to the smart card reader slots present in the set top box (normally just one).
 ResponseEvent performRequest(CARequest request, int timeoutms)
          Perform the specified request synchronously and return the response.
 void performRequest(CARequest request, ResponseListener listener)
          Perform the specified request asynchronously and send the response to the given ResponseListener.
 void performRequest(CARequest request, ResponseListener listener, org.dvb.net.rc.ConnectionParameters params, org.dvb.net.rc.ConnectionListener rclistener)
          Perform the specified request asynchronously using a return channel connection and send the response to the given ResponseListener.
 void removeCAListener()
          Deprecated. Removes the last CAListener attached. If no listener is attached an exception is thrown. If listener does not exist, do nothing.
 void removeCAListener(CAListener listener)
          Removes the specified CAListener if attached, otherwise an exception is thrown.
 void setCAListener(CAListener listener)
          Deprecated. use addCAListener Register a listener to the Conditional Access related events. If listener already exists, do nothing.
 void setParentalControlLevel(ParentalControlLevel level, byte[] pin)
          Set the parental control level.
 
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
 

Constructor Detail

CAManager

protected CAManager(org.davic.resources.ResourceClient resourceClient)
Creates the CAManager object and the associated new CASession. The circumstances when the ResourceClient is called should be defined in the CA system specific documentation. This class is not a singleton. A device supporting multiple CA kernels shall support one instance of this class for each supported CA kernel.

Parameters:
resourceClient - the resource client.
Method Detail

getClient

public org.davic.resources.ResourceClient getClient()
Get the client that requested this object. The circumstances when the ResourceClient is called should be defined in the CA system specific documentation.

Returns:
the client object.
See Also:
ResourceProxy.getClient()

getPins

public abstract Pin[] getPins()
                       throws SessionClosedException
Get all Personal Identification Numbers that are stored on the STB.

Returns:
a vector of Pins.
Throws:
SessionClosedException - if the session is closed.

getIrdSerialNumber

public java.lang.String getIrdSerialNumber()
                                    throws SessionClosedException
Retrieves serial number of the set top box.

Returns:
the set top box serial number.
Throws:
SessionClosedException - thrown if the session was closed.

getSlots

public abstract Slot[] getSlots()
                         throws SessionClosedException
This method returns an array containing references to the smart card reader slots present in the set top box (normally just one). This method shall return all smart card slots regardless of which smartcard (if any) they contain.

Returns:
an array with the slots instances
Throws:
SessionClosedException - thrown if the session was closed.
See Also:
Slot

addCAListener

public void addCAListener(CAListener listener)
                   throws SessionClosedException
Register a listener to the Conditional Access related events. If listener already exists, do nothing.

Parameters:
listener - the only listener to CA related events
Throws:
SessionClosedException - thrown if the session was closed.

setCAListener

public void setCAListener(CAListener listener)
                   throws SessionClosedException
Deprecated. use addCAListener Register a listener to the Conditional Access related events. If listener already exists, do nothing.

Parameters:
listener - the only listener to CA related events
Throws:
SessionClosedException - thrown if the session was closed.

removeCAListener

public void removeCAListener(CAListener listener)
                      throws SessionClosedException,
                             NoListenerAttachedException
Removes the specified CAListener if attached, otherwise an exception is thrown. If listener does not exist, do nothing.

Throws:
SessionClosedException - thrown if the session was closed.
NoListenerAttachedException - thrown if no listener is currently attached

removeCAListener

public void removeCAListener()
                      throws SessionClosedException,
                             NoListenerAttachedException
Deprecated. Removes the last CAListener attached. If no listener is attached an exception is thrown. If listener does not exist, do nothing.

Throws:
SessionClosedException - thrown if the session was closed.
NoListenerAttachedException - thrown if no listener is currently attached

getCurrentEvent

public Product getCurrentEvent()
                        throws SessionClosedException
Deprecated. replaced by getCurrentProduct Retrieve a Product object describing the event currently on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.) A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted. Note: this method has been replaced by the getCurrentProducts method but is retained here for backward compatability.

Returns:
a Product object describing the current service
Throws:
SessionClosedException - thrown if the session was closed.

getNextEvent

public Product getNextEvent()
                     throws SessionClosedException
Deprecated. replaced by getNextProduct Retrieve a Product object describing the event that will be next on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.). A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted. Note: this method has been replaced by the getNextProducts method but is retained here for backward compatability.

Returns:
a Product object describing the next service
Throws:
SessionClosedException - thrown if the session was closed.

getCurrentProducts

public Product[] getCurrentProducts()
                             throws SessionClosedException
Retrieve Product objects describing the event currently on air(in the default Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.) A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. The default implementation returns null after verifying the session status. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted. Example, the same Event may be purchased indiviually or in a Package, with different prices associated.

Returns:
Product objects describing the current service
Throws:
SessionClosedException - thrown if the session was closed.

getCurrentProducts

public Product[] getCurrentProducts(javax.tv.service.selection.ServiceContext serviceContext)
                             throws SessionClosedException,
                                    NoSuchServiceContextException
Retrieve Product objects describing the event currently on air(in the specified Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.). A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. The default implementation returns null after verifying the session status. Example, the same Event may be purchased indiviually or in a Package, with different prices associated.

Returns:
Product objects describing the current service
Throws:
SessionClosedException - thrown if the session was closed.
NoSuchServiceContextException - - if the indicated Service Context does not exist or is not available.

getNextProducts

public Product[] getNextProducts()
                          throws SessionClosedException
Retrieve Product objects describing the service that will be next on air, independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.) A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. In a multi-tuner receiver, the target service is the one in which the application itself is broadcasted.

Returns:
Product objects describing the next service
Throws:
SessionClosedException - thrown if the session was closed.

getNextProducts

public Product[] getNextProducts(javax.tv.service.selection.ServiceContext serviceContext)
                          throws SessionClosedException,
                                 NoSuchServiceContextException
Retrieve Product objects describing the service that will be next on air(in the specified Service Context), independently of the way it is offered (Impulse Pay per View, Ordered Pay per View, Pay per Time, etc.) A NULL value is returned if no service is currently selected in this service context or of the currently selected service context is not something which can be bought through the CA system represented by this CAManager. if no service is currently on air, or if the current service is unknown. The default implementation returns null after verifying the session status.

Returns:
Product objects describing the current service
Throws:
SessionClosedException - thrown if the session was closed.
NoSuchServiceContextException - - if the indicated Service Context does not exist or is not available.

performRequest

public ResponseEvent performRequest(CARequest request,
                                    int timeoutms)
                             throws SessionClosedException,
                                    InvalidRequestParametersException,
                                    InvalidTransactionDataException,
                                    CardNotFoundException,
                                    CARequestAlreadyStartedException,
                                    TimeoutExpiredException
Perform the specified request synchronously and return the response. The method blocks until the response is received or the timeout expires (in this case, the TimeoutExpiredException is thrown).

Parameters:
request - the request which should be performed.
timeoutms - the required timeout in milliseconds, after which the TimeoutExpiredException is thrown.
Returns:
the response event.
Throws:
SessionClosedException - thrown if the session was closed.
InvalidTransactionDataException - if some data used for transaction is wrong (ie. any null field for credit card data)
InvalidRequestParametersException - if the request paramters are invalid.
CardNotFoundException - if the correct card is not inserted.
TimeoutExpiredException - if the timeout expires.
CARequestAlreadyStartedException - if the request is already started

performRequest

public void performRequest(CARequest request,
                           ResponseListener listener)
                    throws SessionClosedException,
                           InvalidRequestParametersException,
                           InvalidTransactionDataException,
                           CardNotFoundException,
                           CARequestAlreadyStartedException
Perform the specified request asynchronously and send the response to the given ResponseListener. If the request is of RcRechargeRequest type, also an event of type RechargeEvent should be thrown to any registered RechargeListener.

Parameters:
request - the request which should be performed.
listener - the object waiting for the response to this request.
Throws:
SessionClosedException - thrown if the session was closed.
InvalidRequestParametersException - if the request paramters are invalid.
InvalidTransactionDataException - if some data used for transaction is wrong (ie. any null field for credit card data)
CardNotFoundException - if the correct card is not inserted.
CARequestAlreadyStartedException - if the request is already started

performRequest

public void performRequest(CARequest request,
                           ResponseListener listener,
                           org.dvb.net.rc.ConnectionParameters params,
                           org.dvb.net.rc.ConnectionListener rclistener)
                    throws SessionClosedException,
                           InvalidRequestParametersException,
                           InvalidTransactionDataException,
                           CardNotFoundException,
                           CARequestAlreadyStartedException
Perform the specified request asynchronously using a return channel connection and send the response to the given ResponseListener. The return channel related events are sent to the given ConnectionListener. If the request is of RcRechargeRequest type, also an event of type RechargeEvent should be thrown to any registered RechargeListener.

Parameters:
request - the request which should be performed
listener - the object waiting for the response to this request.
params - the parameters used for the return channel connection
rclistener - the object waiting for the return channel related events
Throws:
SessionClosedException - thrown if the session was closed.
InvalidRequestParametersException - if the request paramters are invalid.
InvalidTransactionDataException - if some data used for transaction is wrong (ie. any null field for credit card data)
CardNotFoundException - if the correct card is not inserted.
CARequestAlreadyStartedException - if the request is already started

getParentalControlLevel

public ParentalControlLevel getParentalControlLevel()
                                             throws SessionClosedException
Get the current parental control level.

Returns:
the parental control level.
Throws:
SessionClosedException - thrown if the session was closed.

setParentalControlLevel

public void setParentalControlLevel(ParentalControlLevel level,
                                    byte[] pin)
                             throws SessionClosedException,
                                    InvalidPinException
Set the parental control level. This allows the user to set which kind of PPV events should require an extra PIN input for viewing. To change the parental control level, a PIN input may be required.

Parameters:
level - the new parental control level.
pin - the parental control pin.
Throws:
SessionClosedException - thrown if the session was closed.
InvalidPinException - thrown if the specified PIN is invalid.

getCAProvider

public abstract java.lang.String getCAProvider()
Get the name of the CA provider ("Nagra", "Irdeto", etc).

Returns:
a string containing the name of the CA provider.

getCAVersion

public abstract java.lang.String getCAVersion()
Get the version of the CA kernel.

Returns:
CA version.

getCARevision

public abstract java.lang.String getCARevision()
Get the revision of the CA kernel.

Returns:
CA revision.