 |
Grabba Driver for iOS
Unified driver for Grabba devices on the iOS operating system
|
|
|
Grabba Driver for iOS
Unified driver for Grabba devices on the iOS operating system
|
|
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 GrabbaMRZ_Format for the list of supported formats and brief details of each one.
Objects of this class are constructed from GrabbaMRZ_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.
Thread safety: Objects of this class are immutable, and thus fully thread-safe, post-init.
Instance Methods | |
| (NSString *_Nonnull) | - documentNumberWithFillerConversion: |
| Obtain the document number field for the MRZ. More... | |
| (instancetype _Nullable) | - init |
Not callable (NS_UNAVAILABLE) - use initWithData instead. More... | |
| (instancetype _Nullable) | - initWithData: |
| Initialisation - takes raw MRZ data and attempts to validate it. More... | |
| (NSString *_Nonnull) | - primaryNameWithFillerConversion: |
| Obtain the primary name field for the MRZ. More... | |
| (NSString *_Nonnull) | - secondaryNameWithFillerConversion: |
| Obtain the secondary name field for the MRZ. More... | |
Class Methods | |
| (char) | + filler |
| Filler/delimiter character ('<') defined by ICAO 9303. More... | |
| (NSString *_Nonnull) | + issuerNameForCode: |
| Obtain the issuer string for a given issuer code. More... | |
| (instancetype _Nullable) | + validatedWithData: |
| Allocation and initialisation - takes raw MRZ data and attempts to validate it. More... | |
Properties | |
| NSString *_Nonnull | dateOfBirth |
| Bearer's date of birth field for the MRZ. More... | |
| NSString *_Nonnull | documentCode |
| Document code for the MRZ. More... | |
| NSString *_Nonnull | expiryDate |
| Expiry date field for the MRZ. More... | |
| GrabbaMRZ_Format | format |
| Format of the MRZ. More... | |
| NSString *_Nonnull | gender |
| Bearer's gender field for the MRZ. More... | |
| NSString *_Nonnull | issuerCode |
| Issuing state or organisation code for the MRZ. More... | |
| NSString *_Nonnull | issuerName |
| Issuing state or organisation name for the MRZ. More... | |
| NSString *_Nonnull | nationCode |
| Bearer's nation code field for the MRZ. More... | |
| NSString *_Nonnull | nationName |
| Bearer's nation name for the MRZ. More... | |
| NSString *_Nonnull | optionalData |
| Optional data field for the MRZ. More... | |
| - (NSString* _Nonnull) documentNumberWithFillerConversion: | (BOOL) | 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.
| convertFiller | If YES (recommended), any filler characters in the field are converted to spaces in the output of this function; if NO, they are left as-is |
| + (char) filler |
Filler/delimiter character ('<') defined by ICAO 9303.
| - (instancetype _Nullable) init |
Not callable (NS_UNAVAILABLE) - use initWithData instead.
| - (instancetype _Nullable) initWithData: | (GrabbaMRZ_Data *_Nonnull) | data |
Initialisation - takes raw MRZ data and attempts to validate it.
Successful construction implies that all validation checks passed successfully for the format in question.
| data | Data received from an MRZ scan |
nil if either failed | + (NSString* _Nonnull) issuerNameForCode: | (NSString *_Nonnull) | code |
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.
| code | Issuer code; must be a three-character uppercase string matching one of the values defined by ICAO 9303 part 3 section 5 |
| - (NSString* _Nonnull) primaryNameWithFillerConversion: | (BOOL) | 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.
| convertFiller | If YES (recommended), any filler characters in the name are converted to spaces in the output of this function; if NO, they are left as-is |
| - (NSString* _Nonnull) secondaryNameWithFillerConversion: | (BOOL) | 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.
| convertFiller | If YES (recommended), any filler characters in the name are converted to spaces in the output of this function; if NO, they are left as-is |
| + (instancetype _Nullable) validatedWithData: | (GrabbaMRZ_Data *_Nonnull) | data |
Allocation and initialisation - takes raw MRZ data and attempts to validate it.
Successful construction implies that all validation checks passed successfully for the format in question.
| data | Data received from an MRZ scan |
nil if either failed
|
readnonatomiccopy |
Bearer's date of birth field for the MRZ.
The MRZ format encodes dates of birth as six-digit strings:
If any of the fields are unknown then they may be replaced by filler characters.
|
readnonatomiccopy |
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:
A, C or I, then second letter must not be VThe 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).
|
readnonatomiccopy |
Expiry date field for the MRZ.
The MRZ format encodes dates of birth as six-digit strings:
If any of the fields are unknown then they may be replaced by filler characters.
|
readnonatomicassign |
Format of the MRZ.
This is guaranteed to be one of the five formats defined in ICAO 9303 (i.e. not GrabbaMRZ_FormatUnknown).
|
readnonatomiccopy |
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.
|
readnonatomiccopy |
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.
|
readnonatomiccopy |
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 holds the value "AUS", this property would hold the value "Australia".
If the code for this MRZ is not listed in ICAO 9303 part 3 section 5, then this property will hold an empty string.
|
readnonatomiccopy |
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.
|
readnonatomiccopy |
Bearer's nation name for the MRZ.
This is the equivalent to nationCode, except a human-readable string is held rather than a three-digit code - e.g. if nationCode holds "AUS", this property would hold "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.
|
readnonatomiccopy |
Optional data field for the MRZ.
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 concatenates both sides into a single result string. Other formats hold the entirety of this field in a single place.
1.8.13