org.opennfc.se
Interface SeSlot

public interface SeSlot

The Secure Element Slot represent an instance of Secure Element.

Since:

Open NFC 4.3

SCOPE_BOOT

static final int SCOPE_BOOT

Scope of the policy: Policy applied when the device boots (persistent value)

See Also:

Constant Field Values

SCOPE_CURRENT

static final int SCOPE_CURRENT

Scope of the policy: Current value, applied immediately (non-persistent value)

See Also:

Constant Field Values

SCOPE_BAT_OFF

static final int SCOPE_BAT_OFF

Scope of the policy: Policy applied in battery off or in battery low (persistent value)

See Also:

Constant Field Values

getName

String getName()

Returns the name of the Secure Element.

Returns:

the name.

isPresent

boolean isPresent()
                  throws NfcException

Returns true if a Secure Element is present in the slot.

Returns:

true if a Secure Element is present, false otherwise.

Throws:

IllegalStateException - if another operation is pending with the Secure Element.

NfcException - The Secure Element does not support the communication or the Secure Element is not responding.

getSwpStatus

SeSlot.SwpStatus getSwpStatus()
                              throws NfcException

Returns the current SWP Status.

Returns:

the current SWP Status.

Throws:

IllegalStateException - if another operation is pending with the Secure Element.

NfcException - The Secure Element does not support the communication or the Secure Element is not responding.

isRemovable

boolean isRemovable()

Returns true if a Secure Element is removable.

Returns:

true if the Secure Element is removable, false otherwise.

isUicc

boolean isUicc()

Returns true if this Secure Element is a UICC.

Returns:

true if the Secure Element is a UICC, false otherwise.

supportTransactionEvent

boolean supportTransactionEvent()

Returns true if the Secure Element may send transaction events.

Returns:

true if the Secure Element may send transaction events, false otherwise.

supportHotPlugEvent

boolean supportHotPlugEvent()

Returns true if the slot may send hot-plug events.

Returns:

true if the slot may send hot-plug events, false otherwise.

supportConnectivityEvent

boolean supportConnectivityEvent()

Returns true if the Secure Element may send connectivity events.

Returns:

true if the Secure Element may send connectivity events, false otherwise.

supportCommunication

boolean supportCommunication()

Returns true if the Secure Element support the communication using openConnection().

Returns:

true if the Secure Element support the communication, false otherwise.

openConnection

Iso7816Part4Connection openConnection(boolean force)
                                      throws NfcException

Opens a connection with the Secure Element.

If force is set to true, the connection will be open even if:

• a card emulation session is on going with the SE. In this case this will cut off the card emulation session.
• a reader is communicating with an external card. In this case this will cut off the reader session.

If force is set to false, the connection will be created only when the current card emulation is stopped and when there is no reader communication with an external card.

If there is no card emulation and no reader active, the connection is immediate.

Parameters:

force - the flag forcing the connection.

Returns:

the connection on the Secure Element.

Throws:

IllegalStateException - A connection with the Secure Element is already open.

NfcException - The Secure Element does not support the communication or the Secure Element is not responding.

getPolicy

boolean getPolicy(int scope,
                  boolean cardEmulation,
                  ConnectionProperty protocol)

Gets the policy of the Secure Element.

The policy defines the protocol allowed for the secure element with the external RF interface.

Parameters:

scope - the scope of the policy is one of the following values:

• SCOPE_BOOT policy applied when the device boots (persistent value),
• SCOPE_CURRENT current value, applied immediately (non-persistent value), or
• SCOPE_BAT_OFF policy applied in battery off or in battery low (persistent value)

cardEmulation - true for the card emulation policy, false for the card listener policy.

protocol - the protocol of the policy.

Returns:

true if the specified protocol is allowed by the policy with the specified scope, false otherwise.

Throws:

IllegalArgumentException - if protocol is null or the scope value is invalid.

setPolicy

void setPolicy(int scope,
               boolean cardEmulation,
               ConnectionProperty protocol,
               boolean value)
               throws NfcException

Sets the policy of the Secure Element.

The policy defines the protocol allowed for the secure element with the RF interface.

Parameters:

scope - the scope of the policy is one of the following values:

• SCOPE_BOOT policy applied when the device boots (persistent value),
• SCOPE_CURRENT current value, applied immediately (non-persistent value), or
• SCOPE_BAT_OFF policy applied in battery off or in battery low (persistent value)

cardEmulation - true for the card emulation policy, false for the card listener policy.

protocol - the protocol of the policy.

value - true if the specified protocol is allowed by the policy with the specified scope, false otherwise.

Throws:

IllegalArgumentException - if protocol is null or the scope value is invalid.

IllegalArgumentException - if the protocol is not supported by the Secure Element.

SecurityException - if the application is not allowed to the set the policy for this Secrue Element.

IllegalStateException - if another operation is pending with the Secure Element.

NfcException - if an error occures when the policy is set.

isProtocolSupported

boolean isProtocolSupported(boolean cardEmulation,
                            ConnectionProperty protocol)

Checks if a protocol is supported by the Secure Element for the RF interface.

Parameters:

cardEmulation - true for the card emulation protocol, false for the card listener protocol.

protocol - the protocol to check.

Returns:

true if the protocol is supported, false otherwise.

Throws:

IllegalArgumentException - if protocol is null.

registerEventHandler

void registerEventHandler(SeSlotEventHandler handler)
                          throws NfcException

Registers an event handler for the slot.

Parameters:

handler - the event handler to register.

Throws:

IllegalArgumentException - if handler is null.

IllegalStateException - an event handler is already registered for this slot.

NfcException - with code W_ERROR_FEATURE_NOT_SUPPORTED if se does not support this feature.

unregisterEventHandler

void unregisterEventHandler(SeSlotEventHandler handler)

Unregisters an event handler for the slot.

Parameters:

handler - the event handler to unregister.

Throws:

IllegalArgumentException - if handler is null or if it is not the registered one.

IllegalStateException - there is not any event handler registered for this slot.

checkAidAccess

boolean checkAidAccess(byte[] aid,
                       byte[] impersonationData)

Checks the access to an AID. checkAidAccess() is used by the implementation of a transaction registry application implementing the dispatch of the transaction events to other applications. Thus checkAidAccess() does not check the access rights of the caller application. checkAidAccess() checks the access rights of the application identified by the impersonation data. The nature of the impersonation data depends on the integration in the OS.

Parameters:

aid - The AID to check (between 5 and 16 bytes inclusive). This value should not be null.

impersonationData - The buffer containing the impersonated application data for the authentication. This value should not be null.

Returns:

true if the access is granted, false otherwise.

Throws:

IllegalArgumentException - if aid or impersonationData is null.

Since:

Open NFC 4.3.1