org.ocap.system.SystemModuleHandler Maven / Gradle / Ivy
package org.ocap.system;
/**
* The SystemModuleHandler is used by an OCAP-J application
* for the following purposes:
* 1) receive an APDU from the CableCARD device,
* 2) detect an unsent APDU to the POD in case of an error,
* and 3) notification of becoming registered and unregistered.
*
* @see SystemModuleRegistrar
*
* @author Patrick Ladd
* @author Shigeaki Watanabe (modified by ECN 03.0531-4)
*/
public interface SystemModuleHandler {
/**
*
* This is a call back method to notify an APDU received from the
* CableCARD device.
* The APDU structure is defined in Table 16 in Section 8.3 of EIA-679-B
* referred by [CCIF 2.0] and SCTE 28 2003.
* The APDU structure consists of apdu_tag, length_field and data_byte.
*
* For the Private Host Application on the SAS Resource, the
* SystemModuleHandler is bound to a specific session number (and
* a specific Private Host Application ID) when it is registered
* via the {@link SystemModuleRegistrar#registerSASHandler} method.
* Only the receiveAPDU() method that is bound to the session of the
* received APDU shall be called only once by the OCAP implementation.
*
* For the MMI Resource and the Application Information Resource,
* the OCAP-J application can receive APDUs for both Resources by
* a single SystemModuleHandler.
* The OCAP implementation shall call the receiveAPDU() method of
* the SystemModuleHandler registered via the
* {@link SystemModuleRegistrar#registerMMIHandler} method
* only once for both the MMI and Application Information APDU.
*
* The OCAP implementation extract the APDU from an SPDU from
* the CableCARD device according to the OpenCable CableCARD Interface
* Specification, and then call this method. Note that the OCAP
* implementation simply retrieves the field values from the APDU
* and call this method. No validity check is done by the OCAP
* implementation. Though SPDU and TPDU mechanism may detect a
* destruction of the APDU structure while transmitting, the OCAP
* shall call this method every time when it receives an APDU. In
* such case, the parameters may be invalid so that the OCAP-J
* application can detect an error.
*
* Note that if the CableCARD device returns an APDU indicating an error
* condition, this method is called instead of the sendAPDUFailed()
* method.
*
* This method shall return immediately.
*
*
* @param apduTag an apdu_tag value in the APDU coming from the
* CableCARD device. I.e., first 3 bytes. If the corresponding
* bytes are missed, they are filled by zero. Note that
* the OCAP implementation calls this method according
* to the session number, so the apdu_tag value may be
* out of the valid range.
*
* @param lengthField a length_field value in the APDU coming from
* the CableCARD device. This is a decimal int value
* converted from a length field encoded in ASN.1 BER.
* If the corresponding bytes are missing, the value of
* this parameter is set to 0.
*
* @param dataByte an data_byte bytes in the APDU coming from the
* CableCARD device. If the corresponding bytes are missed since
* signaling trouble, only existing bytes are specified.
* If they are more than expected length, all existing
* bytes are specified.
* The APDU consists of the specified apdu_tag, dataByte
* and length_field. The APDU format is defined in [CCIF 2.0].
*
*/
public void receiveAPDU(int apduTag, int lengthField, byte[] dataByte);
/**
* This is a call back method to notify an error has occurred
* while sending an APDU via the {@link SystemModule#sendAPDU}
* method. This method shall return immediately.
*
* @param apduTag an apdu_tag of the APDU that was failed to
* be sent.
* This is the apduTag value specified in the
* SystemModule.sendAPDU() method.
*
* @param dataByte an data_byte of the APDU that was failed
* to be sent.
* This is dataByte value specified in the
* SystemModule.sendAPDU() method.
*
*/
public void sendAPDUFailed(int apduTag, byte[] dataByte);
/**
* This is a call back method to notify that the
* SystemModuleHandler is being unregistered and give a chance
* to do a termination procedure. This method returns after the
* termination procedure has finished.
*/
public void notifyUnregister();
/**
* This is a call back method to notify that this
* SystemModuleHandler is ready to receive an APDU, and returns a
* SystemModule to send an APDU to the CableCARD device.
*
* @param systemModule a SystemModule instance corresponding to
* this SystemModuleHandler. The returned SystemModule
* sends an APDU using the same session that this
* SystemModuleHandler receives an APDU.
* Null is specified, if the OCAP implementation fails
* to establish a SAS connection or fails to create an
* SystemModule instance due to lack of resource.
*
*/
public void ready(SystemModule systemModule);
}