**javacard.framework.service** ====Class BasicService ==== *[[javacard:java-card-api:object|java.lang.Object]] \\ **All Implemented Interfaces:** [[javacard:java-card-api:Service|Service]] **Direct Known Subclasses:** [[javacard:java-card-api:RMIService|RMIService]] ---- public class **BasicService**extends [[javacard:java-card-api:Object|Object]] implements [[javacard:java-card-api:Service|Service]] This class should be used as the base class for implementing services. It provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that manage the APDU buffer to enable co-operation among different Services. The BasicService class uses the state of APDU processing to enforce the validity of the various helper operations. It expects and maintains the following Common Service Format (CSF) of data in the APDU Buffer corresponding to the various APDU processing states (See [[javacard:java-card-api:APDU|APDU]] ): Init State format of APDU Buffer. This format corresponds to the APDU processing state - STATE_INITIAL : 012345 < - offset +------------------------------------------------------------+ | CLA | INS | P1 | P2 | P3 | ... Implementation dependent ...| +------------------------------------------------------------+ Input Ready format of APDU Buffer. This format corresponds to the APDU processing state - STATE_FULL_INCOMING. 012345 < - offset +------------------------------------------------------------+ | CLA | INS | P1 | P2 | Lc | Incoming Data( Lc bytes )| +------------------------------------------------------------+ Output Ready format of APDU Buffer. This format corresponds to the APDU processing status - STATE_OUTGOING .. STATE_FULL_OUTGOING 012345 < - offset +------------------------------------------------------------+ | CLA | INS | SW1 | SW2 | La | Outgoing Data( La bytes )| +------------------------------------------------------------+ When the APDU buffer is in the Init and Input Ready formats, the helper methods allow input access methods but flag errors if output access is attempted. Conversely, when the APDU buffer is in the Output format, input access methods result in exceptions. The Common Service Format (CSF) of the APDU Buffer is only defined for APDUs using the short length (normal semantics) of the ISO7816 protocol. When an implementation supports extended length APDU format (see [[javacard:java-card-api:ExtendedLength|ExtendedLength]] ) and an APDU with more than 255 input or output data bytes is being processed, the behavior of BasicService class is undefined. If the header areas maintained by the BasicService helper methods are modified directly in the APDU buffer and the format of the APDU buffer described above is not maintained, unexpected behavior might result. In addition, both La=0 and La=256 are represented in the CSF format as La=0. The distinction is implementation dependent. The getOutputLength method must be used to avoid ambiguity. Many of the helper methods also throw exceptions if the APDU object is in an error state ( processing status code < 0 ). **Version:** 1.0 **See Also:**[[javacard:java-card-api:APDU|APDU]] , [[javacard:java-card-api:ExtendedLength|javacardx.apdu.ExtendedLength]] ---- ^ Constructor Summary ^^ | **[[javacard:java-card-api:BasicService#BasicService()|BasicService]] **()          Creates new BasicService. |   ^ Method Summary ^^ | ** boolean** | **[[javacard:java-card-api:BasicService#fail(javacard.framework.APDU, short)|fail]] **([[javacard:java-card-api:APDU|APDU]]  apdu,short sw)          Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has failed. | | ** byte** | **[[javacard:java-card-api:BasicService#getCLA(javacard.framework.APDU)|getCLA]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the class byte for the command in the APDU object. | | ** byte** | **[[javacard:java-card-api:BasicService#getINS(javacard.framework.APDU)|getINS]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the instruction byte for the command in the APDU object. | | ** short** | **[[javacard:java-card-api:BasicService#getOutputLength(javacard.framework.APDU)|getOutputLength]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the output length for the command in the APDU object. | | ** byte** | **[[javacard:java-card-api:BasicService#getP1(javacard.framework.APDU)|getP1]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the first parameter byte for the command in the APDU object. | | ** byte** | **[[javacard:java-card-api:BasicService#getP2(javacard.framework.APDU)|getP2]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the second parameter byte for the command in the APDU object. | | ** short** | **[[javacard:java-card-api:BasicService#getStatusWord(javacard.framework.APDU)|getStatusWord]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Returns the response status word for the command in the APDU object. | | ** boolean** | **[[javacard:java-card-api:BasicService#isProcessed(javacard.framework.APDU)|isProcessed]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Checks if the command in the APDU object has already been //processed//. | | ** boolean** | **[[javacard:java-card-api:BasicService#processCommand(javacard.framework.APDU)|processCommand]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          This BasicService method is a default implementation and simply returns false without performing any processing. | | ** boolean** | **[[javacard:java-card-api:BasicService#processDataIn(javacard.framework.APDU)|processDataIn]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          This BasicService method is a default implementation and simply returns false without performing any processing. | | ** boolean** | **[[javacard:java-card-api:BasicService#processDataOut(javacard.framework.APDU)|processDataOut]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          This BasicService method is a default implementation and simply returns false without performing any processing. | | ** short** | **[[javacard:java-card-api:BasicService#receiveInData(javacard.framework.APDU)|receiveInData]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Receives the input data for the command in the APDU object if the input has not already been received. | | ** boolean** | **[[javacard:java-card-api:BasicService#selectingApplet()|selectingApplet]] **()          This method is used to determine if the command in the APDU objectis the applet SELECT FILE command which selected the currently selected applet. | | ** void** | **[[javacard:java-card-api:BasicService#setOutputLength(javacard.framework.APDU, short)|setOutputLength]] **([[javacard:java-card-api:APDU|APDU]]  apdu,short length)          Sets the output length of the outgoing response for the command in the APDU object. | | ** void** | **[[javacard:java-card-api:BasicService#setProcessed(javacard.framework.APDU)|setProcessed]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Sets the processing state of the command in the APDU object to //processed//. | | ** void** | **[[javacard:java-card-api:BasicService#setStatusWord(javacard.framework.APDU, short)|setStatusWord]] **([[javacard:java-card-api:APDU|APDU]]  apdu,short sw)          Sets the response status word for the command in the APDU object. | | ** boolean** | **[[javacard:java-card-api:BasicService#succeed(javacard.framework.APDU)|succeed]] **([[javacard:java-card-api:APDU|APDU]]  apdu)          Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has succeeded. | | ** boolean** | **[[javacard:java-card-api:BasicService#succeedWithStatusWord(javacard.framework.APDU, short)|succeedWithStatusWord]] **([[javacard:java-card-api:APDU|APDU]]  apdu,short sw)          Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has partially succeeded. |   ^ Methods inherited from class java.lang.Object ^ | [[javacard:java-card-api:Object#equals(java.lang.Object)|equals]] |   ^ Constructor Detail ^ === BasicService === public **BasicService**() Creates new BasicService. ^ Method Detail ^ === processDataIn === public boolean **processDataIn**([[javacard:java-card-api:APDU|APDU]]  apdu) This BasicService method is a default implementation and simply returns false without performing any processing. **Specified by:**[[javacard:java-card-api:Service#processDataIn(javacard.framework.APDU)|processDataIn]] in interface [[javacard:java-card-api:Service|Service]] **Parameters:**apdu - the APDU object containing the command being processed **Returns:**false ---- === processCommand === public boolean **processCommand**([[javacard:java-card-api:APDU|APDU]]  apdu) This BasicService method is a default implementation and simply returns false without performing any processing. **Specified by:**[[javacard:java-card-api:Service#processCommand(javacard.framework.APDU)|processCommand]] in interface [[javacard:java-card-api:Service|Service]] **Parameters:**apdu - the APDU object containing the command being processed **Returns:**false ---- === processDataOut === public boolean **processDataOut**([[javacard:java-card-api:APDU|APDU]]  apdu) This BasicService method is a default implementation and simply returns false without performing any processing. **Specified by:**[[javacard:java-card-api:Service#processDataOut(javacard.framework.APDU)|processDataOut]] in interface [[javacard:java-card-api:Service|Service]] **Parameters:**apdu - the APDU object containing the command being processed **Returns:**false ---- === receiveInData === public short **receiveInData**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Receives the input data for the command in the APDU object if the input has not already been received. The entire input data must fit in the APDU buffer starting at offset 5. When invoked, the APDU object must either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format **Parameters:**apdu - the APDU object containing the apdu being processed **Returns:**the length of input data received and present in the APDU Buffer **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING or, \\ *ServiceException.COMMAND_DATA_TOO_LONG if the input data does not fit in the APDU buffer starting at offset 5. \\ ---- === setProcessed === public void **setProcessed**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Sets the processing state of the command in the APDU object to //processed//. This is done by setting the APDU object in outgoing mode by invoking the APDU.setOutgoing method. If the APDU is already in outgoing mode, this method does nothing (allowing the method to be called several times). **Parameters:**apdu - the APDU object containing the command being processed **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === isProcessed === public boolean **isProcessed**([[javacard:java-card-api:APDU|APDU]]  apdu) Checks if the command in the APDU object has already been //processed//. This is done by checking whether or not the APDU object has been set in outgoing mode via a previous invocation of the APDU.setOutgoing method. Note: \\ *//This method returns true if the APDU object is not accessible (APDU object in STATE_ERROR_.. ).// \\ **Parameters:**apdu - the APDU object containing the command being processed **Returns:**true if the command has been //processed//, false otherwise ---- === setOutputLength === public void **setOutputLength**([[javacard:java-card-api:APDU|APDU]]  apdu, short length) throws [[javacard:java-card-api:ServiceException|ServiceException]] Sets the output length of the outgoing response for the command in the APDU object. This method can be called regardless of the current state of the APDU processing. **Parameters:**apdu - the APDU object containing the command being processed length - the number of bytes in the response to the command **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.ILLEGAL_PARAM if the length parameter is greater than 256 or if the outgoing response will not fit within the APDU Buffer. \\ ---- === getOutputLength === public short **getOutputLength**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Returns the output length for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been //processed//. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**a value in the range: 0 to 256(inclusive), that represents the number of bytes to be returned for this command **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not //processed// or if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === setStatusWord === public void **setStatusWord**([[javacard:java-card-api:APDU|APDU]]  apdu, short sw) Sets the response status word for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command. **Parameters:**apdu - the APDU object containing the command being processed sw - the status word response for this command ---- === getStatusWord === public short **getStatusWord**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Returns the response status word for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been //processed//. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**the status word response for this command **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not //processed// or if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === fail === public boolean **fail**([[javacard:java-card-api:APDU|APDU]]  apdu, short sw) throws [[javacard:java-card-api:ServiceException|ServiceException]] Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has failed. Sets the output length to 0 and the status word of the response to the specified value. **Parameters:**apdu - the APDU object containing the command being processed sw - the status word response for this command **Returns:**true **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === succeed === public boolean **succeed**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has succeeded. Sets the status word of the response to 0x9000. The output length of the response must be set separately. **Parameters:**apdu - the APDU object containing the command being processed. **Returns:**true **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === succeedWithStatusWord === public boolean **succeedWithStatusWord**([[javacard:java-card-api:APDU|APDU]]  apdu, short sw) throws [[javacard:java-card-api:ServiceException|ServiceException]] Sets the processing state for the command in the APDU object to //processed//, and indicates that the processing has partially succeeded. Sets the the status word of the response to the specified value. The output length of the response must be set separately. **Parameters:**apdu - the APDU object containing the command being processed sw - the status word to be returned for this command **Returns:**true **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. ) \\ **See Also:**[[javacard:java-card-api:APDU#getCurrentState()|javacard.framework.APDU.getCurrentState()]] ---- === getCLA === public byte **getCLA**([[javacard:java-card-api:APDU|APDU]]  apdu) Returns the class byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**the value of the CLA byte ---- === getINS === public byte **getINS**([[javacard:java-card-api:APDU|APDU]]  apdu) Returns the instruction byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**the value of the INS byte ---- === getP1 === public byte **getP1**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Returns the first parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**the value of the P1 byte **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING. \\ ---- === getP2 === public byte **getP2**([[javacard:java-card-api:APDU|APDU]]  apdu) throws [[javacard:java-card-api:ServiceException|ServiceException]] Returns the second parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING. **Parameters:**apdu - the APDU object containing the command being processed **Returns:**the value of the P2 byte **Throws:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING. \\ ---- === selectingApplet === public boolean **selectingApplet**() This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet. **Returns:**true if applet SELECT FILE command is being processed