org.davic.net.ca
Class CAModule

java.lang.Object
  extended byorg.davic.net.ca.CAModule

public abstract class CAModule
extends java.lang.Object

CAModule class represents a physical CA Module


Field Summary
static int CA0
          Constant value for the CA0 (Common Interface) CA module type.
static int CA1
          Constant value for the CA1 (DAVIC specified smart card) CA module type.
static int ENTITLEMENT_AVAILABLE
          Constant value for a return value of queryEntitlement().
static int ENTITLEMENT_NOT_AVAILABLE
          Constant value for a return value of queryEntitlement().
static int ENTITLEMENT_UNKNOWN
          Constant value for a return value of queryEntitlement().
static int MMI_DIALOGUE_REQUIRED
          Constant value for a return value of queryEntitlement().
static int PROPRIETARY
          Constant value for the proprietary CA module types.
 
Method Summary
 int buyEntitlement(Locator locator)
          Request to buy a specified service or future event (specified by a Locator) from a conditional access system.
 void closeMessageSession(int session_id)
          This method allows an application to close a session to this module.
 void closeMMI()
          Requests the module to leave the complete tree of the current high-level MMI dialogs.
 void enterApplication()
          Requests the module to enter start the application and enter the main application menu.
 java.lang.String getApplicationTitle()
          Retrieves the Application Title String.
 int[] getCASystemIDs()
          Returns all CASystemIDs of this CA module.
 int getModuleType()
          Returns the type of this module.
 int getSlotNumber()
          Returns the number of the slot where module is connected.
 boolean isConnectable(TransportStream ts)
          Returns true if the given transport stream can be connected to this module
 boolean isDescramblable(ElementaryStream[] streams)
          Returns true if the given array of elementary services (which are components of the same service) can be descrambled by this CAModule.
 boolean isDescramblable(Service s)
          Returns true if given service can be descrambled by this CAModule now.
 java.lang.String[] listEntitlements()
          Returns the entitlements present in this module for display to the end-user.
 int openMessageSession(MessageListener listener)
          This method allows an application to open a message session to this module.
 int queryEntitlement(Locator locator)
          Returns if descrambling is possible for specified service or future event (specified by a Locator).
 void sendToModule(int session_id, CAMessage msg)
          Sends a message to this module.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CA0

public static final int CA0
Constant value for the CA0 (Common Interface) CA module type. Values from 0x02 to 0xFE are reserved for future use.

See Also:
getModuleType(), Constant Field Values

CA1

public static final int CA1
Constant value for the CA1 (DAVIC specified smart card) CA module type. Values from 0x02 to 0xFE are reserved for future use.

See Also:
getModuleType(), Constant Field Values

PROPRIETARY

public static final int PROPRIETARY
Constant value for the proprietary CA module types. Values from 0x02 to 0xFE are reserved for future use.

See Also:
getModuleType(), Constant Field Values

ENTITLEMENT_UNKNOWN

public static final int ENTITLEMENT_UNKNOWN
Constant value for a return value of queryEntitlement(). ENTITLEMENT_UNKNOWN shall be returned if all necessary information for returning a more specific answer is not available (e.g. because the STU is not tuned to the relevant transport stream). In the DVB common interface protocol, this constant is mapped to the following CA_enable values of the ca_pmt_response message and event_status values of the event_reply message.

See Also:
queryEntitlement(org.davic.net.Locator), Constant Field Values

ENTITLEMENT_AVAILABLE

public static final int ENTITLEMENT_AVAILABLE
Constant value for a return value of queryEntitlement(). ENTITLEMENT_AVAILABLE is returned when the entitlement is definitely available and all information needed to verify this is available. In the DVB common interface protocol, this constant is mapped to the following CA_enable values of the ca_pmt_response message and event_status values of the event_reply message.

See Also:
queryEntitlement(org.davic.net.Locator), Constant Field Values

ENTITLEMENT_NOT_AVAILABLE

public static final int ENTITLEMENT_NOT_AVAILABLE
Constant value for a return value of queryEntitlement(). ENTITLEMENT_NOT_AVAILABLE is returned when the entitlement is definitely not available and all information needed to verify this is available. In the DVB common interface protocol, this constant is mapped to the following CA_enable values of the ca_pmt_response message and event_status values of the event_reply message.

