Package org.calypsonet.terminal.calypso.card

Interface CalypsoCardSelection

  • All Superinterfaces:
    org.calypsonet.terminal.reader.selection.spi.CardSelection
    public interface CalypsoCardSelection
extends org.calypsonet.terminal.reader.selection.spi.CardSelection
    Card specific CardSelection providing means to filter cards, select applications and define optional commands to be executed during the selection phase.

    Note 1: by default, the selection process ignores PRIME revision 3 cards that have been invalidated. The acceptInvalidatedCard() method must be invoked to stop ignoring them.
    This feature does not apply to earlier revisions for which it is necessary to run a Select File (DF) command to determine the invalidation status. In this case, the rejection or acceptance of invalidated cards will have to be handled by the application.

    Note 2: the APDU commands resulting from the invocation of the "prepare" methods shall be compliant with the PRIME revision 3 cards.

    For all "prepare" type commands, unless otherwise specified, here are the ranges of values checked for the various parameters:

    • SFI: [0..30] (0 indicates the current EF)
    • Record number: [1..250]
    • Counter number: [1..83]
    • Counter value: [0..16777215]
    • Offset: [0..249] or [0..32767] for binary files (0 indicates the first byte)
    • Input data length: [1..250] or [1..32767] for binary files
    Since:
    1.0.0

    • Method Detail

      • filterByCardProtocol

        CalypsoCardSelection filterByCardProtocol​(java.lang.String cardProtocol)
        Requests a protocol-based filtering by defining an expected card.

        If the card protocol is set, only cards using that protocol will match the card selector.

        Parameters:
        cardProtocol - A not empty String.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the argument is null or empty.
        Since:
        1.0.0

      • filterByPowerOnData

        CalypsoCardSelection filterByPowerOnData​(java.lang.String powerOnDataRegex)
        Requests a power-on data-based filtering by defining a regular expression that will be applied to the card's power-on data.

        If it is set, only the cards whose power-on data is recognized by the provided regular expression will match the card selector.

        Parameters:
        powerOnDataRegex - A valid regular expression.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the provided regular expression is null, empty or invalid.
        Since:
        1.0.0

      • filterByDfName

        CalypsoCardSelection filterByDfName​(byte[] aid)
        Requests a DF Name-based filtering by defining in a byte array the AID that will be included in the standard SELECT APPLICATION command sent to the card during the selection process.

        The provided AID can be a right truncated image of the target DF Name (see ISO 7816-4 4.2).

        Parameters:
        aid - A byte array containing 5 to 16 bytes.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the provided array is null or out of range.
        Since:
        1.0.0

      • filterByDfName

        CalypsoCardSelection filterByDfName​(java.lang.String aid)
        Requests a DF Name-based filtering by defining in a hexadecimal string the AID that will be included in the standard SELECT APPLICATION command sent to the card during the selection process.

        The provided AID can be a right truncated image of the target DF Name (see ISO 7816-4 4.2).

        Parameters:
        aid - A hexadecimal string representation of 5 to 16 bytes.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the provided AID is null, invalid or out of range.
        Since:
        1.0.0

      • addSuccessfulStatusWord

        @Deprecated
CalypsoCardSelection addSuccessfulStatusWord​(int statusWord)
        Deprecated.
        Use acceptInvalidatedCard() method instead. (will be soon removed)
        Adds a status word to the list of those that should be considered successful for the Select Application APDU.

        Note: initially, the list contains the standard successful status word 9000h.

        Parameters:
        statusWord - A positive int ≤ FFFFh.
        Returns:
        The object instance.
        Since:
        1.0.0

      • acceptInvalidatedCard

        CalypsoCardSelection acceptInvalidatedCard()
        Request to accept invalidated cards during the selection stage.

        Caution: this functionality is operational only from PRIME revision 3 cards. Invalidated cards are rejected by default.

        Returns:
        The object instance.
        Since:
        1.0.0

      • prepareSelectFile

        @Deprecated
CalypsoCardSelection prepareSelectFile​(byte[] lid)
        Deprecated.
        Use prepareSelectFile(short) method instead. (will be soon removed)
        Adds a command APDU to select file with an LID provided as a 2-byte byte array.

        Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Parameters:
        lid - LID of the EF to select as a byte array
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the argument is not an array of 2 bytes.
        Since:
        1.0.0

      • prepareSelectFile

        CalypsoCardSelection prepareSelectFile​(short lid)
        Adds a command APDU to select an EF by its LID in the current DF.

        Caution 1: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Caution 2: the command will fail if the selected file is not an EF.

        Parameters:
        lid - The LID of the EF to select.
        Returns:
        The object instance.
        Since:
        1.0.0

      • prepareSelectFile

        CalypsoCardSelection prepareSelectFile​(SelectFileControl selectControl)
        Adds a command APDU to select file according to the provided SelectFileControl enum entry indicating the navigation case: FIRST, NEXT or CURRENT.

        Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Parameters:
        selectControl - A SelectFileControl enum entry.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If the argument is null.
        Since:
        1.0.0

      • prepareReadRecordFile

        @Deprecated
CalypsoCardSelection prepareReadRecordFile​(byte sfi,
                                           int recordNumber)
        Deprecated.
        Use prepareReadRecord(byte, int) method instead. (will be soon removed)
        Adds a command APDU to read a single record from the indicated EF.

        Once this command is processed, the result is available in CalypsoCard if the requested file and record exist in the file structure of the card (best effort behavior).

        Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Parameters:
        sfi - The SFI of the EF to read
        recordNumber - The record number to read.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.0.0

      • prepareReadRecord

        CalypsoCardSelection prepareReadRecord​(byte sfi,
                                       int recordNumber)
        Adds a command APDU to read a single record from the indicated EF.

        Once this command is processed, the result is available in CalypsoCard if the requested file and record exist in the file structure of the card (best effort behavior).

        Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Parameters:
        sfi - The SFI of the EF to read
        recordNumber - The record number to read.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If one of the provided argument is out of range.
        Since:
        1.1.0

      • prepareGetData

        CalypsoCardSelection prepareGetData​(GetDataTag tag)
        Adds a command APDU to retrieve the data indicated by the provided tag.

        This method can be used to obtain FCI information when it is not provided directly by the select application (e.g. OMAPI case).

        Caution: the resulting APDU command must be compliant with PRIME revision 3 cards. Therefore, the command may be rejected by some earlier revision cards.

        Parameters:
        tag - The tag to use.
        Returns:
        The object instance.
        Throws:
        java.lang.IllegalArgumentException - If tag is null.
        Since:
        1.0.0