Class: GS1encoder

Get/set the "add check digit" mode for EAN/UPC and GS1 DataBar symbols.

If false (default), then the data string must contain a valid check digit. If true, then the data string must not contain a check digit as one will be generated automatically.

This option is only valid for symbologies that accept fixed-length data, specifically EAN/UPC and GS1 DataBar except Expanded (Stacked).

Get/set the barcode data input buffer using GS1 Application Identifier syntax.

The input is provided in human-friendly format without FNC1 characters which are inserted automatically, for example:

(01)12345678901231(10)ABC123(11)210630

This syntax harmonises the format for the input accepted by all symbologies. For example, the following input is acceptable for EAN-13, UPC-A, UPC-E, any variant of the GS1 DataBar family, GS1 QR Code and GS1 DataMatrix:

(01)00031234000054

The input is immediately parsed and validated against certain rules for GS1 AIs, after which the resulting encoding for valid inputs is available via GS1encoder#dataStr. If the input is invalid then an exception will be thrown.

Any "(" characters in AI element values must be escaped as "\\(" to avoid conflating them with the start of the next AI.

For symbologies that support a composite component (all except Data Matrix, QR Code, and DotCode), the data for the linear and 2D components can be separated by a "|" character, for example:

(01)12345678901231|(10)ABC123(11)210630

Get/set the raw data that would be directly encoded within a GS1 barcode message.

A "^" character at the start of the input indicates that the data is in GS1 Application Identifier syntax. In this case, all subsequent instances of the "^" character represent the FNC1 non-data characters that are used to separate fields that are not specified as being pre-defined length from subsequent fields.

Inputs beginning with "^" will be validated against certain data syntax rules for GS1 AIs. If the input is invalid then the setter will throw a GS1encoderParameterException. In the case that the data is unacceptable due to invalid AI content then a marked up version of the offending AI can be retrieved using GS1encoder#errMarkup.

Note: It is strongly advised that GS1 data input is instead specified using GS1encoder#aiDataStr which takes care of the AI encoding rules automatically, including insertion of FNC1 characters where required. This can be used for all symbologies that accept GS1 AI syntax data.

Inputs beginning with "http://" or "https://" will be parsed as a GS1 Digital Link URI during which the corresponding AI element string is extracted and validated.

EAN/UPC, GS1 DataBar and GS1-128 support a Composite Component. The Composite Component must be specified in AI syntax. It must be separated from the primary linear components with a "|" character and begin with an FNC1 in first position, for example:

encoder.dataStr = "^0112345678901231|^10ABC123^11210630";

The above specifies a linear component representing "(01)12345678901231" together with a composite component representing "(10)ABC123(11)210630".

Note: For GS1 data it is simpler and less error prone to specify the input in human-friendly GS1 AI syntax using GS1encoder#aiDataStr.

Get the non-numeric (ignored) query parameters from a GS1 Digital Link URI.

For example, if the input data buffer contains:

https://a/01/12312312312333/22/ABC?name=Donald%2dDuck&99=ABC&testing&type=cartoon

Then this property returns: name=Donald%2dDuck, testing, type=cartoon

The returned strings are not URI decoded. The expected use for this property is to present which sections of a given GS1 Digital Link URI have been ignored.

Get the error markup generated when parsing AI data fails due to a linting failure.

When a setter function returns false (indicating an error), if that failure is due to AI-based data being invalid, a marked up instance of the AI that failed will be generated.

Where it is meaningful to identify offending characters in the input data, these characters will be surrounded by "|" characters. Otherwise the entire AI value will be surrounded by "|" characters.

Get the Human-Readable Interpretation ("HRI") text for the current data input buffer.

For composite symbols, a separator "--" will be included in the array to distinguish between the linear and 2D components.

Example output for ^011231231231233310ABC123|^99XYZ(TM) CORP:

(01) 12312312312333
(10) ABC123
--
(99) XYZ(TM) CORP

Get/set the "include data titles in HRI" flag.

When set to true, data titles from the GS1 General Specification will be included in the HRI text.