See Also:
queryEntitlement(org.davic.net.Locator), Constant Field Values

MMI_DIALOGUE_REQUIRED

public static final int MMI_DIALOGUE_REQUIRED
Constant value for a return value of queryEntitlement(). MMI_DIALOGUE_REQUIRED is returned when the entitlement may become available after an MMI dialogue (e.g. a purchase dialogue or a maturity rating verfication dialogue). In the DVB common interface protocol, this constant is mapped to the following CA_enable values of the ca_pmt_response message and event_status values of the event_reply message.

See Also:
queryEntitlement(org.davic.net.Locator), Constant Field Values
Method Detail

queryEntitlement

public int queryEntitlement(Locator locator)
                     throws CAException,
                            InvalidLocatorException
Returns if descrambling is possible for specified service or future event (specified by a Locator).

Return values are specified by constants in this class. In case of DVB Common Interface, this maps onto CI messages as follows:

Parameters:
locator - a Locator that points to a broadcast service or an event of a service
Returns:
descrambling status code
Throws:
NoFreeCapacityException - raised if the CAModule does not have available capacity to perform this action now
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
java.lang.SecurityException - raised if the application does not have an instance of CAPermission with the "entitlementInfo" name.
InvalidLocatorException - if the locator does not point to a valid service or event.
CAException

buyEntitlement

public int buyEntitlement(Locator locator)
                   throws CAException
Request to buy a specified service or future event (specified by a Locator) from a conditional access system.

Returns whether descrambling of the specified service or future event is possible after the user dialogue has been completed. Return values are specified by constants in this class. If a dialog is required to buy an entitlement, this dialog may be started.

In case of DVB Common Interface, this maps onto CI messages as follows:

Parameters:
locator - Locator that points to a broadcast service or an event of a service
Returns:
descrambling status code (similar as in queryEntitlement)
Throws:
NoFreeCapacityException - raised if the CAModule does not have available capacity to perform this action now
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
NotTunedException - raised if performing the action would require being tuned to the transport stream carrying the service and the receiver is not currently tuned to it
java.lang.SecurityException - raised if the application does not have an instance of CAPermission with the "buy" name.
CAException

listEntitlements

public java.lang.String[] listEntitlements()
                                    throws CAException
Returns the entitlements present in this module for display to the end-user. The strings returned are CA system dependent. The CA system and implementation of this API together should format these such that they can be presented to end users.

Returns:
array of entitlement strings
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
java.lang.SecurityException - raised if the application does not have an instance of CAPermission with the "entitlementInfo" name.
CAException

isConnectable

public boolean isConnectable(TransportStream ts)
                      throws CAException
Returns true if the given transport stream can be connected to this module

Returns:
true, if the transport stream can be connected to this CA module, false otherwise
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
NotTunedException - raised if performing the action would require being tuned to the transport stream carrying the service and the receiver is not currently tuned to it
CAException

getSlotNumber

public int getSlotNumber()
                  throws CAException
Returns the number of the slot where module is connected. The numbering of slots is dependent on the API implementation, but should be such that if the number is presented to the end user, he can identify which physical slot it is.

Returns:
slot number
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
CAException

isDescramblable

public boolean isDescramblable(Service s)
                        throws CAException
Returns true if given service can be descrambled by this CAModule now. The difference between this function and the queryEntitlement is that this function returns whether this CA module can descramble this service now, i.e. if it has both the entitlement as well as resources to perform it. In case of CA0 this maps onto ca_pmt with ca_pmt_cmd_id = query (Common Interface specification, section 8.4.3.4).

Returns:
true, if descrambling of the service could be performed now, false otherwise
Throws:
NotTunedException - raised if performing the action would require being tuned to the transport stream carrying the service and the receiver is not currently tuned to it
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
CAException

isDescramblable

public boolean isDescramblable(ElementaryStream[] streams)
                        throws CAException
