Introduction

GS1 Barcode Syntax Engine

Author: GS1 AISBL

Copyright: Copyright (c) 2000-2026 GS1 AISBL.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Public C API header for the GS1 Barcode Syntax Engine. For an overview, examples and usage instructions, see the main documentation page. C++ users may prefer the RAII C++ wrapper in gs1encoders.hpp; see the C++ API topic.

This graph shows which files directly or indirectly include this file:

Data Structures
struct	gs1_encoder_init_opts
	Initialisation options structure for gs1_encoder_init_ex(). More...

Macros
#define	GS1_ENCODERS_API

#define	GS1_ENCODERS_DEPRECATED

#define	GS1_ENCODERS_DEPRECATED_ENUM = 1 << 3

Typedefs
typedef enum gs1_encoder_symbologies	gs1_encoder_symbologies_t
	Equivalent to the `enum gs1_encoder_symbologies` type.

typedef enum gs1_encoder_validations	gs1_encoder_validations_t
	Equivalent to the `enum gs1_encoder_validations` type.

typedef enum gs1_encoder_init_flags	gs1_encoder_init_flags_t
	Equivalent to the `enum gs1_encoder_init_flags` type.

typedef enum gs1_encoder_init_status	gs1_encoder_init_status_t
	Equivalent to the `enum gs1_encoder_init_status` type.

typedef struct gs1_encoder_init_opts	gs1_encoder_init_opts_t
	Equivalent to the `struct gs1_encoder_init_opts` type.

typedef struct gs1_encoder	gs1_encoder
	A gs1_encoder context.

Enumerations
enum	gs1_encoder_symbologies { gs1_encoder_sNONE = -1 , gs1_encoder_sDataBarOmni , gs1_encoder_sDataBarTruncated , gs1_encoder_sDataBarStacked , gs1_encoder_sDataBarStackedOmni , gs1_encoder_sDataBarLimited , gs1_encoder_sDataBarExpanded , gs1_encoder_sUPCA , gs1_encoder_sUPCE , gs1_encoder_sEAN13 , gs1_encoder_sEAN8 , gs1_encoder_sGS1_128_CCA , gs1_encoder_sGS1_128_CCC , gs1_encoder_sQR , gs1_encoder_sDM , gs1_encoder_sDotCode , gs1_encoder_sNUMSYMS }
	Recognised GS1 barcode formats ("symbologies") for processing scan data. More...

enum	gs1_encoder_validations { gs1_encoder_vMUTEX_AIS = 0 , gs1_encoder_vREQUISITE_AIS , gs1_encoder_vREPEATED_AIS , gs1_encoder_vDIGSIG_SERIAL_KEY , gs1_encoder_vUNKNOWN_AI_NOT_DL_ATTR , gs1_encoder_vNUMVALIDATIONS }

enum	gs1_encoder_init_flags { gs1_encoder_iDEFAULT = 0 , GS1_ENCODERS_DEPRECATED_ENUM = 1 << 0 , gs1_encoder_iNO_EMBEDDED = 1 << 1 , gs1_encoder_iFALLBACK_ON_SYNDICT_ERROR = 1 << 2 , GS1_ENCODERS_DEPRECATED_ENUM = 1 << 0 }
	Initialisation flags for gs1_encoder_init_ex(). More...

enum	gs1_encoder_init_status { GS1_ENCODERS_INIT_SUCCESS = 0 , GS1_ENCODERS_INIT_FALLBACK_TO_EMBEDDED_TABLE = 1 , GS1_ENCODERS_INIT_FAILED_NO_MEM = -1 , GS1_ENCODERS_INIT_FAILED_NO_EMBEDDED_TABLE = -2 , GS1_ENCODERS_INIT_FAILED_LOADING_SYNDICT = -3 , GS1_ENCODERS_INIT_FAILED_AI_TABLE_CORRUPT = -4 }
	Initialisation status codes returned by gs1_encoder_init_ex(). More...

Functions
GS1_ENCODERS_API char *	gs1_encoder_getVersion (void)
	Get the version string of the library.

GS1_ENCODERS_API size_t	gs1_encoder_instanceSize (void)
	Find the memory storage requirements for an instance of gs1_encoder.

GS1_ENCODERS_API int	gs1_encoder_getMaxDataStrLength (void)
	Get the maximum size of the input data buffer for barcode message content.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED gs1_encoder *	gs1_encoder_init (void *mem)
	Initialise a new gs1_encoder context.

GS1_ENCODERS_API gs1_encoder *	gs1_encoder_init_ex (void mem, const gs1_encoder_init_opts_t opts)
	Initialise a new gs1_encoder context with the extended interface.

GS1_ENCODERS_API char *	gs1_encoder_getErrMsg (gs1_encoder *ctx)
	Read an error message generated by the library.

GS1_ENCODERS_API char *	gs1_encoder_getErrMarkup (gs1_encoder *ctx)
	Read the error markup generated when parsing AI data fails due to a linting failure.

GS1_ENCODERS_API gs1_encoder_symbologies_t	gs1_encoder_getSym (gs1_encoder *ctx)
	Get the current symbology type.

GS1_ENCODERS_API bool	gs1_encoder_setSym (gs1_encoder *ctx, gs1_encoder_symbologies_t sym)
	Set the symbology type.

GS1_ENCODERS_API bool	gs1_encoder_getAddCheckDigit (gs1_encoder *ctx)
	Get the current status of the "add check digit" mode.

