mirror of
https://git.code.sf.net/p/zint/code
synced 2025-12-17 18:07:02 +00:00
general: change BARCODE_RAW_TEXT to write to new zint_symbol
fields `raw_segs` and `raw_seg_count` instead of `text`, and to do so for all symbologies, using new common funcs `rt_cpy()` etc. MICROPDF417: return ECC percentage in top byte of `option_1` DBAR_EXP_STK: return `option_2`/`option_3` feedback CLI: change warning text "ignoring" -> "**IGNORED**" GUI: show feedback for DBAR_EXP_STK, MICROPDF417, UPNQR ctest: fix recent inability to run tests via "ctest" on Windows (MSVC) by using cmake 3.22 feature `ENVIRONMENT_MODIFICATION` manual: document feedback and RAW_TEXT in new "Feedback" section; rephrase some symbology descriptions test suite: new general-use arg "-a"; add `func_name` to context; new "test_bwipp" test for testing BWIPP against ZXing-C++
This commit is contained in:
gitlost
168
docs/manual.pmd
168
docs/manual.pmd
@@ -86,7 +86,8 @@ GS1 data
|
||||
|
||||
: This is a structured way of representing information which consists of
|
||||
'chunks' of data, each of which starts with an Application Identifier (AI).
|
||||
The AI identifies what type of information is being encoded.
|
||||
The AI identifies what type of information is being encoded. Many types are
|
||||
defined, the most prominent being GTIN (Global Trade Item Number).
|
||||
|
||||
Reader Initialisation (Programming)
|
||||
|
||||
@@ -2104,6 +2105,14 @@ Member Name Type Meaning Default Value
|
||||
|
||||
`memfile_size` integer Length of in-memory file (output only)
|
||||
buffer.
|
||||
|
||||
`raw_segs` pointer to Pointer to array of raw (output only)
|
||||
array of segments if
|
||||
segments `BARCODE_RAW_TEXT` set in
|
||||
`output_options` - see
|
||||
[5.16 Feedback].
|
||||
|
||||
`raw_seg_count` integer Number of raw segments. (output only)
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
Table: API Structure `zint_symbol` {#tbl:api_structure_zint_symbol tag="$ $"}
|
||||
@@ -2154,10 +2163,6 @@ detailing the nature of the error. The errors generated by Zint are:
|
||||
------------------------------------------------------------------------------
|
||||
Return Value Meaning
|
||||
----------------------------- -----------------------------------------------
|
||||
`ZINT_WARN_HRT_RAW_TEXT` The Human Readable Text returned in `text` was
|
||||
outputted as raw text (`output_options` set to
|
||||
`BARCODE_RAW_TEXT`).
|
||||
|
||||
`ZINT_WARN_HRT_TRUNCATED` The Human Readable Text returned in `text` was
|
||||
truncated (maximum 255 bytes).
|
||||
|
||||
@@ -2219,9 +2224,6 @@ Return Value Meaning
|
||||
|
||||
`ZINT_ERROR_HRT_TRUNCATED` Returned if `warn_level` set to `WARN_FAIL_ALL`
|
||||
and `ZINT_WARN_HRT_TRUNCATED` occurs.
|
||||
|
||||
`ZINT_ERROR_HRT_RAW_TEXT` Returned if `warn_level` set to `WARN_FAIL_ALL`
|
||||
and `ZINT_WARN_HRT_RAW_TEXT` occurs.
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
Table: {#tbl:api_warnings_errors tag=": API Warning and Error Return Values"}
|
||||
@@ -2339,10 +2341,8 @@ Value Effect
|
||||
`BARCODE_MEMORY_FILE` Write output to in-memory buffer `symbol->memfile`
|
||||
instead of to `outfile` file.
|
||||
|
||||
`BARCODE_RAW_TEXT` Set HRT with no decoration,[^14] complete with any
|
||||
control characters[^15] and check characters,[^16]
|
||||
and for all linear and DataBar Stacked symbologies,
|
||||
including those that normally don't set it.
|
||||
`BARCODE_RAW_TEXT` Write data encoded to raw segment buffers
|
||||
`symbol->raw_segs` (see [5.16 Feedback]).
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
Table: API `output_options` Values {#tbl:api_output_options tag="$ $"}
|
||||
@@ -2356,16 +2356,6 @@ Code].
|
||||
[^13]: Codablock-F, Code 16K, Code 49, EAN-2 to EAN-13, ISBN, ITF-14, UPC-A and
|
||||
UPC-E have compliant quiet zones added by default.
|
||||
|
||||
[^14]: In particular no parentheses will appear in the HRT for GS1 symbologies,
|
||||
and `GS` separators will be added as required. However for EAN/UPC symbologies,
|
||||
any add-on data will be separated by a `+` character as usual.
|
||||
|
||||
[^15]: Normally control characters (including `DEL`) and non-ISO/IEC 8859-1 are
|
||||
replaced by spaces in the HRT.
|
||||
|
||||
[^16]: Except for Japanese Postal Code, whose check character is not truly
|
||||
representable in HRT.
|
||||
|
||||
## 5.11 Setting the Input Mode
|
||||
|
||||
The way in which the input data is encoded can be set using the `input_mode`
|
||||
@@ -2477,7 +2467,8 @@ These are direct analogues of the previously mentioned `ZBarcode_Encode()`,
|
||||
`ZBarcode_Encode_and_Buffer_Vector()` respectively, where instead of a pair
|
||||
consisting of `"source, length"`, a pair consisting of `"segs, seg_count"` is
|
||||
given, with `segs` being an array of `struct zint_seg` segments and `seg_count`
|
||||
being the number of elements it contains. The zint_seg structure is of the form:
|
||||
being the number of elements it contains. The `zint_seg` structure is of the
|
||||
form:
|
||||
|
||||
```c
|
||||
struct zint_seg {
|
||||
@@ -2618,7 +2609,7 @@ Value Meaning
|
||||
|
||||
`ZINT_CAP_STACKABLE` Is the symbology stackable?
|
||||
|
||||
`ZINT_CAP_EANUPC`[^17] Is the symbology EAN/UPC?
|
||||
`ZINT_CAP_EANUPC`[^14] Is the symbology EAN/UPC?
|
||||
|
||||
`ZINT_CAP_COMPOSITE` Does the symbology support composite data? (see
|
||||
[6.3 GS1 Composite Symbols (ISO 24723)] below)
|
||||
@@ -2649,7 +2640,7 @@ Value Meaning
|
||||
|
||||
Table: {#tbl:api_cap tag=": API Capability Flags"}
|
||||
|
||||
[^17]: `ZINT_CAP_EANUPC` was previously named `ZINT_CAP_EXTENDABLE`, which is
|
||||
[^14]: `ZINT_CAP_EANUPC` was previously named `ZINT_CAP_EXTENDABLE`, which is
|
||||
still recognised.
|
||||
|
||||
For example:
|
||||
@@ -2669,10 +2660,45 @@ if (cap & ZINT_CAP_ECI) {
|
||||
}
|
||||
```
|
||||
|
||||
## 5.16 UTF-8 to ECI convenience functions
|
||||
## 5.16 Feedback
|
||||
|
||||
On successful encodation (after using `ZBarcode_Encode()` etc.) the `option_1`,
|
||||
`option_2` and `option_3` members will be set to the values used by Zint to
|
||||
create the barcode. This is useful for feedback if the values were left as
|
||||
defaults or were overridden by Zint.
|
||||
|
||||
In particular for symbologies that have masks,[^15] `option_3` will contain the
|
||||
mask used as `(N + 1) << 8`, N being the mask. Also Aztec Code will return the
|
||||
actual ECC percentage used in `option_1` as `P << 8`, where P is the integer
|
||||
percentage, the low byte containing the values given in Table {@tbl:aztec_eccs}
|
||||
(with the addition of `0` meaning less than 5% + 3 codewords). Micro PDF417 also
|
||||
will return the ECC percentage in `option_1` as `P << 8`.
|
||||
|
||||
Detailed feedback on the data encoded may be requested by specifying the
|
||||
`BARCODE_RAW_TEXT` option in the `output_options` member, which will populate
|
||||
the `raw_segs` member with an array of `zint_seg` structures (see [5.12 Multiple
|
||||
Segments] for the format), one for each segment specified, the size of the array
|
||||
being set in `raw_seg_count` - which will always be at least one.
|
||||
|
||||
The `source`, `length` and `eci` members of `zint_seg` will be set accordingly -
|
||||
the data in `source`, the data length in `length`, and the character set the
|
||||
data is in (UTF-8 data will be converted) in `eci`. Any check characters encoded
|
||||
will be included,[^16] and for GS1 data any `FNC1` separators will be
|
||||
represented as `GS` characters. For EAN/UPC data, add-ons will be separated from
|
||||
the main data with a plus (`+`) sign. GS1 Composite data if any will be
|
||||
separated from the primary data (including any EAN/UPC add-ons) by a pipe (`|`)
|
||||
character.
|
||||
|
||||
[^15]: DotCode, Han Xin, Micro QR Code, QR Code and UPNQR have variable masks.
|
||||
Rectangular Micro QR Code has a fixed mask (4).
|
||||
|
||||
[^16]: Except for Japanese Postal Code, whose check character is not truly
|
||||
representable in the encoded data.
|
||||
|
||||
## 5.17 UTF-8 to ECI convenience functions
|
||||
|
||||
As a convenience the conversion done by Zint from UTF-8 to ECIs is exposed in
|
||||
two helper functions (compatible with the `libzueci`[^18] functions
|
||||
two helper functions (compatible with the `libzueci`[^17] functions
|
||||
`zueci_utf8_to_eci()` and `zueci_dest_len_eci()`):
|
||||
|
||||
|
||||
@@ -2692,11 +2718,11 @@ returned in `p_dest_length`, may be smaller than the estimate given by
|
||||
NUL-terminated. The destination buffer is not NUL-terminated. The obsolete ECIs
|
||||
0, 1 and 2 are supported.
|
||||
|
||||
[^18]: The library `libzueci`, which can convert both to and from UTF-8 and ECI,
|
||||
[^17]: The library `libzueci`, which can convert both to and from UTF-8 and ECI,
|
||||
is available at [https://sourceforge.net/projects/libzueci/](
|
||||
https://sourceforge.net/projects/libzueci/).
|
||||
|
||||
## 5.17 Zint Version
|
||||
## 5.18 Zint Version
|
||||
|
||||
Whether the Zint library linked to was built with PNG support may be determined
|
||||
with:
|
||||
@@ -2729,39 +2755,38 @@ widths.
|
||||
|
||||
{.lin}
|
||||
|
||||
Developed by Intermec in 1977, Code 11 is similar to Code 2 of 5 Matrix and is
|
||||
primarily used in telecommunications. The symbol can encode data consisting of
|
||||
the digits 0-9 and the dash character (`-`) up to a maximum of 140 characters.
|
||||
Two modulo-11 check digits are added by default. To add just one check digit,
|
||||
set `--vers=1` (API `option_2 = 1`). To add no check digits, set `--vers=2`
|
||||
(API `option_2 = 2`).
|
||||
Developed by Intermec in 1977 for Bell Labs as a high-density barcode to track
|
||||
small telephone components, Code 11 can encode data consisting of the digits 0-9
|
||||
and the dash character (`-`) up to a maximum of 140 characters. Two modulo-11
|
||||
check digits are added by default. To add just one check digit, set `--vers=1`
|
||||
(API `option_2 = 1`). To add no check digits, set `--vers=2` (API
|
||||
`option_2 = 2`).
|
||||
|
||||
### 6.1.2 Code 2 of 5
|
||||
|
||||
Code 2 of 5 is a family of one-dimensional symbols, 8 of which are supported by
|
||||
Zint. Note that the names given to these standards alters from one source to
|
||||
another so you should take care to ensure that you have the right barcode type
|
||||
before using these standards.
|
||||
Code 2 of 5 is a family of one-dimensional self-checking symbols, 8 of which are
|
||||
supported by Zint. Note that the names given to these standards alters from one
|
||||
source to another so you should take care to ensure that you have the right
|
||||
barcode type before using them.
|
||||
|
||||
#### 6.1.2.1 Standard Code 2 of 5
|
||||
|
||||
{.lin}
|
||||
|
||||
Also known as Code 2 of 5 Matrix, this is a self-checking code used in
|
||||
industrial applications and photo development. Standard Code 2 of 5 will encode
|
||||
numeric input (digits 0-9) up to a maximum of 112 digits. No check digit is
|
||||
added by default. To add a check digit, set `--vers=1` (API `option_2 = 1`). To
|
||||
add a check digit but not show it in the Human Readable Text, set `--vers=2`
|
||||
(API `option_2 = 2`).
|
||||
Also known as Code 2 of 5 Matrix, and used in industrial applications and photo
|
||||
development, Standard Code 2 of 5 will encode numeric input (digits 0-9) up to
|
||||
a maximum of 112 digits. No check digit is added by default. To add a check
|
||||
digit, set `--vers=1` (API `option_2 = 1`). To add a check digit but not show it
|
||||
in the Human Readable Text, set `--vers=2` (API `option_2 = 2`).
|
||||
|
||||
#### 6.1.2.2 IATA Code 2 of 5
|
||||
|
||||
{.lin}
|
||||
|
||||
Used for baggage handling in the air-transport industry by the International Air
|
||||
Transport Agency, this self-checking code will encode numeric input (digits 0-9)
|
||||
up to a maximum of 80 digits. No check digit is added by default, but can be set
|
||||
the same as for [6.1.2.1 Standard Code 2 of 5].
|
||||
Used by the International Air Transport Agency (IATA) for baggage handling, this
|
||||
barcode will encode numeric input (digits 0-9) up to a maximum of 80 digits. No
|
||||
check digit is added by default, but can be set the same as for [6.1.2.1
|
||||
Standard Code 2 of 5].
|
||||
|
||||
#### 6.1.2.3 Industrial Code 2 of 5
|
||||
|
||||
@@ -2776,7 +2801,7 @@ Industrial Code 2 of 5 can encode numeric input (digits 0-9) up to a maximum of
|
||||
{.lin}
|
||||
|
||||
This self-checking symbology encodes pairs of numbers, and so can only encode an
|
||||
A high-density barcode that encodes pairs of numbers, and so can only encode an
|
||||
even number of digits (0-9). If an odd number of digits is entered a leading
|
||||
zero is added by Zint. A maximum of 62 pairs (124 digits) can be encoded. No
|
||||
check digit is added by default, but can be set the same as for [6.1.2.1
|
||||
@@ -2795,8 +2820,9 @@ same as for [6.1.2.1 Standard Code 2 of 5].
|
||||
{.lin}
|
||||
|
||||
ITF-14, also known as UPC Shipping Container Symbol or Case Code, is based on
|
||||
Interleaved Code 2 of 5 and requires a 13-digit numeric input (digits 0-9). One
|
||||
modulo-10 check digit is added by Zint.
|
||||
Interleaved Code 2 of 5 and is designed to encode a GTIN-14. It takes a 13-digit
|
||||
numeric input (digits 0-9), which will be prefixed with leading zeroes if less
|
||||
than 13 digits entered. One modulo-10 check digit is added by Zint.
|
||||
|
||||
If no border option is specified Zint defaults to adding a bounding box with a
|
||||
border width of 5. This behaviour can be overridden by using the `--bind` option
|
||||
@@ -2887,7 +2913,7 @@ descend below the main bars can be adjusted by setting `--guarddescent` (API
|
||||
|
||||
UPC-E is a zero-compressed version of UPC-A developed for smaller packages. The
|
||||
code requires a 6-digit article number (digits 0-9). The check digit is
|
||||
calculated by Zint. EAN-2 and EAN-5 add-on symbols can be added using the +
|
||||
calculated by Zint. EAN-2 and EAN-5 add-on symbols can be added using the `+`
|
||||
character as with UPC-A. In addition Zint also supports Number System 1 encoding
|
||||
by entering a 7-digit article number starting with the digit 1. For example:
|
||||
|
||||
@@ -3061,7 +3087,7 @@ by Zint.
|
||||
|
||||
{.lin}
|
||||
|
||||
Standard Code 39 was developed in 1974 by Intermec. Input data can be up to 86
|
||||
Standard Code 39 was introduced in 1975 by Intermec. Input data can be up to 86
|
||||
characters in length and can include the characters 0-9, A-Z, dash (`-`), full
|
||||
stop (`.`), space, asterisk (`*`), dollar (`$`), slash (`/`), plus (`+`) and
|
||||
percent (`%`). The standard does not require a check digit but a modulo-43 check
|
||||
@@ -3144,16 +3170,16 @@ required. An invisible Import character prefix `'I'` can be added by setting
|
||||
|
||||
{.lin}
|
||||
|
||||
Also known as NW-7, Monarch, ABC Codabar, USD-4, Ames Code and Code 27, this
|
||||
symbology was developed in 1972 by Monarch Marketing Systems for retail
|
||||
purposes. The American Blood Commission adopted Codabar in 1977 as the standard
|
||||
symbology for blood identification. Codabar can encode up to 103 characters
|
||||
starting and ending with the letters A-D and containing between these letters
|
||||
the numbers 0-9, dash (`-`), dollar (`$`), colon (`:`), slash (`/`), full stop
|
||||
(`.`) or plus (`+`). No check character is generated by default, but a modulo-16
|
||||
one can be added by setting `--vers=1` (API `option_2 = 1`). To have the check
|
||||
character appear in the Human Readable Text, set `--vers=2` (API
|
||||
`option_2 = 2`).
|
||||
Also known as Rationalized Codabar, Code 27, 2 of 7 Code, NW-7 (Japan), USD-4
|
||||
and Monarch, this symbology was developed in 1972 from earlier versions by
|
||||
Pitney Bowes-Alpex for retail price marking. The American Blood Commission
|
||||
adopted Codabar in 1979 as the standard barcode for blood products. Codabar can
|
||||
encode up to 103 characters starting and ending with the letters A-D and
|
||||
containing between these letters the numbers 0-9, dash (`-`), dollar (`$`),
|
||||
colon (`:`), slash (`/`), full stop (`.`) or plus (`+`). No check character is
|
||||
generated by default, but a modulo-16 one can be added by setting `--vers=1`
|
||||
(API `option_2 = 1`). To have the check character appear in the Human Readable
|
||||
Text, set `--vers=2` (API `option_2 = 2`).
|
||||
|
||||
### 6.1.9 Pharmacode One-Track
|
||||
|
||||
@@ -3219,13 +3245,13 @@ alphanumerics) are not recommended.
|
||||
{.lin}
|
||||
|
||||
It is sometimes advantageous to stop Code 128 from using Code Set C which
|
||||
compresses numerical data. The `BARCODE_CODE128AB`[^19] variant (symbology 60)
|
||||
compresses numerical data. The `BARCODE_CODE128AB`[^18] variant (symbology 60)
|
||||
suppresses Code Set C in favour of Code Sets A and B.
|
||||
|
||||
Note that the special extra escapes mentioned above are not available for this
|
||||
variant (nor for any other).
|
||||
|
||||
[^19]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is
|
||||
[^18]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is
|
||||
still recognised.
|
||||
|
||||
#### 6.1.10.3 GS1-128
|
||||
@@ -3706,9 +3732,9 @@ strcpy(my_symbol->primary, "331234567890");
|
||||
ZBarcode_Encode_and_Print(my_symbol, "[99]1234-abcd", 0, 0);
|
||||
```
|
||||
|
||||
EAN-2 and EAN-5 add-on data can be used with EAN and UPC symbols using the +
|
||||
symbol as described in sections [6.1.3 UPC (Universal Product Code) (ISO 15420)]
|
||||
and [6.1.4 EAN (European Article Number) (ISO 15420)].
|
||||
EAN-2 and EAN-5 add-on data can be used with EAN and UPC symbols using the `+`
|
||||
character as described in sections [6.1.3 UPC (Universal Product Code)
|
||||
(ISO 15420)] and [6.1.4 EAN (European Article Number) (ISO 15420)].
|
||||
|
||||
The 2D component of a composite symbol can use one of three systems: CC-A, CC-B
|
||||
and CC-C, as described below. The 2D component type can be selected
|
||||
@@ -3817,7 +3843,7 @@ first and last digit are ignored, leaving a 4-digit DX Extract number in any
|
||||
case, which must be in the range 16 to 2047. The second format `"NNN-NN"`
|
||||
represents the DX Extract as two numbers separated by a dash (`-`), the first
|
||||
number being 1 to 3 digits (range 1 to 127) and the second 1 to 2 digits (range
|
||||
0 to 15).[^20]
|
||||
0 to 15).[^19]
|
||||
|
||||
The optional frame number is a number in the range 0 to 63, and may have a half
|
||||
frame indicator `"A"` appended. Special character sequences (with or without a
|
||||
@@ -3827,7 +3853,7 @@ number 62, `"K"` or `"00"` means frame number 63, and `"F"` means frame number
|
||||
|
||||
A parity bit is automatically added by Zint.
|
||||
|
||||
[^20]: The DX number may be looked up in The (Modified) Big Film Database at
|
||||
[^19]: The DX number may be looked up in The (Modified) Big Film Database at
|
||||
[https://thebigfilmdatabase.merinorus.com](
|
||||
https://thebigfilmdatabase.merinorus.com).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user