Returns true if the given array of elementary services (which are components of the same service) can be descrambled by this CAModule. The difference between this function and the queryEntitlement is that this function returns whether this CA module can descramble this service now, i.e. if it has both the entitlement as well as resources to perform it. In case of CA0 this maps onto ca_pmt with ca_pmt_cmd_id = query (Common interface specification, section 8.4.3.4).

Returns:
true, if descrambling of these elementary streams could be performed now or if an empty array was passed in, false otherwise
Throws:
NotTunedException - raised if performing the action would require being tuned to the transport stream carrying the service and the receiver is not currently tuned to it
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
CAException

getCASystemIDs

public int[] getCASystemIDs()
                     throws CAException
Returns all CASystemIDs of this CA module.

Returns:
array of CA system identifiers
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
CAException

getModuleType

public int getModuleType()
                  throws CAException
Returns the type of this module. Constants for the possible return values are defined in this class

Returns:
module type
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
CAException

openMessageSession

public int openMessageSession(MessageListener listener)
                       throws CAException
This method allows an application to open a message session to this module. The return value of this method is the session_id that is a unique identification of the session within the module. In a DVB CI/DAVIC CA0 system, this method can only be used to address private resources and not public ones as defined in .

In systems based on the DVB common interface, messages sessions opened using this method shall be mapped onto the CA pipeline for the module represented by this CAModule instance as defined in section 6.8 of the common interface extensions specification. Neither the module_id or the resource_id of the module are visible to the application. It is the responsibility of the platform to perform the relevant mapping. NOTE:The document referred to as "common interface extensions specification."is TS 101 699.

Parameters:
listener - the listener which will receive the messages related to this message session
Returns:
the session identifier
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
ModuleBusyException - raised if the module is busy and is not able to handle a message session at the moment. This is CA system dependant.
ModuleResourceNonExistentException - raised if the specified resource is not present in the module.
ModuleResourceVersionTooLowException - raised if the version of the module resource is too low. NOTE: The ModuleResourceVersionTooLowException shall never be thrown in this version of the present document.
java.lang.SecurityException - raised if the application does not have an instance of CAPermission with the "messagePassing" name.
CAException

closeMessageSession

public void closeMessageSession(int session_id)
                         throws CAException
This method allows an application to close a session to this module. After this method has returned, no new messages will be accepted in this session. Messages that have already been submitted will however be answered. After the last 'ModuleResponseEvent' a 'SessionClosedEvent' will follow.

Parameters:
session_id - the session identifier returned by the openMessageSession method.
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
UnknownSessionException - raised if the specified session does not exist
CAException

sendToModule

public void sendToModule(int session_id,
                         CAMessage msg)
                  throws CAException
Sends a message to this module. The sending of the message is asynchronous. In systems based on the DVB common interface, messages sent using this method shall be mapped onto the CAPipelineRequest as defined in section 6.8.3 of the common interface extensions specification. Responses from the CA system reported through the CAPipelineResponse and CAPipelineNotification messages shall be mapped onto instances of ModuleResponseEvent.

Parameters:
session_id - the session identifier returned by the openMessageSession method
msg - the message to be sent to the module
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more
UnknownSessionException - raised if the specified session does not exist
BufferFullException - raised if the message buffer is full
CAException

getApplicationTitle

public java.lang.String getApplicationTitle()
                                     throws ModuleUnavailableException
Retrieves the Application Title String. This functionality is provided at low lowel (within MMI and Application Information sessions defined in EN50221) by the message application_info() message (Application Information resource, see 8. 4.2.2)

Returns:
the application title string
Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more

enterApplication

public void enterApplication()
                      throws ModuleUnavailableException
Requests the module to enter start the application and enter the main application menu. This functionality is provided at low lowel (within MMI and Application Information sessions defined in EN50221) by the message enter_menu() message (Application Information resource, see 8.4.2.3)

Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more

closeMMI

public void closeMMI()
              throws ModuleUnavailableException
Requests the module to leave the complete tree of the current high-level MMI dialogs. This functionality is provided at low lowel (within MMI and Application Information sessions defined in EN50221) by the message close_mmi() message (MMI resource, see 8.6.2.1)

Throws:
ModuleUnavailableException - raised if the physical CA module has been removed and is not available any more