Default: false

Get/set the "permit unknown AIs" mode.

If false (default), then all AIs represented by the input data must be known.

If true, then unknown AIs (those not in this library's static AI table) will be accepted.

Note: The option only applies to parsed input data, specifically bracketed AI data supplied with GS1encoder#aiDataStr and GS1 Digital Link URIs supplied with GS1encoder#dataStr. Unbracketed AI element strings containing unknown AIs cannot be parsed because it is not possible to differentiate the AI from its data value when the length of the AI is uncertain.

Default: false

Get/set the "permit zero-suppressed GTIN in GS1 DL URIs" mode.

If false (default), then the value of a path component for AI (01) must be provided as a full GTIN-14.

If true, then the value of a path component for AI (01) may contain the GTIN-14 with zeros suppressed, in the format of a GTIN-13, GTIN-12 or GTIN-8.

This option only applies to parsed input data, specifically GS1 Digital Link URIs. Since zero-suppressed GTINs are deprecated, this option should only be enabled when it is necessary to accept legacy GS1 Digital Link URIs having zero-suppressed GTIN-14.

Default: false

Process scan data received from a barcode reader or return the expected scan data string.

Setting: Process normalised scan data received from a barcode reader with reporting of AIM symbology identifiers enabled to extract the message data and perform syntax checks in the case of GS1 Digital Link and AI data input.

This function will process scan data (such as the output of a barcode reader) and process the received data, setting the data input buffer to the message received and setting the selected symbology to something that is able to carry the received data.

Note: In some instances the symbology determined by this library will not match that of the image that was scanned. The AIM symbology identifier prefix of the scan data does not always uniquely identify the symbology that was scanned. For example GS1-128 Composite symbols share the same symbology identifier as the GS1 DataBar family, and will therefore be detected as such.

A literal "|" character may be included in the scan data to indicate the separation between the first and second messages that would be transmitted by a reader that is configured to return the composite component when reading EAN/UPC symbols.

Example scan data input:

]C1011231231231233310ABC123{GS}99TESTING

where {GS} represents ASCII character 29.

Getting: Returns the string that should be returned by scanners when reading a symbol that is an instance of the selected symbology and contains the same input data.

The output will be prefixed with the appropriate AIM symbology identifier.

Get/set the symbology type.

This might be set manually or automatically when processing scan data with GS1encoder#scanData.

Get/set the "validate AI associations" flag.

Deprecated: Use GS1encoder#getValidationEnabled and GS1encoder#setValidationEnabled instead.

This property is equivalent to using the GS1encoder#getValidationEnabled and GS1encoder#setValidationEnabled methods with the RequisiteAIs validation procedure.

Get the version string of the library.

Returns a string containing the version of the library, typically the build date.

Recognised GS1 barcode formats ("symbologies") for processing scan data.

This object defines all supported GS1 barcode symbology types that can be used with the encoder. Each symbology has specific characteristics and use cases.

Optional AI validation procedures that may be applied to detect invalid inputs.

These validation procedures are applied when AI data is provided using GS1encoder#aiDataStr, GS1encoder#dataStr or GS1encoder#scanData.

Only AI validation procedures whose "enabled" status can be updated (i.e. not "locked") are described.

Get a GS1 Digital Link URI that represents the AI-based input data.

This method converts AI-based input data into a GS1 Digital Link URI format.

Example:

(01)12345678901231(10)ABC123(11)210630

with stem https://id.example.com/stem might produce:

https://id.example.com/stem/01/12345678901231?10=ABC123&11=210630

Get the current enabled status of the provided AI validation procedure.

Initialises a new instance of the GS1Encoder.

Enable or disable the given AI validation procedure.

This determines whether certain checks are enforced when data is provided using GS1encoder#aiDataStr, GS1encoder#dataStr or GS1encoder#scanData.

If enabled is true (default), then the corresponding validation will be enforced. If enabled is false, then the corresponding validation will not be enforced.

Note: The option only applies to AI input data.