Package org.eclipse.keypop.storagecard.transaction

Interface StorageCardTransactionManager

public interface StorageCardTransactionManager
Provides methods to manage APDU exchanges with a storage card.

This interface allows to:

  • Prepare read and write operations to the card
  • Process prepared commands in a single transaction
  • Manage the communication channel with the card
Since:
1.0.0

  • Method Details

    • prepareReadSystemBlock

      StorageCardTransactionManager prepareReadSystemBlock()
      Prepares the reading of the system block from the storage card when present.

      Not all storage card types include a system block. This method should only be called for card types that support system block access.

      Once this command is processed, the result is available in StorageCard.

      Returns:
      The current instance.
      Throws:
      UnsupportedOperationException - If the current card type does not support system block access.
      Since:
      1.0.0

    • prepareWriteSystemBlock

      StorageCardTransactionManager prepareWriteSystemBlock(byte[] data)
      Prepares the writing of data to the system block of the storage card when present.

      System blocks contain card-specific metadata and configuration data. Not all storage card types include a system block that can be written to. This method should only be called for card types that support system block write access.

      The data length must match the block size defined by the card's ProductType.

      Important: After execution of this write command, the StorageCard memory image is not automatically updated. Some storage card technologies do not provide reliable status codes to confirm successful write operations. To ensure data consistency, an explicit read operation must be performed after the write to refresh the memory image and verify the actual content stored on the card.

      Parameters:
      data - The data to be written to the system block. The length must match the card's block size.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If data is null or its length does not match the block size.
      UnsupportedOperationException - If the current card type does not support system block write access.
      Since:
      1.0.0
      See Also:

    • prepareReadBlock

      StorageCardTransactionManager prepareReadBlock(int blockAddress)
      Prepares the reading of a specific block from the storage card.

      Block addresses start at 0 and the maximum value is equal to ProductType.getBlockCount() - 1.

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      blockAddress - The address of the block to be read.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the block address is out of range.
      Since:
      1.0.0
      See Also:

    • prepareReadBlocks

      StorageCardTransactionManager prepareReadBlocks(int fromBlockAddress, int toBlockAddress)
      Prepares the reading of a range of blocks from the storage card.

      Block addresses start at 0 and the maximum value is equal to ProductType.getBlockCount() - 1.

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      fromBlockAddress - The starting block address (inclusive).
      toBlockAddress - The ending block address (inclusive).
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the arguments is out of range.
      Since:
      1.0.0
      See Also:

    • prepareWriteBlocks

      StorageCardTransactionManager prepareWriteBlocks(int fromBlockAddress, byte[] data)
      Prepares the writing of blocks of data to the storage card starting from a specific block number offset.

      The provided data should be a byte array representing the content of the blocks to be written. The number of blocks that will be written is determined by the length of the data array divided by the block size of the storage card. The block size is provided by ProductType.getBlockSize().

      Important: Some storage card technologies do not provide reliable status codes to confirm successful write operations. For such cards (e.g., SRT512/ST25), the library automatically performs a verification read after each write to ensure that the data has been correctly stored. For cards that provide a reliable write acknowledgment, no additional read is performed. In all cases, the library guarantees the integrity of the written data, and the application does not need to explicitly perform verification reads.

      Parameters:
      fromBlockAddress - The offset from which the blocks will be written.
      data - The data to be written to the storage card.
      Returns:
      The current instance of the StorageCardTransactionManager.
      Throws:
      IllegalArgumentException - If data is null or its length is not a multiple of the block size.
      Since:
      1.0.0
      See Also:

    • processCommands

      StorageCardTransactionManager processCommands(ChannelControl channelControl) throws ReaderIOException, CardIOException, UnexpectedCommandStatusException
      Processes all previously prepared commands and closes the physical channel if requested.

      All APDUs corresponding to the prepared commands are sent to the card, their responses are retrieved and used to update the StorageCard associated with the transaction.

      For read commands: The StorageCard memory image is updated with the data retrieved from the card.

      For write commands: The StorageCard memory image is not updated even when the command appears successful, as some storage card technologies do not provide reliable confirmation of write completion. Applications should perform explicit read operations after writes to verify the actual card content and update the memory image.

      The process is interrupted at the first failed command.

      Parameters:
      channelControl - Policy for managing the physical channel after executing commands to the card.
      Returns:
      The current instance.
      Throws:
      ReaderIOException - If a communication error with the card reader or the cryptographic module reader occurs.
      CardIOException - If a communication error with the card occurs.
      UnexpectedCommandStatusException - If one of the prepared command failed.
      Since:
      1.0.0