BioTemplate (Java Card API, Connected Edition)
Date: 2009-12-11

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

## javacardx.biometry
Interface BioTemplate

All Known Subinterfaces:
  OwnerBioTemplate, SharedBioTemplate, SharedBioTemplateAuth

    @TransactionType(value=NOT_SUPPORTED)
    @SensitiveType(sensitivity=FULL)
    public interface BioTemplate

The BioTemplate interface is the base interface for all biometric templates. It provides the user interface for accessing biometric functionality.

Since:
  2.2.2

Field Summary
`static short` | `MATCH_NEEDS_MORE_DATA` This negative score value indicates that more data are needed to continue the matching session.
`static short` | `MINIMUM_SUCCESSFUL_MATCH_SCORE` The minimum successful matching score.

Method Summary
`byte` | `getBioType()` Get the biometric type.
`short` | `getPublicTemplateData(short publicOffset, byte[] dest, short destOffset, short length)` Get public part of the reference template.
`byte` | `getTriesRemaining()` Returns the number of times remaining that an incorrect candidate template can be presented before the reference template is blocked.
`short` | `getVersion(byte[] dest, short offset)` Get the matching algorithm version and ID.
`short` | `initMatch(byte[] candidate, short offset, short length)` Initialize or re-initialize a biometric matching session.
`boolean` | `isInitialized()` Returns true if the reference template is completely loaded and ready for matching functions.
`boolean` | `isValidated()` Returns true if the template has been successfully checked since the last card reset or last call to `reset()`.
`short` | `match(byte[] candidate, short offset, short length)` Continues a biometric matching session.
`void` | `reset()` Resets the validated flag associated with the reference template.

Field Detail

### MINIMUM_SUCCESSFUL_MATCH_SCORE

    static final short MINIMUM_SUCCESSFUL_MATCH_SCORE

  The minimum successful matching score.

  See Also:
    Constant Field Values

### MATCH_NEEDS_MORE_DATA

    static final short MATCH_NEEDS_MORE_DATA

  This negative score value indicates that more data are needed to continue the matching session.

  See Also:
    Constant Field Values

Method Detail

### isInitialized

    boolean isInitialized()

  Returns true if the reference template is completely loaded and ready for matching functions. This is independent of whether or not the match process has been initialized (see `initMatch`).

  Returns:
    true if initialized, false otherwise.

### isValidated

    boolean isValidated()

  Returns true if the template has been successfully checked since the last card reset or last call to `reset()`.

  Returns:
    true if validated, false otherwise.

### reset

    void reset()

  Resets the validated flag associated with the reference template. This could be appropriate as a last action after an access is completed.

### getTriesRemaining

    byte getTriesRemaining()

  Returns the number of times remaining that an incorrect candidate template can be presented before the reference template is blocked.

  Returns:
    the number of tries remaining
  Throws:
    `BioException` - with the following reason codes:
    - `BioException.NO_TEMPLATES_ENROLLED` if the reference template is uninitialized.

### getBioType

    byte getBioType()

  Get the biometric type. Valid type are described in `BioBuilder`.

  Returns:
    biometric general type.

### getVersion

    short getVersion(byte[] dest,
                     short offset)

  Get the matching algorithm version and ID.

  Parameters:
    `dest` - destination byte array.
    `offset` - starting offset within the destination byte array.
  Returns:
    number of bytes written in the destination byte array.

### getPublicTemplateData

    short getPublicTemplateData(short publicOffset,
                                byte[] dest,
                                short destOffset,
                                short length)
                                throws BioException

  Get public part of the reference template. This method copies all or a portion of the reference public data to the destination array.

  Parameters:
    `publicOffset` - starting offset within the public data.
    `dest` - destination byte array.
    `destOffset` - starting offset within the destination byte array.
    `length` - maximum length in bytes of the requested data.
  Returns:
    number of bytes written to the destination byte array. 0 if public data are not available.
  Throws:
    `BioException` - with the following reason codes:
    - `BioException.NO_TEMPLATES_ENROLLED` if the reference template is uninitialized.

### initMatch

    short initMatch(byte[] candidate,
                    short offset,
                    short length)
                    throws BioException

  Initialize or re-initialize a biometric matching session. The exact return score value is implementation dependent and can be used, for example, to code a confidence rate. If the reference is not blocked, a matching session starts and, before any other processing, the validated flag is reset and the try counter is decremented if the try counter has reached zero, the reference is blocked. This method results in one of the following:
  - The matching session ends with success state if the templates match. The validated flag is set and the try counter is reset to its maximum.
  - The matching session ends with failed state if the templates don't match.
  - The matching session continues if the matching needs more data. The `match` method has to be called to continue the matching session.

  If the reference is blocked, no matching session starts and this method returns 0. Notes:

  - A correct matching sequence is : `initMatch`,[`match`]. Calling `initMatch` is mandatory, calling `match` is optional.
  - If a matching session is in progress (case needs more data), a call to `initMatch` makes the current session to fail and starts a new matching session.
  - Even if a transaction is in progress, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated.

  Parameters:
    `candidate` - - the data or part of the data of the candidate template.
    `offset` - - starting offset into the candidate array where the candidate data is to be found.
    `length` - - number of bytes to be taken from the candidate array.
  Returns:
    the matching score with the following meaning :
    - >= MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session is successful
    - >= 0 and < MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session has failed
    - = MATCH_NEEDS_MORE_DATA : the matching session needs more data
  Throws:
    `BioException` - with the following reason codes:
    - `BioException.INVALID_DATA` if the submitted candidate template data does not have the required format.
    - `BioException.NO_TEMPLATES_ENROLLED` if the reference template is uninitialized.

### match

    short match(byte[] candidate,
                short offset,
                short length)
                throws BioException

  Continues a biometric matching session. The exact return score value is implementation dependent and can be used, for example, to code a confidence rate. If a matching session is in progress, this method results in one of the following:
  - The matching session ends with success state if the templates match. The validated flag is set and the try counter is reset to its maximum.
  - The matching session ends with failed state if the templates don't match.
  - The matching session continues if the matching needs more data. The `match` method has to be called to continue the matching session.
  Notes:
  - A correct matching sequence is : `initMatch`,[`match`]. Calling `initMatch` is mandatory, calling `match` is optional.
  - Even if a transaction is in progress, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated.

  Parameters:
    `candidate` - - the data or part of the data of the candidate template.
    `offset` - - starting offset into the candidate array where the candidate data is to be found.
    `length` - - number of bytes to be taken from the candidate array.
  Returns:
    the matching score with the following meaning :
    - >= MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session is successful
    - >= 0 and < MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session has failed
    - = MATCH_NEEDS_MORE_DATA : the matching session needs more data
  Throws:
    `BioException` - with the following reason codes:
    - `BioException.ILLEGAL_USE` if used outside a matching session.
    - `BioException.INVALID_DATA` if the submitted candidate template data does not have the required format.
    - `BioException.NO_TEMPLATES_ENROLLED` if the reference template is uninitialized.

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

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.