Grabba Driver for Android
Unified driver for Grabba devices on the Android operating system
ValidatedMRZ Class Reference

Description

Class encapsulating validated data read from a machine-readable zone (MRZ)

This class parses and validates data read from an MRZ, and guarantees that any object of this type contains data that is fully conformant with the data formats laid out in ICAO 9303. Refer to MRZ_Format for the list of supported formats and brief details of each one.

Objects of this class are constructed from MRZ_Data objects, which encapsulate raw and unvalidated MRZ data. The constructor determines the format of the MRZ and performs full validation, checking the validity of each field and verifying each check digit against the associated source data.

Invariant
All fields are fully valid to the full extent defined by ICAO 9303 for the format in question. Successful construction also strongly implies (although does not 100% guarantee) that the MRZ reader correctly identified all characters in the MRZ.

Thread safety: This class is immutable, and therefore fully thread-safe.

Public Member Functions

 ValidatedMRZ (@NonNull MRZ_Data rawData)
 Construction - takes raw MRZ data and attempts to validate it. More...
 
String dateOfBirth ()
 Obtain the bearer's date of birth field for the MRZ. More...
 
String documentCode ()
 Obtain the document code for the MRZ. More...
 
String documentNumber (boolean convertFiller)
 Obtain the document number field for the MRZ. More...
 
String expiryDate ()
 Obtain the expiry date field for the MRZ. More...
 
MRZ_Format format ()
 Query the format of the MRZ. More...
 
String gender ()
 Obtain the bearer's gender field for the MRZ. More...
 
String issuerCode ()
 Obtain the issuing state or organisation code for the MRZ. More...
 
String issuerName ()
 Obtain the issuing state or organisation name for the MRZ. More...
 
String nationCode ()
 Obtain the bearer's nation code field for the MRZ. More...
 
String nationName ()
 Obtain the bearer's nation name for the MRZ. More...
 
String optionalData ()
 Obtain the optional data field for the MRZ, if present. More...
 
String primaryName (boolean convertFiller)
 Obtain the primary name field for the MRZ. More...
 
String secondaryName (boolean convertFiller)
 Obtain the secondary name field for the MRZ. More...
 

Static Public Member Functions

static String issuerName (@NonNull String code)
 Obtain the issuer string for a given issuer code. More...
 

Static Public Attributes

static final char Filler
 Filler/delimiter character ('<') defined by ICAO 9303.
 

Constructor & Destructor Documentation

◆ ValidatedMRZ()

ValidatedMRZ ( @NonNull MRZ_Data  rawData)

Construction - takes raw MRZ data and attempts to validate it.

Successful construction implies that all validation checks passed successfully for the format in question.

Parameters
rawDataData received from an MRZ scan
Exceptions
IllegalArgumentExceptionif any of the validation checks failed (e.g. check digit mismatch)

Member Function Documentation

◆ dateOfBirth()

String dateOfBirth ( )

Obtain the bearer's date of birth field for the MRZ.

The MRZ format encodes dates of birth as six-digit strings:

  • The first two digits are the year, modulo 100 - e.g. 1942 is encoded as "42"
  • The next two digits are the month number, range 1-12 - e.g. July is encoded as "07"
  • The final two digits are the day number, range 1-31 - e.g. 2nd is encoded as "02"

If any of the fields are unknown then they may be replaced by Filler characters.

Returns
Date string (6 chars in length)

◆ documentCode()

String documentCode ( )

Obtain the document code for the MRZ.

The document code designates the type of MRZ and, if valid, is either one or two characters in length. It occupies the first two characters of line 1 in all MRZ types.

The first letter of the code is specified as follows:

  • P - passport (type TD3)
  • A, C or I - official travel documents (types TD1 or TD2)
  • V - visa (type MRV-A or MRV-B)

The second letter of the code is optional; if omitted (i.e. replaced by a Filler in the MRZ text) then it will not be included in the output of this function. If present, it must conform to the following:

  • Character must be from the uppercase alphabet
  • If first letter is A, C or I, then second letter must not be V

The second letter of the code is at the discretion of the issuing organisation, and may be omitted (i.e. replaced by a Filler in the MRZ text).

Returns
Document code (1-2 chars in length)

◆ documentNumber()

String documentNumber ( boolean  convertFiller)

Obtain the document number field for the MRZ.

This field encodes a passport number, visa number, or other document number of up to nine digits. Typically it is fully numeric, but alphabetic characters and the Filler character are permitted.

Parameters
convertFillerIf true (recommended), any Filler characters in the field are converted to spaces in the output of this function; if false, they are left as-is
Returns
Document number (up to 9 characters in length)

◆ expiryDate()

String expiryDate ( )

Obtain the expiry date field for the MRZ.

The MRZ format encodes dates of birth as six-digit strings:

  • The first two digits are the year, modulo 100 - e.g. 1942 is encoded as "42"
  • The next two digits are the month number, range 1-12 - e.g. July is encoded as "07"
  • The final two digits are the day number, range 1-31 - e.g. 2nd is encoded as "02"

If any of the fields are unknown then they may be replaced by Filler characters.

Returns
Date string (6 chars in length)

