GS1 Syntax Dictionary: Linter reference
A reference to the AI component linter routines referred to by the GS1 Syntax Dictionary. Copyright (c) 2022-2024 GS1 AISBL.
Macros
lint_key.c File Reference

Macros

#define GCP_MIN_LENGTH   4
 Currently the shortest GS1 Company Prefix is four digits.
 

Purpose

The key linter checks whether an input starts with a GS1 Company Prefix ("GCP").

Remarks
The GCP is defined in the GS1 General Specifications section "GS1 Company Prefix".

Functional Description

◆ gs1_lint_key()

GS1_SYNTAX_DICTIONARY_API gs1_lint_err_t gs1_lint_key ( const char *const  data,
size_t *const  err_pos,
size_t *const  err_len 
)

Used to ensure that an AI component starts with a GCP.

Note
To enable this linter to hook into a GS1 Company Prefix lookup service containing a record of current GCP allocations (provided by the user) the GS1_LINTER_CUSTOM_GCP_LOOKUP_H macro may be set to the name of a header file to be included that defines a custom GS1_LINTER_CUSTOM_GCP_LOOKUP macro.
If provided, the GS1_LINTER_CUSTOM_GCP_LOOKUP macro shall invoke whatever API is defined by the user-provided GCP lookup service, then using the result must assign to locally-scoped variables as follows:
  • valid: Set to 1 if the GCP is valid (or should be treated as such). Otherwise 0.
  • offline: Set to 1 to indicate that the GCP data source is offline and the linter must fail. Otherwise 0.
Parameters
[in]dataPointer to the null-terminated data to be linted. Must not be NULL.
[out]err_posTo facilitate error highlighting, the start position of the bad data is written to this pointer, if not NULL.
[out]err_lenThe length of the bad data is written to this pointer, if not NULL.
Returns
GS1_LINTER_OK if okay.
GS1_LINTER_INVALID_GCP_PREFIX if the data does not start with a GCP.
GS1_LINTER_TOO_SHORT_FOR_KEY if the data is too short to start with a GCP.
GS1_LINTER_GCP_DATASOURCE_OFFLINE if the user-provided GCP lookup source is unavailable and this should result in the linting failing. [IMPLEMENTATION SPECIFIC]
Note
The choice of whether or not to assign offline = 1 in order to return GS1_LINTER_GCP_DATASOURCE_OFFLINE when a user-provided GCP lookup service is unavailable is implementation specific. It depends on whether the desired behaviour is to fail open (return GS1_LINTER_OK) or to fail closed (return GS1_LINTER_GCP_DATASOURCE_OFFLINE). In the case that it is desirable to fail open then in addition to assigning offline = 0 it is necessary to assign valid = 1 to avoid returning GS1_LINTER_INVALID_GCP_PREFIX, which would be misleading in the event of service outage.
96{
97
98 size_t i, len;
99
100 assert(data);
101
102 len = strlen(data);
103
104 /*
105 * The current minimum GCP length is defined by GCP_MIN_LENGTH.
106 *
107 */
108 if (len < GCP_MIN_LENGTH) {
109 if (err_pos) *err_pos = 0;
110 if (err_len) *err_len = len;
112 }
113
114 /*
115 * Any character within the minimum-length GCP prefix that is outside
116 * the range '0' to '9' is illegal.
117 *
118 */
119 for (i = 0; i < GCP_MIN_LENGTH; i++) {
120 if (data[i] < '0' || data[i] > '9') {
121 if (err_pos) *err_pos = i;
122 if (err_len) *err_len = 1;
124 }
125 }
126
127 /*
128 * Call the custom GCP lookup routine if one has been provided.
129 *
130 */
131#ifdef GS1_LINTER_CUSTOM_GCP_LOOKUP
132{
133 int valid = 0, offline = 0;
134 GS1_LINTER_CUSTOM_GCP_LOOKUP(data);
135 if (offline)
137 else if (!valid)
139}
140#endif
141
142 return GS1_LINTER_OK;
143
144}
@ GS1_LINTER_TOO_SHORT_FOR_KEY
The component is shorter than the minimum length GS1 Company Prefix.
Definition gs1syntaxdictionary.h:77
@ GS1_LINTER_GCP_DATASOURCE_OFFLINE
The data source for GCP lookups is offline.
Definition gs1syntaxdictionary.h:76
@ GS1_LINTER_OK
No issues were detected by the linter.
Definition gs1syntaxdictionary.h:66
@ GS1_LINTER_INVALID_GCP_PREFIX
The GS1 Company Prefix is invalid.
Definition gs1syntaxdictionary.h:78
#define GCP_MIN_LENGTH
Currently the shortest GS1 Company Prefix is four digits.
Definition lint_key.c:49