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]	data	Pointer to the null-terminated data to be linted. Must not be NULL.
[out]	err_pos	To facilitate error highlighting, the start position of the bad data is written to this pointer, if not NULL.
[out]	err_len	The 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

When GCP lookup service is provided by the user, it will be called with strings whose prefix may be one of (1) a regular GCP, (2) a UPC Company Code normalised to a regular GCP (by prefixing "0"), or (3) a GS1-8 Prefix normalised to a regular GCP by prefixing "00000".

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.

{
 
        size_t i, len;
 
        assert(data);
 
        len = strlen(data);
 
        /*
         * The current minimum GCP length is defined by GCP_MIN_LENGTH.
         *
         */
        if (len < GCP_MIN_LENGTH)
                GS1_LINTER_RETURN_ERROR(
                        GS1_LINTER_TOO_SHORT_FOR_KEY,
                        0,
                        len
                );
 
        /*
         * Any character within the minimum-length GCP prefix that is outside
         * the range '0' to '9' is illegal.
         *
         */
        for (i = 0; i < GCP_MIN_LENGTH; i++) {
                if (data[i] < '0' || data[i] > '9')
                        GS1_LINTER_RETURN_ERROR(
                                GS1_LINTER_INVALID_GCP_PREFIX,
                                i,
                                1
                        );
        }
 
        /*
         * Call the custom GCP lookup routine if one has been provided.
         *
         */
#ifdef GS1_LINTER_CUSTOM_GCP_LOOKUP
{
        int valid = 0, offline = 0;
        GS1_LINTER_CUSTOM_GCP_LOOKUP(data);
        if (offline)
                GS1_LINTER_RETURN_ERROR(GS1_LINTER_GCP_DATASOURCE_OFFLINE, 0, 0);
        else if (!valid)
                GS1_LINTER_RETURN_ERROR(GS1_LINTER_INVALID_GCP_PREFIX, 0, 0);
}
#endif
 
        GS1_LINTER_RETURN_OK;
 
}