◆ format()

MRZ_Format format ( )

Query the format of the MRZ.

Returns
MRZ format, guaranteed to be one of the five defined in ICAO 9303 (i.e. not UNKNOWN)

◆ gender()

String gender ( )

Obtain the bearer's gender field for the MRZ.

Three values are considered valid for this field - 'F' for female, 'M' for male, and Filler for unspecified gender.

Returns
Gender string (1 character in length)

◆ issuerCode()

String issuerCode ( )

Obtain the issuing state or organisation code for the MRZ.

The issuing state or organisation is encoded as a three-letter code in the MRZ according to the rules specified in ICAO 9303 part 3 section 5. It occupies characters 3 to 5 of line 1 in all MRZ types.

No validity checks are performed on this code beyond ensuring that either it consists of 1-3 uppercase characters followed by 0-2 Filler characters, with an overall length of 3. That is, even if the code does not match a value defined by ICAO 9303, it will still be accepted if it meets that basic format.

Returns
Issuer code (3 chars in length) if this MRZ is of one of the known formats and contains a code which meets basic formatting checks, otherwise an empty string. Any trailing Filler characters will be retained, e.g. code for Germany will be "D<<".
See also
issuerString() for a human-readable equivalent

◆ issuerName() [1/2]

String issuerName ( )

Obtain the issuing state or organisation name for the MRZ.

This is the equivalent to issuerCode(), except a human-readable string is returned rather than a three-digit code - e.g. if issuerCode() would return "AUS", this function would return "Australia".

If there is no valid code, or the code provided is not listed in ICAO 9303 part 3 section 5, then an empty string will be returned.

Returns
Human-readable name of this MRZ's issuer if known and valid, otherwise an empty string

◆ issuerName() [2/2]

static String issuerName ( @NonNull String  code)
static

Obtain the issuer string for a given issuer code.

This function returns the name of an issuer given by the supplied code. The names and codes are defined in ICAO 9303 part 3 section 5.

It may also be used to generate strings for nationality codes, as those are a subset of the issuer codes.

Parameters
codeIssuer code; must be a three-character uppercase string matching one of the values defined by ICAO 9303 part 3 section 5
Returns
Human-readable name of given issuer code if known and valid, otherwise the string "Unknown"

◆ nationCode()

String nationCode ( )

Obtain the bearer's nation code field for the MRZ.

The bearer's nationality is encoded as a three-letter code in the MRZ according to the rules specified in ICAO 9303 part 3 section 5.

No validity checks are performed on this code beyond ensuring that either it consists of 1-3 uppercase characters followed by 0-2 Filler characters, with an overall length of 3. That is, even if the code does not match a value defined by ICAO 9303, it will still be accepted if it meets that basic format.

Returns
Nation code (3 chars in length). Any trailing Filler characters will be retained, e.g. code for Germany will be "D<<".
See also
nationName() for a human-readable equivalent, or issuerString(const string&) for a function which converts these codes (which are a subset of the issuer codes) to human-readable strings.

◆ nationName()

String nationName ( )

Obtain the bearer's nation name for the MRZ.

This is the equivalent to NationCode(), except a human-readable string is returned rather than a three-digit code - e.g. if NationCode() would return "AUS", this function would return "Australia".

If there is no valid code, or the code provided is not listed in ICAO 9303 part 3 section 5, then an empty string will be returned.

Returns
Human-readable name of this MRZ bearer's nation

◆ optionalData()

String optionalData ( )

Obtain the optional data field for the MRZ, if present.

On passports (TD3 format) this is typically used to store a personal number given to the bearer by the issuing state or organisation. On all formats it may be used to store other optional data at the discretion of this organisation.

There are no restrictions on the format of this data aside from the basic character set requirements of all MRZ data. Consequently, it is not validated beyond those basic checks.

On the TD1 format the content of this field is split across two separate lines; the output of this function takes the field contents from the first line (excluding trailing check digit) and appends the field contents from the second line to it. Other formats hold the entirety of this field in a single location.

Returns
Optional data field (variable length depending on format)

◆ primaryName()

String primaryName ( boolean  convertFiller)

Obtain the primary name field for the MRZ.

The primary name is typically a bearer's surname (family name), and forms part of the name field along with the secondary name field (see secondaryName()).

The primary name field must start with an uppercase alphabetic character. It may then be followed by any number of additional characters which may be either uppercase alphabetic characters or Filler characters, subject to the restriction that no two Filler characters may be directly adjacent.

Parameters
convertFillerIf true (recommended), any Filler characters in the name are converted to spaces in the output of this function; if false, they are left as-is
Returns
Primary name (1-39 chars in length)

◆ secondaryName()

String secondaryName ( boolean  convertFiller)

Obtain the secondary name field for the MRZ.

The secondary name typically contains a bearer's given name(s), and forms part of the name field along with the primary name field (see primaryName()).

The secondary name field may be an empty string, implying the user has only one name (which is primary). If non-empty, it must follow the same rules as the primary name.

Parameters
convertFillerIf true (recommended), any Filler characters in the name are converted to spaces in the output of this function; if false, they are left as-is
Returns
Secondary name (0-36 chars in length)