Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## opencard.core.service
Class CardChannel

    java.lang.Object
      |
      +--opencard.core.service.CardChannel

public class CardChannel
extends java.lang.Object

A communication channel to a smartcard. A channel is used to exchange APDUs with an associated smartcard. Additionally, it can be used to access some other resources related to the associated card, like the terminal into which it is inserted.
`CardChannel` is the card service layer pendant to the terminal layer's `SlotChannel`. The slot channel is a physical channel, onto which several logical card channels can be multiplexed if the smartcard supports logical channels.

See Also:
  `SlotChannel`, `CardServiceScheduler`

Constructor Summary
`protected` | `CardChannel(SlotChannel slotchannel)` Instantiate a new logical card channel.

Method Summary
`void` | `close()` Closes this `CardChannel`.
`protected void` | `closeFinal()` Closes this `CardChannel` so it cannot be opened anymore.
`void` | `finalize()` Tries to clean up.
`CardTerminal` | `getCardTerminal()` Returns the card terminal associated with this channel.
`java.lang.Object` | `getState()` Retrieves the service specific object associated with this channel.
`boolean` | `isOpen()` Checks whether this channel is currently open.
`void` | `open()` Opens this `CardChannel`.
`ResponseAPDU` | `sendCommandAPDU(CommandAPDU cmdAPDU)` Sends a `CommandAPDU` to the smart card.
`ResponseAPDU` | `sendVerifiedAPDU(CommandAPDU command, CHVControl control, CHVDialog dialog)` Sends a command including a PIN to the smart card within a given time.
`ResponseAPDU` | `sendVerifiedAPDU(CommandAPDU command, CHVControl control, CHVDialog dialog, int timeout)` Deprecated.
`void` | `setState(java.lang.Object state)` Stores a service specific object associated with this channel.
`java.lang.String` | `toString()` Returns a string representation of this card channel.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### CardChannel

    protected CardChannel(SlotChannel slotchannel)

  Instantiate a new logical card channel. The new channel has the given underlying physical slot channel which will be used to contact the smartcard.
  Parameters:
    `slotchannel` - the physical channel to the smartcard

Method Detail

### isOpen

    public final boolean isOpen()

  Checks whether this channel is currently open. A channel can be used for communication with the associated smartcard only while it's open.
  Returns:
    `true` if this channel is open, `false` otherwise

### getCardTerminal

    public CardTerminal getCardTerminal()

  Returns the card terminal associated with this channel. The card channel is a logical channel, which is mapped onto a physical slot channel. The slot channel is associated with the slot into which the smartcard is inserted. The slot itself is associated with a card terminal. That card terminal is queried using this method.
  Returns:
    The terminal that owns the underlying slot channel.
  See Also:
    `SlotChannel`, `Slot`

### setState

    public final void setState(java.lang.Object state)

  Stores a service specific object associated with this channel. The object stored can be retrieved by `getState`. By convention, this method is invoked only by a card service that has currently allocated this channel. The state object can, for example, be used to store the current selection. It allows card services to cooperate without knowing about each other, as long as they use the same conventions for the objects stored here. The state is associated with a channel rather than a smartcard, since a smartcard may support several logical channels with partially independent states.
  Parameters:
    `state` - the object to associate with this channel, or `null` to reset previous associations
  See Also:
    `getState()`

### getState

    public final java.lang.Object getState()

  Retrieves the service specific object associated with this channel. This method returns the argument to the last invocation of `setState`. By convention, it is invoked only by a card service that has currently allocated this channel. The object retrieved has been stored by a service that used this channel before.
  Returns:
    the object currently associated with this channel, or `null` if there is no association
  See Also:
    `setState(java.lang.Object)`

### sendCommandAPDU

    public ResponseAPDU sendCommandAPDU(CommandAPDU cmdAPDU)
                                 throws InvalidCardChannelException,
                                        CardTerminalException

  Sends a `CommandAPDU` to the smart card. Receives and returns the smartcard's response.
  Parameters:
    `cmdAPDU` - the `CommandAPDU` to send
  Returns:
    the response from the smartcard
  Throws:
    InvalidCardChannelException - This channel is currently not open.

### sendVerifiedAPDU

    public final ResponseAPDU sendVerifiedAPDU(CommandAPDU command,
                                               CHVControl control,
                                               CHVDialog dialog,
                                               int timeout)
                                        throws InvalidCardChannelException,
                                               CardTerminalException,
                                               CardServiceInvalidCredentialException

  Deprecated.

### sendVerifiedAPDU

    public final ResponseAPDU sendVerifiedAPDU(CommandAPDU command,
                                               CHVControl control,
                                               CHVDialog dialog)
                                        throws InvalidCardChannelException,
                                               CardTerminalException,
                                               CardServiceInvalidCredentialException

  Sends a command including a PIN to the smart card within a given time. The APDU to send will be modified on it's way to the card by storing a PIN or password which has been entered by the card owner. This method supports GUI password dialogs as well as a card terminal's encrypting pinpad, if available. The smartcard's response to the command is received and returned if the operation completes within the specified timeout.
  The decision whether the terminal or a GUI dialog is used for querying the password is crucial to security. Currently, the GUI is used only if the terminal does not implement the interface `VerifiedAPDUInterface`. This behavior must not be changed in derived classes, therefore this method is `final`.
  Parameters:
    `command` - the `CommandAPDU` to send
    `control` - the verification parameters to use
    `dialog` - the dialog to use to query a password. Ignored if the terminal takes the reponsibility for querying the password or PIN. The default dialog is used if this argument is `null`.
  Returns:
    the response from the smartcard
  Throws:
    InvalidCardChannelException - This channel is currently not open.
    CardTerminalException - The terminal encountered an error.
    CardServiceInvalidCredentialException - The user cancelled password input.
  See Also:
    `VerifiedAPDUInterface`, `CardHolderVerificationGUI`

### open

    public void open()
              throws InvalidCardChannelException

  Opens this `CardChannel`. This method cannot be invoked after the channel has been closed for good by an invocation of `closeFinal()`. The default visibility is (would be) sufficient since it gets called by the scheduler, which resides in the same package.
  Parameters:
    `owner` - the object now considered to be the owner of this channel
  Throws:
    InvalidCardChannelException - This channel is already open, or closed for good.

### close

    public void close()

  Closes this `CardChannel`. It can still be opened again. While the channel is not open, invocations of the send methods will throw an exception.

### closeFinal

    protected void closeFinal()

  Closes this `CardChannel` so it cannot be opened anymore.

### finalize

    public void finalize()

  Tries to clean up.
  Overrides:
    finalize in class java.lang.Object

### toString

    public java.lang.String toString()

  Returns a string representation of this card channel.
  Returns:
    a human-readable representation of this channel
  Overrides:
    toString in class java.lang.Object

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD