Class GS1Encoder

Main class for processing GS1 barcode data, including validation, format conversion, and generation of outputs such as GS1 Digital Link URIs and Human-Readable Interpretation text.

Inheritance
object
GS1Encoder
Inherited Members
Namespace: GS1.Encoders
Assembly: .dll
Syntax
public class GS1Encoder

Constructors

GS1Encoder()

Initialises a new instance of the GS1Encoder class.

Declaration
public GS1Encoder()
Exceptions
Type Condition
GS1EncoderGeneralException

Thrown when the library fails to initialise

Properties

AIdataStr

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

Declaration
public string AIdataStr { get; set; }
Property Value
Type Description
string

The barcode data in human-friendly GS1 AI syntax, or null if the input data does not contain AI data.
Remarks

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 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

AddCheckDigit

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

Declaration
public bool AddCheckDigit { get; set; }
Property Value
Type Description
bool

true if check digits will be generated automatically; false if the data must include a valid check digit.
Remarks

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).

Exceptions
Type Condition
GS1EncoderParameterException

Thrown when the setter is provided with an invalid value.

DLignoredQueryParams

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

Declaration
public string[] DLignoredQueryParams { get; }
Property Value
Type Description
string[]

An array of strings containing the non-numeric query parameters that were ignored when processing a GS1 Digital Link URI.
Remarks

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.

DataStr

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

Declaration
public string DataStr { get; set; }
Property Value
Type Description
string

The raw barcode data input buffer.
Remarks

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 this 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 ErrMarkup.

Note: It is strongly advised that GS1 data input is instead specified using 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 AIdataStr.

Exceptions
Type Condition
GS1EncoderParameterException

Thrown when the setter is provided with invalid data.
See Also

ErrMarkup

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

Declaration
public string ErrMarkup { get; }
Property Value
Type Description
string

Marked up instance of the AI that failed validation, or empty string if no linting failure.
Remarks

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.

HRI

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

Declaration
public string[] HRI { get; }
Property Value
Type Description
string[]

An array of null-terminated strings representing the HRI text.
Remarks

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

IncludeDataTitlesInHRI

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

Declaration
public bool IncludeDataTitlesInHRI { get; set; }
Property Value
Type Description
bool

true if data titles should be included in HRI; otherwise false.
Remarks

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

Default: false

PermitUnknownAIs

Get/set the "permit unknown AIs" mode.

Declaration
public bool PermitUnknownAIs { get; set; }
Property Value
Type Description
bool

true if unknown AIs are permitted; otherwise false.
Remarks

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 AIdataStr and GS1 Digital Link URIs supplied with 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

PermitZeroSuppressedGTINinDLuris

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

Declaration
public bool PermitZeroSuppressedGTINinDLuris { get; set; }
Property Value
Type Description
bool

true if zero-suppressed GTINs are permitted in GS1 Digital Link URIs; otherwise false.
Remarks

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

ScanData

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

Declaration
public string ScanData { get; set; }
Property Value
Type Description
string

The scan data string that a reader should return when scanning the current data, or null if invalid.
Remarks

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.

Sym

Get/set the symbology type.

Declaration
public GS1Encoder.Symbology Sym { get; set; }
Property Value
Type Description
GS1Encoder.Symbology

The current symbology type.
Remarks

This might be set manually or automatically when processing scan data with ScanData.

Exceptions
Type Condition
GS1EncoderParameterException

Thrown when the setter is provided with an invalid symbology type.
See Also

ValidateAIassociations

Get/set the "validate AI associations" flag.

Declaration
[Obsolete]
public bool ValidateAIassociations { get; set; }
Property Value
Type Description
bool

true if the RequisiteAIs validation procedure is enabled; otherwise false.
Remarks

Deprecated: Use SetValidationEnabled(Validation, bool) and GetValidationEnabled(Validation) instead.

This property is equivalent to using the GetValidationEnabled(Validation) and SetValidationEnabled(Validation, bool) methods with the RequisiteAIs validation procedure.

Version

Get the version string of the library.

Declaration
public string Version { get; }
Property Value
Type Description
string

A string containing the version of the library, typically the build date.

Methods

GetDLuri(string)

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

Declaration
public string GetDLuri(string Stem)
Parameters
Type Name Description
string Stem

A URI "stem" used as a prefix for the URI. If null, the GS1 canonical stem (https://id.gs1.org/) will be used.
Returns
Type Description
string

A string representing the GS1 Digital Link URI for the input data
Remarks

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

Exceptions
Type Condition
GS1EncoderDigitalLinkException

Thrown when invalid input was provided

GetValidationEnabled(Validation)

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

Declaration
public bool GetValidationEnabled(GS1Encoder.Validation validation)
Parameters
Type Name Description
GS1Encoder.Validation validation

A validation procedure to check the status of
Returns
Type Description
bool

true if the AI validation procedure is currently enabled; false otherwise

SetValidationEnabled(Validation, bool)

Enable or disable the given AI validation procedure.

Declaration
public void SetValidationEnabled(GS1Encoder.Validation validation, bool enabled)
Parameters
Type Name Description
GS1Encoder.Validation validation

A validation procedure to set the enabled status of
bool enabled

true to enable the validation; false to disable
Remarks

This determines whether certain checks are enforced when data is provided using AIdataStr, DataStr or 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.