GS1_ENCODERS_API bool	gs1_encoder_setAddCheckDigit (gs1_encoder *ctx, bool addCheckDigit)
	Enable or disable "add check digit" mode for EAN/UPC and GS1 DataBar symbols.

GS1_ENCODERS_API bool	gs1_encoder_getPermitUnknownAIs (gs1_encoder *ctx)
	Get the current status of the "permit unknown AIs" mode.

GS1_ENCODERS_API bool	gs1_encoder_setPermitUnknownAIs (gs1_encoder *ctx, bool permitUnknownAIs)
	Enable or disable "permit unknown AIs" mode for parsing of bracketed AI element strings and GS1 Digital Link URIs.

GS1_ENCODERS_API bool	gs1_encoder_getPermitZeroSuppressedGTINinDLuris (gs1_encoder *ctx)
	Get the current status of the "permit zero-suppressed GTIN in GS1 DL URIs" mode.

GS1_ENCODERS_API bool	gs1_encoder_setPermitZeroSuppressedGTINinDLuris (gs1_encoder *ctx, bool permitZeroSuppressedGTINinDLuris)
	Enable or disable "permit zero-suppressed GTIN in GS1 DL URIs" mode for parsing of GS1 Digital Link URIs.

GS1_ENCODERS_API bool	gs1_encoder_getIncludeDataTitlesInHRI (gs1_encoder *ctx)
	Get the current status of the "include data titles in HRI" flag.

GS1_ENCODERS_API bool	gs1_encoder_setIncludeDataTitlesInHRI (gs1_encoder *ctx, bool includeDataTitles)
	Enable or disable "include data titles in HRI" flag.

GS1_ENCODERS_API bool	gs1_encoder_getValidationEnabled (gs1_encoder *ctx, gs1_encoder_validations_t validation)
	Get the current enabled status of the provided AI validation procedure.

GS1_ENCODERS_API bool	gs1_encoder_setValidationEnabled (gs1_encoder *ctx, gs1_encoder_validations_t validation, bool enabled)
	Enable or disable the given AI validation procedure of type gs1_encoder_validations, that determines whether certain checks are enforced when data is provided using gs1_encoder_setAIdataStr(), gs1_encoder_setDataStr() or gs1_encoder_setScanData().

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED bool	gs1_encoder_getValidateAIassociations (gs1_encoder *ctx)
	Provided for backwards compatibility to get the current enabled status of the gs1_encoder_vREQUISITE_AIS validation procedure.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED bool	gs1_encoder_setValidateAIassociations (gs1_encoder *ctx, bool validateAIassociations)
	Provided for backwards compatibility to enable or disable the gs1_encoder_vREQUISITE_AIS validation procedure, that determines whether mandatory AI pairings are enforced when data is provided using gs1_encoder_setAIdataStr(), gs1_encoder_setDataStr() or gs1_encoder_setScanData().

GS1_ENCODERS_API char *	gs1_encoder_getDataStr (gs1_encoder *ctx)
	Reads the raw barcode data input buffer.

GS1_ENCODERS_API bool	gs1_encoder_setDataStr (gs1_encoder ctx, const char dataStr)
	Sets the raw data that would be directly encoded within a GS1 barcode message.

GS1_ENCODERS_API bool	gs1_encoder_setAIdataStr (gs1_encoder ctx, const char dataStr)
	Sets the data in the buffer that is used when buffer input is selected by parsing input provided in GS1 Application Identifier syntax into a raw data string.

GS1_ENCODERS_API char *	gs1_encoder_getAIdataStr (gs1_encoder *ctx)
	Return the barcode input data buffer in human-friendly AI syntax.

GS1_ENCODERS_API char *	gs1_encoder_getDLuri (gs1_encoder ctx, const char stem)
	Returns a GS1 Digital Link URI representing AI-based input data.

GS1_ENCODERS_API bool	gs1_encoder_setScanData (gs1_encoder ctx, const char scanData)
	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.

GS1_ENCODERS_API char *	gs1_encoder_getScanData (gs1_encoder *ctx)
	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.

GS1_ENCODERS_API int	gs1_encoder_getHRI (gs1_encoder ctx, char **hri)
	Update a given pointer towards an array of strings containing Human-Readable Interpretation ("HRI") text.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED size_t	gs1_encoder_getHRIsize (gs1_encoder *ctx)
	Get the require HRI buffer size.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED void	gs1_encoder_copyHRI (gs1_encoder ctx, void buf, size_t max)
	Copy the HRI to a user-provided buffer in the form of a "\|"-separated string.

GS1_ENCODERS_API int	gs1_encoder_getDLignoredQueryParams (gs1_encoder ctx, char **qp)
	Update a given pointer towards an array of strings containing the non-numeric (ignored) query parameters in a provided GS1 Digital Link URI.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED size_t	gs1_encoder_getDLignoredQueryParamsSize (gs1_encoder *ctx)
	Get the require buffer size for ignored GS1 Digital Link query parameters.

GS1_ENCODERS_API GS1_ENCODERS_DEPRECATED void	gs1_encoder_copyDLignoredQueryParams (gs1_encoder ctx, void buf, size_t max)
	Copy the non-numeric (ignored) GS1 Digital Link query parameters to a user-provided buffer in the form of a "&"-separated string.

GS1_ENCODERS_API void	gs1_encoder_free (gs1_encoder *ctx)
	Destroy a gs1_encoder instance.

Introduction

Data Structures

Macros

Typedefs

Enumerations

Functions